Using Macros Directly in Comments

The best solution for formatting the text seems to be using macros directly in comments. Macros are defined and used in templates but they can be called directly from comments as well. User can define any number of macros. Macro calls are replaced by their text during compilation. The source code using macros doesn't depend on output format, so you can use it with every template supporting given macro. Thus, e.g. for bold text the same macro is used which is defined in each template using the proper specific syntax.

Example:

This is modified example using formatting directives so that it can be used with every output format. First we need to define macro for bold text in every template. Let the opening macro for bold be $b$ and closing $bb$. In every HTML based template (HTML and CHM) define these macros as follows:

$b$ <b>
$bb$ </b>

And in every RTF based template (RTF and HLP) define these macros as follows:

$b$ {\b_
$bb$ }

Important, don't forget to type one space character after "{\b" instead of red underscore! The reason is explained bellow.

Now we can use our macros everywhere in the VBdocman comments:

'**
'Returns score 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$bb$ score
'is chosen.
Public Function evaluateTurn(ByVal x As Integer, ByVal y As Integer) As Integer
End Function. 

You can call all macros and commands provided by VBdocman, not only those defined by user. But you should be very careful and do it only when really necessary.

When defining new macros for some output formats you should realize and respect some facts related to given format. For example, tags in RTF format must be separated from following text by space. This is the reason why there is a space after every formatting macro body in all RTF based templates (only $EOL$ is implemented by the author). If you omit this space in definition, you should include space in VBdocman comment after macro call, otherwise RTF reader won't recognize it.

Note, macro usage can be also applied to the title page text in the Options dialog.

See also:

$EOL$ macro usage

$CODE$ and $END-CODE$ macros usage

Formatting Documentation Directly in Comments.


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