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

[Garth T Kidd]

> > Please, no! :) Just think of the mess when someone re-wraps a long
> > directive and the .. markers get evenly distributed. Yeccch.
>
> You misunderstand. I'm talking about comments only, not directives.

Directives will chew everything until an outdent, but comments won't?

I'm obviously still misunderstanding.

> No, an empty comment *will* add a node to the tree.

My imagination must be cramped. Why? I mean, apart from that being the
spec. :)

> So we special-case the empty comment (== two dots &
> [optional] space *only* on the first line?) to *not* consume
> subsequent indented blocks?

Yes. Exactly.

My apologies to everyone for not making that bit clear. I was so
completely blinded by how useful an empty comment could be to outdent
that it *completely* escaped me that it was a special case and that
people would have a lot of difficulty understanding what I was
blathering on about if I didn't spell that out.

> Actually, I *was* thinking about ... adding explicit directives for
> footnotes and hyperlink targets. But I would leave the ``..
> _whatever:`` and ``.. _[whatever]`` syntax as shortcuts. Don't
> panic; read on.

Indignant panic has a certain righteous glow to it at the time. :/

> Anyhow, don't worry (yet). I'm just thinking out loud about
> interesting alternatives that *might* solve a tiny little wart,
> but possibly at the expense of introducing a much larger mole.

That's my guess. Yep.

Regards,
Garth.