Common Desktop Environment: Help System Author's and Programmer's Guide

Including Comments and Writer's Memos

Frequently it is useful to include within your source files comments that are not intended to be part of the help text. Text marked with the comment element is always ignored by the HelpTag software. Comments can be used to make notes to yourself or to another author, or to exclude some markup without taking it out of the file.

In addition to standard comments, HelpTag also provides a <memo> element for entering writer's memos. Memo notes appear in your help topics during reviews, but not when you make your final help files. Authors commonly use the <memo> element to write questions or make notes to reviewers.

To Insert a Comment

    Use the comment begin marker (<!--) and end marker (-->) as shown:

<!-- text here is completely ignored --> 

The HelpTag software ignores all markup between the <!-- and -->. A comment cannot be nested within another comment.


Here's an example that has two comments, a line before the paragraph, and a single word within the paragraph.

<!-- Here is my rough draft of the introduction: --> 
 Welcome to my application. This software
 is <!-- perhaps --> the fastest and most
 efficient software you'll ever own.

To Insert a Writer's Memo

    Use the <memo> element as shown:

<memo> text <\memo>  

By default, the text within the <memo> element is ignored by the HelpTag software (just like a comment). However, if you add the memo option to your helptag.opt file (or specify the memo option with the dthelptag command), all memos within your help volume appear in a bold font.


Suppose you are writing about your application and have a question for the project team. You can include the question within the text using the <memo> element like this:

<memo>Team: Will the product also
 support 32-bit characters?<\memo> 

If you process the help volume with the following command (or include memo in your helptag.opt file), the memo appears in the help text in a bold font.

dthelptag  volume  memo

If the memo option is not used (or the nomemo option is used), the text within the memo is ignored and does not appear in the help text.