[Doc-SIG] Alternative inline markup

[Moore, Paul]

From: Alan Jaffray [mailto:jaffray@pobox.com]
> 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.

That makes the nesting rules dependent on the markup characters involved.
That's a *very* odd distinction to make - it implies that there is an
argument for changing the markup for strong text to, say ``!strong!``, as
that makes it nestable (!!).

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

We lose consistency, which is what I am arguing is crucial.

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

Bold italic, in most web browsers. That's not to say I feel the need to
support it, but it's a *perfectly* sensible thing.

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

I probably agree here - nesting is a fundamental issue. It's just that I
disagree that that fact makes it necessary to support it. On the contrary,
I'd say that lack of nesting is a distinguishing, simplifying, feature of
the design.

You can't get around it - the language doesn't support nesting, and unless
that is changed, it means that it simply isn't *possible* to use emphasized
strong text in reST. More relevantly, it means that you can't emphasize
parts of a hyperlink. This is a more realistic requirement, but I *still*
don't see it as so earth-shattering that we have to accept either
inconsistent or complex nesting rules (all options I've seen so far are one
or the other of these...) just to support it.

> > Having to quote things because they "happen" to be a 
> > directive is not a good idea, since directives are not
> > predictably named
> 
> 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 ``//``).

Regardless of the actual rules, there's still the restriction that certain
things *require* quoting, where others don't. Inconsistency again. In fact,
making the special cases rarer is arguably worse, as it makes it less likely
that people will remember the exceptions.

But we disagree on whether people should be able to write reST without
reading the spec. I believe that things should be deducible from examples,
you feel that attempting to use markup without knowing the rules is foolish.
(I hope I didn't misrepresent you - I'm not trying to argue that your
position is wrong, just point out that we have differing perspectives).

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

Agreed (about use of literal blocks), but I think keeping the special
characters to a minimum is an important goal. In particular, code becomes
unreadable if it needs *any* escaping at all. ("Is that markup, or am I
supposed to type that?") And while braces-as-delimiters are probably only
seen in literal blocks, it's quite reasonable to talk about dictionaries
(ie, {'a':1, 'b':2}) inline...

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

I thought that interpreted text (ie, anything in \`...\`, with the exception
of substitutions and hyperlinks, which have extra delimiting characters) was
entirely application-defined. You seem to be suggesting some standard
interpretation of the contents to cover attributes. [1]_

.. [1] By the way, you do realise that in advocating nesting,
       you are making the construct::

           ```attribute:: Fred```

       which you just used, illegal? (Or at least different.)
       At the moment it is a literal display of markup. What would
       it be with nesting? Or is \`\`...\`\` [2]_ another example
       of an exception to the nesting rule?

.. [2] Boy, it's hard to discuss markup using marked up text...

Paul.

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

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