[Doc-SIG] using the same delimiter on the left and right..

[Guido van Rossum]

> The Runoff family was a simpler variant on the TeX idea, which wanted to
> produce computer manuals, and so on. There's generally less control over
> meaning, more interest in presentation. It's not clear to me if troff
> and so on belong to the TeX family or the Runoff family.

TeX and troff are both very old and have the same amount of control
over the typesetter.  However, the TeX *language* is more flexible
(maybe too flexible) and hence could more easily beget LaTeX, which is
a member of the SGML family: it cares about meaning, not markup.
There are languages like that in the troff family too: the -man macros
(generally try to) specify meaning, not markup.  Troff lost to TeX
because it was too concerned with machine efficiency in the 16-bit
days, and restricted its language to 2-character identifiers.

> The Pod family is, maybe, if it exists, the family of marking up
> docstrings. Edward Welbourne has talked about this in an earlier email.
> Basically, the aim is to produce something more useful than plain text
> (but not of a quality to stop a technical documentor wincing), leaving
> the original, marked up, text still useful *as such*. Eddy also comments
> that if someone using (in his comment, ST) is spending too much time
> worrying about markup, then they're not spending enough time working on
> more important things.

Objection.  I'm not "worrying too much about markup".  I'm worrying
quite a lot, based upon hard-earned experience, that the heuristics of
the ST family introduce unwanted markup and drop characters that are
essential for the documentation.

> > Let's make all of our delimiters into real delimiters,
> > that can only be used for delimiting (or maybe also for
> > bullets, in the case of '*').  We could switch our "literal"
> > delimiter to "`".  So then we would have the following
> > reserved characters, that may not appear in text without
> > being quoted somehow:
> >     '<'    left delimiter for URLs
> >     '>'    right delmiter for URLs

Unneeded -- URLs can be recognized easily, and we don't have to drop
any characters when we add a link.

> >     '#'    delimiter for inlines
> >     '`'    delimiter for literals
> >     '*'    delimiter for emph, maybe for strong.

We only need one of these (emph or strong).

> >     '::'   marker for literal regions

We need an escape too.

> I hadn't thought of using backtick as a literal delimiter. In the
> context of docstrings, I can't see why it wouldn't work - hmm, this is a
> `literal` - yep, that works for me (does the resonance with Python
> backtick work?).

>From a readability perspective, I'd prefer `symmetric quotes'.

> It frees up both sorts of "normal" quote, which is
> good, and only inconveniences people like Eddy who insist on typing
> `both sorts of single quote' (TeX users, the lot of them). And it mean I
> can type "'cos" without worrying (or 'plane or 'phone if I want to
> appear old-fashioned).

Maybe it would work if the quotes were left in the output text?  That
way at least if a stray backtick is mistaken for markup, it's still
clear that there was a backtick in the docstring source.

> And if those *are* the delimiters, then it *would* work to expect them
> to be quoted when they occurred - neat. Just goes to prove why we keep
> Edward around on the list (please add a <wink> here).
> 
> Does that mean we allow things like "there is a hard-space` `here"? It
> would be quite a neat thing to allow...

This looks like horrible abuse to me.

--Guido van Rossum (home page: http://www.python.org/~guido/)