[Doc-SIG] Alternative inline markup

Moore, Paul Paul.Moore@atosorigin.com
Tue, 6 Nov 2001 11:54:21 -0000

From: Tony J Ibbs (Tibs) [mailto:tony@lsl.co.uk]
> Immediate off-the-cuff comments - but for inline markup usage, I think
> that's actually what one *wants*...

I agree with pretty much all of this - I'll add a few specific comments.

> Alan Jaffray wrote:
> > If you are sick enough to try::
> >
> >       ***Strong enclosing emphasis***
> >       **Strong enclosing *emphasis***
> >       *Emphasis enclosing **strong***
> >
> > then the first two will work and the third won't.
> And *that* is unacceptable (not the "sick enough" bit,
> since I don't think a user trying to apply rules they've,
> presumably, been given *is* sick!), since it is quite
> clear to a user what the second and third mean

Agreed entirely. I had to work to understand why Alan's rules made the third
one illegal. You *can* make rules which "work" (something like closest
opener is closed first), but we're back to trying to codify do-what-I-mean
rules, which is too complex for this type of application.

> > If the user expects any of them to work without consulting
> > documentation, they're foolish.
> Then count me as a fool

Me too. One of the crucial things about reST to my mind is that it should be
possible to (quickly) get enough of a grip on the rules to use them
"naturally" in normal text. A key example of this is the usage of reST in
E-Mail in this group. It isn't valid reST (normal E-Mail quoting constructs
simply don't work), but it's *very* readable, and adds useful structure to
"raw" text.

And it's *not* (quite) "standard" usage, as the standard is to use
``_underline_`` and ``*bold*`` rather than ``*emphasized (conceptually
italic)*`` and ``**strong (bold)**``. So it is "learned"...

> 3. Previous rounds of the Doc-SIG have died partly
>    because people kept trying to jam things in.
>    (which isn't to say one shouldn't try to get it
>    right, but I just get a rather uncomfortable
>    feeling).

To me, this is a serious uncomfortable feeling. I think reST *as it stands,
right now* is "just right". I'm emphatically **not** saying that it is
perfect for all application areas. But we'll break it in the attempt to
"make it better" if we go *any* further. (IMHO)

> Now, as a user I am primarily interested in producing documentation
> within docstrings. I'm also likely to use reST for producing 
> very simple HTML pages [...]

My personal goal is to get it seen as a "normal mindset" for people who want
to add a little structure to their plain text writing - wherever that may
be. If people use it "naturally", it will start turning up in the oddest
places[1]_[2]_. And the "normal" usage will tend to be marked up plain text,
read "raw".

.. [1] Docstrings being one such case. And even there, you need the
       non-reST converts to "accept" reST as raw text. I've seen
       (current) docstrings written in various forms of markup - even
       DocBook (!) - and my normal reaction is "grr - stupid markup,
       I can't read this direct from the source". The fact that I read
       E-Mails in reST *without* that reaction is a very significant
       point. (I intend to start posting in reST on other lists, to
       see the reaction...).

.. [2] Annoyingly, I couldn't recall the footnote syntax straight off
       here. And I was fairly sure I'd guess wrong. That implies to me
       that we're close to the complexity limit. (Or that I'm getting
       old :-). Interestingly, I looked through old E-Mails for example
       usage, rather than going to the spec, or even the refcard. Make
       of that what you will...
The Perl people (based on Larry Wall's thinking) tend to talk in terms of
"memes", and view ideas as existing in a space where there is some sort of
natural selection. In that context, I'd like to see reST taking over the
ecological niche currently held by ``_underline_`` and ``*bold*`` (and "oh,
heck - I don't know how to lay this out" :-)) That means that people need to
be able to use it "by example" - just looking at other people's markup, and
getting it right without manuals. Tibs' refcard is the *absolute maximum*
level of documentation that can be expected to capture this audience.

On that basis, reST is currently just about right.

My view (in summary) is: Let's just implement what we've got. It may not be
perfect, but I'll take implemented and imperfect over perfect but
theoretical any day. Heck, there are millions of people using POD, on the
sole basis that it *exists* :-)

I want a full implementation **now**. (And if I don't get one, I'll thcream
and thcream until I'm thick. [As 2 short planks. Oops - didn't mean to say
that :-)])

With the existing parser converting to XML, and the XSLT stylesheets, we're
a good way there. Once I learn XSLT a bit, I'm planning on doing a prototype
converter to LaTeX based on one of the existing XSLT stylesheets. (A
pure-Python implementation might be better, but I'm getting bogged down in
technical issues over tree walks, and as I say, I want it now...)

This went on too long. But I'm convinced - we should freeze the design now,
and work on implementation. We can't hit a moving target. (At the very
least, the DOM needs to be frozen so that work on output has a firm