[Doc-SIG] Alternative inline markup

[Tony J Ibbs (Tibs)]

Alan and Paul seem to be teasing meaning out of/into the debate whilst I
sleep, but I can't resist making *some* comments...

Despite my earlier comment about complexity worries, I *do* believe that
raising issues and worrying around them causes a "language" to be
stronger, even if the result is eventually to reject the proposals -
provided one keeps a record of *why* it was rejected, of course (which
David seems to be doing for such issues).

Alan Jaffray wrote:
> 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.

Well, it's quite clear to me what the author is trying to do, if one
thinks in the final presentation terms - they presumably want a bold
italic text. Not at all unreasonable, surely, if one allows both bold
and italic?

(and yes, I *know* they're not technically indicating presentation with
*..* and **..**, but I bet most people forget that when they're actually
typing!)

In reply to Paul saying much the same, Alan responded:
> That's not semantics or structure, it's presentation.  Honestly,
> I don't mind the idea of having "bold" and "italic" tags in the
> language, but if structural purity is a goal, then we shouldn't
> treat "emphasis" and "strong emphasis" as euphemisms for "italic"
> and "bold".  If "emphasized strong emphasis" has a meaning, it's
> not a terribly important one. :-)

But worrying about it because they're *called* "emphasis" and "strong
emphasis" is non-sensible, too - would you be happier if I called them
"flurgle" and "splurgle"? Surely one couldn't object to someone wanting
to flurgle their splurgled text, for clarity? (I guess my *real* point
is that the provision of two forms is *actually* derived from the two
typographic forms. To then say that back-applying the semantic
distinction to the typographic distinction doesn't make sense may be
true theoretically, but it isn't much use in real life, in the mindspace
that people *want* to work in.)

> Nesting is a fundamental feature.

True.

> It's not going to become easier to add it later.

True, possibly (modulo experience gained in doing such things).

> It's going to become more difficult.

I don't know the innards of David's parser well enough to comment on
that, but I doubt it.
Certainly, if *I* were writing a parser for reST, and could use any tool
I like (so it would be mxTextTools, then), it would not be any harder to
add it in later on.

> Meanwhile, attempts to get around the need to add it will
> complicate and clutter the language, while adding it now
> can simplify matters.

Hmm. So far as *I'm* concerned, I can live without it - but then I'm
mostly typing, well, text. Your needs seem to be more complex, but I'm
not convinced that David's suggestions don't go a good way to coping
with them (OK, maybe not terribly well, that's for you to explain), and
they certainly extend the language about as far as I can cope with, for
now.

As to adding the ability to the DTD, so that other implementations can
do it (was that what Alan meant?) - there's a problem if the *core*
(reference) implementation doesn't handle something this fundamental - I
don't like the idea that the distributed-with-Python tool would grumble
about texts that appear to conform to the format they're meant to be
supporting - I don't think that would fly.

Hmm - I like Paul Moore's summary of backquoted markup possibilities:

>    `xxxxx`_   -  named hyperlink reference (type 2)
>    `xxxxx`__  -  anonymous hyperlink reference (type 2)
>    _`xxxx`    -  inline hyperlink targets
>    `/xxx/`    -  substitution reference
>    `xxxxx`    -  interpreted text

I'll have to keep that to hand...

Alan Jaffray wrote, in response to me:
> > 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.

Historical decision. In one thread of discussion (looking at maybe using
< and > to delimit URIs), Guido made the point that he often wanted to
write XML elements within his documentation text, and it would not be
acceptable, to him, to have to quote them. This seemed like a valid
point (heck, it was the BDFL who said it). I believe (although I can't
cite cases from memory) that there has also been a similar feeling that
*having* to quote elements of code, particularly Python code (since we
*did* start out looking at docstrings) would be a Bad Thing (it also has
the advantage that a surprising number of docstrings are probably
already close to being valid reST).

Thus we *want* people still to be able to write::

    This function takes a <paragraph> and splits it into
    a series of <line> elements. To do this, it uses a
    dictionary which is something like {nl:'\n',cr='\r'}.
    *Why* it wants to do this is beyond my ken.

You can, of course, immediately see why there was a loud argument about
whether backslash could/should be used as an escape character for reST!

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"No one trike will do everything... buy the whole set!" - Rob Hague
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)