[Doc-SIG] Alternative inline markup

[Tony J Ibbs (Tibs)]

Immediate off-the-cuff comments - but for inline markup usage, I think
that's actually what one *wants*...

Alan Jaffray wrote:
> 1) Inline markup can be nested:

OK - not a bad idea in and of itself, but we *do* know it can be
difficult to work out the implications.

> 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
(so they are the ones that *must* work), whilst the first is ambiguous
(and thus the one I could cope with not allowing - although in fact it
doesn't matter in many cases whether it is strong emphasis or emphasised
strongness, so the user won't care, so it's easy to special case).

    As with other facets of reST, I believe that what we
    *want* should come before the implementation choice
    - David (and Edward before him) have argued this
    very cogently in the past.

I'd still vote for leaving nested inline markup as a "possible future
enhancement" - not having it gets us some large percentage of the way to
a perfect tool, and *definitely* leaves us with a *usable* tool (for the
vast majority of cases).

> If the user expects any of them to work without consulting
> documentation, they're foolish.

Then count me as a fool (heh, do I get a hat with bells on?), since (as
I say) I regard the last two as perfectly obvious in meaning, and the
first one as castable either way without mattering.

I'm mostly leaving the other items alone for now, since they actually
require more thought, except to say:

1. We want a *simple* markup scheme, so it is easy to
   learn and easy to remember (all of). I think David's
   latest suggestion about quoted slashmarky things
   (about which I am undecided) is pushing the very
   edge of that. *Unless* Alan's scheme *does* simplify
   overall, that added complexity makes it a non-starter
   for me.

2. We do *not* have to get the whole thing right at
   the start, so long as any extensions/additions
   can be carefully added at a later stage. For this
   sort of purpose, having things like directives,
   roles, and so on, is a *good* thing - they allow
   one to extend without changing the format.
   (i.e., losing roles isn't necessarily such a
   good thing as it sounds).

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).

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 (not *much* simpler than the sort I normally produce, mind
you!), and for providing a neat way of integrating text and doctest
outwith Python files. The first and last of these uses *require* reST to
be readable easily in the raw form (one of the Main Precepts). None of
these uses require complicated substitution schemes (so I am doubtless
not the best person to comment on them positively!).

Because I'm not target audience for Alan's changes, and because I *am* a
different audience who doesn't particularly want them, I'd want a lot
more explanation of *why* they are valuable to him, particularly taking
into consideration the read-as-raw issue.

And I would want a *very* good usage case for Alan's item 3, where he
has a table whose contents is *very* hard to discern!

Random other notes:

Having to quote things because they "happen" to be a directive is not a
good idea, since directives are not predictably named (i.e., one cannot
easily tell which directives may exist at a given time). David has used
punctuation to discriminate in the places where such a thing might be an
issue, previously.

Having to quote { and } in Python-related text is surely a non-starter
(heck, we don't want to have to quote < and > because one might have to
talk about *ML elements, so not being able to backquote dictionaries is
*surely* out).

Roles are supremely useful in Python docstrings, where one wants to
qualify :class:`Fred` as opposed to :attribute:`Fred` (to use them
incorrectly - but that's another argument). A more complex scheme for
doing this is *not* a good thing (and splattering the information about
the document is "more complex").

Eagerly awaiting David's comments...

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"I'm a little monster, short and stout
 Here's my horns and here's my snout
 When you come a calling, hear me shout
 I will ROAR and chase you out"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)