[Doc-SIG] Alternative inline markup

[Alan Jaffray]

On Tue, 6 Nov 2001, Tony J Ibbs (Tibs) wrote:
> 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

OK, so forbid all three.  General rule: A nested markup element cannot
be delimited by the same characters as its parent.  That's probably a
better design decision.
 
Do we lose anything?  No.  In the current spec you can't nest at all.
In the proposed spec there are happier alternatives for all three,
since ``*`` and ``**`` become mere sugar for tagged content.

The reason I said "sick" is because I don't know a semantic meaning for
"emphasized strong text" other than "the author wants to demonstrate a
case where nesting is difficult to parse". :-)  "Perverse" would have
been a more accurate adjective.

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

Nesting is a fundamental feature.  It's not going to become easier
to add it later.  It's going to become more difficult.  Meanwhile,
attempts to get around the need to add it will complicate and
clutter the language, while adding it now can simplify matters.

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

Oh, I agree entirely.  That's what I meant - URLs which contain
punctuation (such as ``/``) making them illegal directive names
don't have to be backquoted.  If we were willing to forbid ``.``
and ``:`` in directive names, this would become the *vast* 
majority of cases.  As it is, it's just a considerable majority.
It misses relative links to files in the current directory and 
mailto URLs (or other similar schemes without ``//``).

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

Really?  Some of our documents talk about Python, and some of them talk
about Perl which uses curly braces even more heavily, but I didn't think
it'd be an issue.  I would expect code fragments to be in *literal*
blocks much more often than single backquotes.

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

You still have those.  Instead of ``:attribute:`Fred``` you write 
```attribute:: Fred```.  Directives are slightly expanded to subsume
the role of roles.  And if you ever want to give that "class"
directive/role some arguments or otherwise make it more complex,
you can do that, which you couldn't with the current roles.

Alan