Comments

ICG Usage

• use the role :flag3: for inline comments
• use of ;; and ;;; is an inner-comment technique to allow for syntax highlighting (thus, optional)

There is one glaring problem with the `comment mechanism`__ :flag3:`note
the preceding link markup is non-conventional for ICG` provided by reST:
you cannot do inline comments as done in this paragraph's source.

There is one glaring problem with the comment mechanism note the preceding link markup is non-conventional for ICG provided by reST: you cannot do inline comments as done in this paragraph’s source.

The need to “suspend” content via inline comment, and also the need to, well, comment on inline content, is actually quite common. reST comments must begin at the current left edge context, thus only block comments are possible.

The :flag3: role is an ICG customization that supplies the missing capability. It is not a part of Docutils or Sphinx. It simply sets “display:none” (in CSS) for its contents. This is also useful because that means its contents are passed into html output. By contrast, standard reST commented matter is stripped out and does not appear in html output (view source and see what happened to the standard reST comments that appear in the last example on this page).

What’s Up with ;; and ;;;?

Within valid reST-style comments, you may see use use of ;; and ;;;. These are being used to mark the comment as a comment to be picked up by syntax highlighting.

While clever, the use of “empty” explicit markup as a comment has the problem of being hopelessly indeterminate from the perspective of syntax highlighting. Thus the use of “;” as a delimiter to make comments interpretable by the highlighter (with a nod to ICG’s history with “;” in commands and FISH).

Three semicolons (;) is for to-line-end comments (which must still
appear in a valid reST comment).

..
   + like this one     ;;; it tends to comment on the comment
   + and this line too ;;; which, though infrequent, is sometimes needed

Two semicolons are used to delimit the start and end of a comment block.

.. ;; As you can see, the block comment is formed as normal.

   It just has the semicolons in place to indicate what the syntax
   highlighter should mark as a comment ;;

The use of these is strictly optional.

Three semicolons (;) is for to-line-end comments (which must still appear in a valid reST comment).

Two semicolons are used to delimit the start and end of a comment block.

The use of these is strictly optional.

Note

As seen in the two examples above, a valid reST comment can start on the line with .. or below it. However, all matter to be commented must maintain indentation level (be spaced three characters in). The comment ends when indentation level is broken to the left.