##### 37.1.1.5 Including comments in macro definitions

Any line in a macro definition that starts with a semicolon (;) is treated as a configuration-file comment, even lines that would otherwise execute system commands:

    [SomeMacro]
    ; This entire line is a comment, and so is the next:
    ; jhjar <$$currpath>\help ugdita2go
    ; But the following line will be executed:
    jhindex <$$currpath>\help html

Normally, a line that starts with a semicolon in a macro definition does not appear at all in the output. If you do want such a comment to appear in the output, as itself, escape the semicolon with a backslash:

    \; my macro comment

When you do this, you get the backslash character in the output, which appears to be wrong based on the rule for escaping characters (see §37.1.1.3 Escaping special characters in macro definitions). However, using two backslashes “\\;” also results in “\;” in the output, which is correct.

There is a reason for this odd behavior. Macros can be nested, and it is desirable to avoid multiple escaping that depends on the nesting level. If the original backslash went away, and the macro was nested inside another macro, the comment would disappear on the next evaluation, unless you used “\\\;”; and if the macro was nested two deep you would need “\\\\\\;”, which starts to become user unfriendly. Keeping the single backslash avoids all that, but it can cause astonishment.

What you do not get in the output is an HTML comment:

    <!-- my macro comment -->

If that is what you want, put the comment in your macro using HTML comment syntax, exactly as you want it to appear in HTML output.

Previous Topic: 37.1.1.4 Managing line breaks in macro definitions

Next Topic: 37.1.1.6 Obtaining RTF code for macro definitions

Parent Topic: 37.1.1 Defining macros

Sibling Topics:

37.1.1.1 Understanding what a macro definition can include

37.1.1.2 Understanding where you can define named macros

37.1.1.3 Escaping special characters in macro definitions

37.1.1.4 Managing line breaks in macro definitions

37.1.1.6 Obtaining RTF code for macro definitions

Table of Contents • Index