[Doc-SIG] More on directives and comments

[Tony J Ibbs (Tibs)]

Sorry for lack of proper references in the following - I just want to
write a quick note before I forget it.

I (think) I agree with Garth that directive forms of target links would
be overkill. I also think it would be difficult to do (he was worrying
about "over the top" tendencies to consistency - I *think* he's
overworrying?). So I'd vote for targets being targets and directives
being directives. I can drum up reasons if I have to, but I'll only
bother if it seems needed...

I think he and I will have to disagree about how obvious and natural it
is that::

	.. Some text which has two dots at the start

is a "comment" (if reST is *meant* to be human-readable in the "raw",
with as much status for that form as for any post-processed form, then
the idea of a "comment" is odd enough that it definitely wouldn't come
to mind as the first thing I'd think of! - I'd assume it was meant to be
an introductory ellipsis with a dot left off).

Luckily, stylistic decisions are best made by a "leader" who takes
comments on board and weighs them up - so either David, or (in ultimate)
Guido, I guess. I'll still argue for::

	.. comment:: This is a comment, obviously

*But* I would argue that there is an advantage to be had in defining one
(exactly one, count them!) directive in the reST spec itself.

Directives are meant to be uncommon, things one doesn't normally need.
So one doesn't really want any in reST, because that would imply that we
have missed something that is *not* uncommon. On the other hand, if
there is a construct that can be used "properly" in reST, there should
be a decent example.

I would contend that comments are this uncommon but, at the same time,
sensible to have in reST, example.

As I've said before, comments are *not* something one would normally put
into (for instance) docstrings - one doesn't *normnally* embed metadata
in text that is to be read "as such" (well, maybe some of us do, but
then maybe we're odd, and we probably talk to ourselves as well). So
comments are "uncommon" in that sense - not an everyday event.

But clearly there is (at least some) demand for them - citing setext's
provision for them, Garth seems to like them, David kept them in, and
even I've used them in my notes on the specs.

Which means that using them as our canonical example directive is a Good
Thing - not least because it lets us find any "bugs" in how we're
defining directives.

(there, David, another argument in favour! <fx:small child>are we there
yet?)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)