Formatting Documentation Directly in Comments

When VBdocman 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 three ways:

  1. Edit generated documentation
  2. Use syntax of documentation format in VBdocman comments
  3. Use macros in VBdocman comments

Edit generated documentation

This is the easiest way how to format your text. After VBdocman 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 VBdocman 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 VBdocman installation. This program recognizes one command-line argument: name of CHM project file, which is generated by VBdocman. Its extension is HHP.

Example:

"c:\Program Files\VBdocman\Templates\hhc.exe" "d:\sample\TicTacToe\Vbdoc\TicTacToe.hhp"

You can always see how the documentation is built in the template file in $vbdoc-exec-after$ macro.

HLP

HLP file is compiled from auxiliary RTF files using HLP compiler from Microsoft. So for HLP, there are RTF files generated for each topic. Find the RTF files with topics you want to modify and edit them. After that you must recompile new HLP file using hcrtf.exe compiler located in Templates directory of VBdocman installation. This program recognizes two command-line arguments:

  1. /xn
  2. Name of HLP project file, which is generated by VBdocman. Its extension is HPJ.

    Example:

    "c:\Program Files\VBdocman\Templates\hcrtf.exe" /xn d:\sample\TicTacToe\Vbdoc\TicTacToe.hpj

You can always see how the documentation is built in the template file in $vbdoc-exec-after$ macro.

 

Use syntax of documentation format in VBdocman comments

Editing generated documentation is against the VBdocman's main idea - simplifying the process of documentation creation. As mentioned above, it is necessary to edit it every time when the new documentation is generated.

The better solution is to insert formatting directives directly into VBdocman comments. But in this case you are limited to use only subset of output formats. It is because every format uses different syntax for formatting and the other one simply doesn't recognize it. (This limitation can be reduced by using macros in comments.) For example bold text is created as follows:

Format
Syntax
HTML and CHM <b>My text</b>
RTF and HLP {\b My text}

So, if you are sure that you will use only HTML or CHM format, you can use HTML syntax directly in your code. The same applies to RTF or HLP.

Example for HTML:

'**
'Returns <i>score</i> for specified turn.
'
'@rem To every turn found in decision procedure is
'assigned a score that reflects the "fitness" of
'that turn. At the end the turn with the <b>best</b> score
'is chosen.
Public Function evaluateTurn(ByVal x As Integer, ByVal y As Integer) As Integer
End Function. 

Note, this approach can be also applied to the title page text in the Options dialog.


Use macros in VBdocman comments

The best solution for formatting the text seems to be using macros directly in comments. This approach is similar to previous one, but instead of format specific directives in comments, macros are used here. 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. VBdocman 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, VBdocman comes with predefined $CODE$ and $END-CODE$ macros, that are defined in all templates and provide formatting of source code.

For more information see Using Macros Directly in Comments.


Send feedback to Helixoft
© 2000-2005 Helixoft. All rights reserved.