[Doc-SIG] Alternative inline markup

[Moore, Paul]

I've said most of what I think already, so I'll keep this short (if I
can)...

From: David Goodger [mailto:goodger@users.sourceforge.net]
> [Alan]
> > Here are my suggested changes to the current inline markup system.
> 
> Thanks for your input. I wish it had come earlier though! If you've
> been following the \*-checkins lists, you've noticed that I've already
> written the specs and checked in the implementation of::
> 
>     Substitutions: `/text/` `/picture/`.
> 
>     .. /text/ If you're happy and you know it
>     .. /picture/ image:: clapping_hands.png
> 
> Except for Tony's neutral note, I haven't seen any reaction to this
> construct & syntax yet (posted last week as "Inline Substitutions").
> Alan?

I didn't comment, mainly due to lack of time to think about it, and lack of
any real motivation to *use* it. Some comments:

1. I'm not keen on the overloading of the \` character in the syntax.
   Substitutions look like interpreted text. For some reason, hyperlinks
   don't have this problem, even though they reuse the \` character as
   well. Maybe some form of postfix notation would help for
   substitutions, as well? [1]_

2. I'm not 100% clear on the semantics, either. To my mind, pure text
   substitutions are a bad thing - put the text inline instead. Otherwise,
   you are making the marked up text *less* readable. `/swim/`? And the
   semantics of anything else is effectively output-processor dependent.
   Generally, I'm against any markup which makes my text output dependent.
   Even your image example (the least contentious possibility for this sort
   of thing) may not be renderable in certain output formats (ASCII text,
   for instance!!!).

3. Overall, I'd like to see clearer examples of what all this could be
*for*.
   Your example of interpreted text roles in Python documentation (can't
recall
   where I saw this - things like ``:class:`zipfile``` and
``:variable:`filename```
   to distinguish types of identifier). I'd like to see a "motivation"
section,
   with more of this sort of example.

.. /swim/ See what I mean

.. [1] Actually, having used the syntax in my example above, I find I quite
       like it. But point (2) still stands - it's not clear (to me) that
       the construct is *useful*.

> >    If the user expects any of them to work without consulting
> >    documentation, they're foolish.
> 
> With a little bit of experience, I'd say such expectations would be
> common. Nested inline markup should be obvious and orthogonal in the
> general case, or nonexistent.

And in my view, the corner cases kill the possibility of obviousness, so I
vote for nonexistent.

> I've asked this before, and I really would like to know: what does the
> "lj" tag *do* in the end? Can you show us some HTML output?

That gets back to my point - what's the motivation? And for me, I'd like to
see more than just HTML output. What would such a document show in
PDF/PostScript intended for printing? (If the answer is "you don't use it in
that context", then we're getting too domain-specific).

> > 5) Roles can go away.  We don't need them.  Optionally if we want
> >    the ability to put short directive names inline, we could
> >    declare ::
> > 
> >       `foo:: bar bar bar`

The example::

    :class:`zipfile`

is, to me, a telling argument in *favour* of roles. I can see the point, it
reads clearly in markup form, and I can imagine output formatters rendering
class names specially (or putting them in an index, or whatever).

Of course, getting that level of flexibility in the output code is the next
exciting step... :-)

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

What I understood Tony to mean was that if you had to stop and think about
it, it wasn't clear and simple enough to be what we want.

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

OK, that sounds like a killer argument for substitutions. And the converse
is, that *any* request for extra features should be addressable with "use a
(substitution|directive)". If not, then we need to rethink these constructs,
to understand why they aren't doing their job properly.

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

Hmm, by my own argument, that implies that roles should be *replaced* by
substitutions. Maybe the fact that they can't means that there is still
something to address here. Substitutions don't take "parameters" (the
interpreted text part of a role). Roles don't have the "supplemental
information" (the directive-like bit in the ``..`` section - I don't know
what to call it) that substitutions do.

> I agree with the sentiment, but even if the parser is frozen the
> document tree model is still subject to change. Its functionality is
> only construction-oriented (parser) now; as you well know, there's not
> much support for transformations, tree walking, and whatever else
> output needs.

Sorry - that's actually closer to what I was trying to say. Freeze the
parser (and hence, certain key parts of the document tree model, like what
types of node exist - effectively the DTD side of it), and work on the other
parts. With the document tree at the centre of it all, there's no way you
can completely freeze it when only one of its "clients" has been frozen.

> > Hmm - should we aim for a formal release (alpha? beta?) early in
> > the new year? From here it looks doable...
> 
> If it's ready, we will. I won't commit any further than that.

No commitment, but it sounds like a worthwhile target to aim at.

-- 
Paul Moore (paul.moore@atosorigin.com)

Marked up with reStructuredText: http://structuredtext.sf.net/