Help & Manual (H&M) is a help authoring system which can be used in conjunction with VSdocman. There are several benefits when you generate API documentation to H&M format first and then you publish final documentation in H&M.
•With H&M you can generate some additional output formats not supported in VSdocman, e.g. PDF and old Winhelp (.hlp).
•H&M is one of the leading help authoring tools on the market. Many companies already use it for general purpose documentation. So it is natural to unify the creation of API and end-user documentation.
The recommended way of authoring with H&M is to create one master documentation in H&M. Then you generate API documentation with VSdocman and include it into the master documentation. This needs to be done only once. After that, you can generate API documentation with VSdocman any time, without need to open H&M. When the help is ready to be published, just open master document in H&M and publish it. VSdocman already comes with preset master documentation. It is located in Templates\HaM\MSDN_master_project\MasterProject.hmxp. It contains detailed instructions how to use it.
This master documentation and API documentation generated by VSdocman look like MSDN library and contain live links to members in MSDN. Moreover, if published as VS help (.HxS), it supports F1 context help. You will need Help & Manual Professional 5.0.5 or higher. Your final documentation will consist of two parts:
1.General info such as Introduction, use cases, license info, company info etc. This part can be generated also by VSdocman but you will probably create it in H&M. The master project contains mentioned topics.
2.API documentation. This is generated by VSdocman and included in this master project as sub-project under its own chapter.
Viewing
After you generate H&M documentation you can view it by pressing Show Documentation button on compilation dialog. This opens H&M with your generated documentation. If you want just test the API documentation, this is OK. If you want to test whole master documentation, you need to open the master project in H&M. It will automatically contain also your API sub-chapter. When the project is loaded in H&M, you can test it by publishing in one of available formats, e.g. CHM. See Reference - Publishing Formats in H&M help for detailed information. |
Deploying
There are no special requirements regarding deployment of most output formats. See Reference - Publishing Formats in H&M help for detailed information. There is one exception - Visual Studio Help (Help2). Deploying Help2 (Visual Studio help)H&M generates correct Help2 (.HxS) file. When you publish VS help output in H&M, this file is registered under specified namespace as title. But that's all. Even Document Explorer which automatically opens after publishing is empty. You need to correctly register your help to see it in VS help, whether on your or other computer. VSdocman automatically generates all necessary files to create help collection that can be registered in VS help with its own TOC, Index and filter. There is also registration utility HelixoftHelpReg.exe with preconfigured batch scripts to register the help. Follow the steps below to generate and register VS help. 1.Make sure the Help title of your master project is the same as the documentation title of included API sub-project. It is usually VS project name. You can set it in Project Explorer - Configuration section - Common Properties - Title & Copyright. 2.Make sure that generated .HxS file is named exactly as the Help title. It should be in the form VS_PROJECT_NAME.hxs. You can set it in Publish Help Project dialog in Output File field. 3.VSdocman generates all required files in OUTPUT_DIRECTORY\Help2 directory, where OUTPUT_DIRECTORY is output path specified in VSdocman options. The .hxs file generated by H&M needs to be placed in that directory. You need to copy it there manually or set Output file in H&M mentioned in previous step directly to that directory. 4.Now you have all the files in Help2 directory. H&M already registered .hxs help under specified namespace during publishing. The settings were slightly different than you need. So it is recommended to unregister first. Just run unregister_PROJECT_NAME.bat. Now you can register, view and deploy your help as described in VSdocman help in Viewing and Deploying Documentation - View and Deploy Help 2 Documentation. In short, you need to deploy complete Help2 directory. To register the help, just run register_PROJECT_NAME.bat. To see the help, you need to close Document Explorer and Visual Studio. Then reopen Visual Studio and open VS help. Your documentation should be visible in TOC and Index. |
Distribution Policy
You can distribute your documentation with HelixoftHelpReg.exe utility only if you are registered user of VSdocman. You cannot distribute HelixoftHelpReg.exe if you are using evaluation (trial) or beta version of VSdocman.
Registered users can distribute HelixoftHelpReg.exe royalty-free but only with documentation generated by VSdocman or with documentation which contains parts generated by VSdocman.
