[Doc-SIG] Alternative inline markup

[Tony J Ibbs (Tibs)]

David Goodger saved me having to learn new syntax by disliking it...

David then wrote:
> Except for Tony's neutral note, I haven't seen any reaction to this
> construct & syntax yet (posted last week as "Inline Substitutions").

I'm still way behind on internalising all of the ways links have changed
recently, and I made a firm decision to leave this one on trust until I
could think more about it. It depends a bit on whether I can think of
reasons *I* might want to use it. I assume that the silence means that
(a) people like Paul Moore, Ueli Schlaepfer, Garth Kidd and so on are on
holiday, or (b) they don't have a great feeling either way. At which
point it becomes an executive decision...

> [Tony]
> > Immediate off-the-cuff comments - but for inline markup usage, I
> > think that's actually what one *wants*...
>
> I don't follow.

I simply meant that if one couldn't understand how inline markup worked
*immediately* (essentially by looking at it, given it *is* markup, even
if one doesn't know its *meaning*) then we're probably losing. In other
words, complex UNINTUITIVE schemes on what is legal to nest will not
work.

> > 1. We want a *simple* markup scheme, ...
> >    *Unless* Alan's scheme *does* simplify
> >    overall, that added complexity makes it
> >    a non-starter for me.
>
> Which added complexity?

Sorry - the added complexity of Alan's proposals.

> > 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).
>
> They're meant as a last resort anyhow. Substitutions provide more
> flexibility with less obtrusive markup, albeit indirectly.

...

> Substitutions (or equivalent, whatever the syntax) filled a gap in the
> reStructuredText specification. Directives allow arbitrary block-level
> structures. Substitutions allow arbitrary text-level (inline)
> structures. Without them, every time someone wants a specific new
> inline structure, they'd have to petition for a syntax change. With
> them plus existing syntax, any inline structure can be coded without
> new syntax (or with only directive-local syntax). This was the goal of
> interpreted text roles also, but roles have limited functionality and
> the syntax is obtrusive. They're most useful if the role can be
> inferred by the system.

And that's a good summary of why they should be in - as I say, I still
need to work out a use case for myself, but I'm quite prepared to trust
David until I do (that *doesn't* mean I'm thinking "oh yes, that's more
or less OK, so I'll trust David" - it means "ah - I'm not at all sure
about that, but since I don't have time to think deeply about it now,
and since David has a good track record in the past, I shall trust his
judgement is still working" (or, putting it another way, "hmm_, if I
decide I don't like this, past evidence shows David has a good chance of
changing my mind, since he's awkward that way")).

> With the addition of substitutions, I consider reStructuredText to be
> pretty much complete. There are a couple of details remaining in
> rst-notes.txt (multi-line titles, an external hyperlink mechanism with
> a finer resolution, and ``\ `` as non-breaking space), but they're not
> significant in the grand scheme.

All of which are clearly things that can be added later, so
<fx:fireworks> and celebrations!

> >        (I intend to start posting in reST on other lists, to
> >        see the reaction...).
>
> Good idea. How about adding a line to our signatures? ::
>
>     Marked up with reStructuredText: http://structuredtext.sf.net/

Ooh, sneaky. And that means someone will *have* to produce an email
mode...

> > Tibs' refcard is the *absolute maximum* level of documentation that
> > can be expected to capture this audience.
>
> Actually, I think the quickref needs to be broken up (at least
> internally) into "basic" and "advanced" parts, to make the
> introduction easier. Perhaps each construct with an advanced aspect
> should have an "Advanced Usage" subsection.

I suspect that it needs to have two forms (at least for my own sake) - a
one page form that has everything (i.e., the current thing with the
missing details added), and something more like what you describe -
which is essentially a quick tutorial as well as a reminder.

> I also want to take a good look at HappyDoc and others before
> reinventing any more wheels.

Good.

> [Tony]
> > hmm, maybe we should insist he does documentation instead of
> > coding!!!!)
>
> And how are you going to make me? Coding is much more fun!

By withholding those candy treats you ask for in the README files (how
*are* we meant to get them to you without a postal address?).

.. _hmm: or, perhaps, by egregious compliments until he gives in...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)