[Doc-SIG] Comments on the reST specification - comments

[Garth T Kidd]

One thing I keep forgetting to point out with regards to directives is
that I expect the application to run the [non-argument] contents through
the parser again, hence ``sidebar::`` as my canonical example. It could
just as easily be ``pagefooter::`` or ``pullquote::``.

I think comments might also end up run through the parser sometimes. If
I were using reST as my markup of choice for a collaborative document
development system, document consumers wouldn't want to see comments but
fellow authors probably would.

Thinking of this has also reminded me of a use for marking text with
directives: annotations. There's a whole snake-pit of issues in there,
though, and unless paragraphs get obscenely long the next best thing is
a normal directive. [1]_

.. annotation:: gtk
   ... or maybe not.

Hmm. Y'know, I have a sneaking suspicion that to make things easier for
authors someone would end up using author ids as directive types...

Regards,
Garth.

.. _[1] This might be a limitation that makes the implementation
   a lot more useful. Microsoft Word's annotations are a complete
   pain because you can't view them inline, which makes sense
   because their "position" is an arbitrary text selection. If an
   annotation can only be put between paragraphs, viewing them
   inline is a *lot* easier.