>> Mike Orr wrote:
>>> .. __foo: foo2
>>> Does not appear, although in an earlier version of docutils it
>>> caused a target without reference error.
> David Goodger wrote:
>> Hmmm, it should still.
> (I just got a little scared because I thought the anomymous target
> syntax has broken and wondered how it got through the tests. :-))
> But no, ".. __foo: foo2" is just invalid reST syntax. An correct
> anonymous target would be ".. __: foo2" or "__ foo2". The parser
> recognizes ".. __foo: foo2" as a target with the name "_foo", but it
> should probably throw an error. I added this to BUGS.txt.
Yes, this should be caught as invalid. An intentional leading
underscore should be backquoted:
However, the point Mike made, and that I concurred with, was that
unused targets used to throw system messages (probably INFO-level).
>>> __ foo
>>> Appears as a literal <p>foo</p>.
>> The literal block should have been inside a system message,
>> something like "Anonymous hyperlink mismatch: 0 references but 1
> No, it shouldn't. There can be many unused targets ("5 references
> but 10 targets"), so you can't insert just one of them as a literal
> block. And there could also be more references than targets.
Right, my mistake. I wonder why Mike saw a literal block.
>> Mike, do you normally learn by trial-and-error? There *is*
>> extensive documentation, at all levels from quickref to spec. ;-)
> The fact that Mike learns by trial-and-error suggests that the
> documentation needs improvement. And I think it does indeed.
Documentation *always* needs improvement.
> The reST spec could use an overhaul for example.
I have to disagree here though. The spec is just that: a
specification. It should not be used as a tutorial or intro. In
fact, it begins with the following:
This document is a detailed technical specification; it is not a
tutorial or a primer. If this is your first exposure to
reStructuredText, please read `A ReStructuredText Primer`_ and the
`Quick reStructuredText`_ user reference first.
If we need to expand on one of those, or add another doc, I'm all for
it (but I have no *time* to do it :-( ). The spec works just fine as
it is, AFAICT. If you have some specific ideas for improvement,
please spell them out, but don't just criticize without backing up
David Goodger <http://python.net/~goodger>