Full Comment Declarations

The comments that you see at the beginning of easy-to-read DTDs are full comment declarations. They start with <-- and end with -->.

---

Tip:  
Don’t confuse -- (used in comment declarations) with - - (used to indicate minimization of open or close delimiters).

---

In the following full comment declaration, the delimiters do not appear on the same line:

 <!--This is a comment. You can put any sort of symbol you like in here,
 within reason, because the parser ignores everything between the first
 comment symbol and
 -->

The style of comment above, where the delimiters do not appear on the same line, works best in the middle of a DTD between groups of declarations, or in the middle of a declaration that requires special explanation. This example comes from listing 12.2:

                   <!-- Attribute Definition Lists -->
 <!-- As this document type definition is intended for basic SGML
         documents, in which the LINK features are not supported, it was
         necessary to include link attributes in the definitions.
 -->

Although full comment declarations like this one certainly are acceptable, they sometimes are not as striking as they need to be, as at the beginning of a DTD, for example. The following comment is better when you need to grab the reader’s attention:

 <!--***************************************************-->
 <!--  Here’s another example of a comment line.        -->
 <!--  Each line begins and ends with a                 -->
 <!--  delimiter; there is little chance of mistaking   -->
 <!--  this text. You can also add more formatting by   -->
 <!--  using white space and headings, such as          -->
 <!--                                                   -->
 <!--                                                   -->
 <!--  Heading here:                                    -->
 <!--                                                   -->
 <!--               Heading info here                   -->
 <!--                 (more heading info)               -->
 <!--                                                   -->
 <!--                                                   -->
 <!--                      And then,                    -->
 <!--                      when you’re finally ready,   -->
 <!--                                                   -->
 <!--                                                   -->
 <!--                                                   -->
 <!--  You can come back to your original format        -->
 <!--  as though nothing different happened             -->
 <!--  because as far as the parser is concerned,       -->
 <!--  nothing did happen.                              -->
 <!--***************************************************-->
 <!--***************************************************-->

As far as SGML is concerned, you may use whatever special symbols you like—asterisks, pound signs, and equal signs—between comment delimiters as long as they are part of the ASCII character set.

---

Tip:  
You can combine both ways of making full comment declarations in one DTD. For single-line comments, use delimiters at the end of each line. When you need to write a quick paragraph of explanation, use one <-- on the top line and one --> at the end of the bottom line.

---

Stay away from an accidental close delimiter that SGML might react to in your comments. For example, if you write:

 <!--  Don’t say --> inside a comment line, ‘cause      -->
 <!--  that could get SGML all confused and bothered    -->

the result might be an error message. Be careful about what you place between comment delimiters.

Inline Comments

Use inline comments when you need to say something within another declaration. They come in handy when you want to leave a hint about a content model. For example:

 <!ELEMENT  book   - -  (chapter|frontmtr) -- no bakmtr -->

This comment refers the user to another DTD or a DTD fragment:

 <!ELEMENT comment - -  (%stuff;)    -- see common DTD ref-->

An inline comment is a quick note—sometimes a reference to another source of information. If it’s more than a quick note, you should make a full comment declaration instead.