[Doc-SIG] Comments on the reST notes

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> > notes:`Horizontal rules`_
> >
> >     The solution is to introduce them into a mode specifically for
> >     producing HTML documents, and leave them out of other modes
> >     (since other modes may also be used for producing other sorts of
> >     output format).
>
> reStructuredText is not a page layout language. I'm reluctant to add
> these, at least for now.

Oh, by no way should they be in "plain" reST - but I would advocate
support in (for instance) the HTML-preparation mode of reST (indeed, I
do, and that is the correct place for it).

> > notes:`Parser notes`_
> >
> >     Incorrect indentation should:
> >
> >     a) generate a warning (level 1?)
>
> I'm thinking that I'll leave it alone. There's nothing preventing a
> block quote from containing another block quote. We shouldn't prevent
> a block quote from beginning with a nested block quote either.

Hmm - so one allows::

    This is some text.

            This *looks* like it might
            be indented wrongly, but...

        ...in fact this blockquote is
        OK, so it isn't.

Does that "fall out" ok with your current parser? If this *is* allowed
(and, as you say, it does make sense) then I think that the "proper"
reST documentation should make a note that it will work, in the section
on blockquotes.

> >     Note that use in "batch" environments (such as Wikis) will alway
> >     require a reasonable best guess, since they produce the visible
> >     documentation (HTML) from the internal format, and there is no
> >     author to ask if that internal format is in error.
>
> But surely the author gets a chance to correct their input? I'm going
> to leave the "guessing" out for now; others can add it later if it
> proves necessary. I want reStructuredText to be as deterministic as
> possible all on its own.

Ah - different assumptions.

You're assuming that the "author" gives a toss - that they come in to
edit a Wiki page (for instance) and actually bother to read it
afterwards to make sure it makes sense. I bet this isn't always so.

I'm assuming that the reader should be given a chance to make sense out
of what a poor author wrote, by use of some simple heuristic, even
whilst flagging the text as in error. Of course, your comment on block
quotes above may remove much of the reason for this.

As to determinism - my prototype had such "guessing" built in, but the
documentation declared it up front, and after guessing the output
formatter could flag it as "guessed - maybe wrong". Which is all I'm
asking for.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)