When VSdocman parses user comments, it copies the text from tags into resulting documentation. Usually, there is only a plain text without any information for formatting and in most cases it is satisfactory. However, there is still a possibility to format the text. You can customize the output text in several ways:
1. Use XML formatting tags or Comment editor
If you are using XML comments, you can directly use built-in formatting tags <b>, <i>, <u>, <code>, <c>, <font>, <see>, <list> or <img>. The easiest way is to use WYSIWYG comment editor which automatically creates correct comments. |
The following steps are only useful if the XML formatting tags are not enough for you.
2. Edit generated documentation
This is the easiest way how to format your text. After VSdocman generates the documentation, user can edit it in favourite external editor. It is good if there are only few changes, because changes must be done every time when the new documentation is generated. Generated documentation is located in the output directory as specified in VSdocman options. RTF and HTML For RTF and HTML format this process is quite straightforward. Just edit desired files in your RTF or HTML editor. CHM CHM file is compiled from auxiliary HTML files using CHM compiler from Microsoft. So for CHM, there are HTML files generated for each topic. Find the HTML files with topics you want to modify and edit them. After that you must recompile new CHM file using hhc.exe compiler located in Templates directory of VSdocman installation. This program recognizes one command-line argument: name of CHM project file, which is generated by VSdocman. Its extension is HHP.
You can always see how the documentation is built in the template file in $vbdoc-exec-after$ macro. The best way is to uncomment the third line in this macro which creates execAfter_bak.bat file in your output folder which you can study later. Help 2 Help 2 files are compiled from auxiliary HTML files using help 2 compiler from Microsoft. So for Help 2, there are HTML files generated for each topic. Find the HTML files with topics you want to modify and edit them. After that you must recompile new CHM file using HxComp.exe compiler located in your VS SDK directory specified in Environment Options. Here is the syntax of HxComp.exe (you must have VS SDK or VSHIK installed to see this help). You can always see how the documentation is built in the template file in $vbdoc-exec-after$ macro. The best way is to uncomment the third line in this macro which creates execAfter_bak.bat file in your output folder which you can study later. |
3. Use macros in VSdocman texts
The better solution for formatting the text seems to be using macros directly in comments. The source code using macros doesn't depend on output format, so you can use it with every template supporting given macro. End of line The most common requirement for formatting the text is the ability to insert new line in the resulting document. VSdocman comes with predefined $EOL$ macro, which provides inserting of new line. Source code block You often want to insert source code samples in the resulting document. Therefore, VSdocman comes with predefined $CODE$ and $END-CODE$ macros, that are defined in all templates and provide formatting of source code. Font formatting There are several predefined macros for formatting the text:
As already mentioned, all of this can and should be achieved by XML tags. So only use macros for functionality that isn't possible with XML tags. Define your own formatting macro in output templates and then use it in your comments. |
