[Doc-SIG] Alternative inline markup

[Alan Jaffray]

On Wed, 7 Nov 2001, Moore, Paul wrote:
> From: Alan Jaffray [mailto:jaffray@pobox.com]
> > 
> > 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 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. :-)

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

I think being able to link anything - emphasized text, class and attribute
names, other inline interpreted/tagged text - is a basic need.  I don't
think "you can't put emphasis inside strong emphasis" is too great an
inconsistency to accept to support the vast majority of nesting cases. 

> But we disagree on whether people should be able to write reST without
> reading the spec.

Actually, no, I agree with you completely on this.

What we might disagree on is whether people should be able to learn
**all** of reST without reading some documentation.

I don't intend to teach my users nesting in the two-minute rundown.
I'll tell them how to do titles and lists and links and emphasis and
literals and literal blocks and what to escape.  They'll probably
try to link emphasized text on their own at some point, since it's
a natural thing to do; it'd be nice if that Just Worked.

If I get another five minutes, I'll tell them about field lists and
tables and footnotes and definition lists and nested markup and
transitions and whatever else.

> I believe that things should be deducible from examples,
> you feel that attempting to use markup without knowing the rules is foolish.

I shouldn't have made the "foolish" comment.

What I meant was this: If you were a user and you wanted to write
emphasized strong emphasized text, and you typed ``***foo***``, wouldn't
you look at the ``***`` just a little funny and maybe wonder whether or
not it would work, and either check the docs or try it out before being
really surprised if it didn't work?

I know that I looked at ``````` a little funny the first time I used it.  
(And if you didn't raise an eyebrow at my inline literal triple backquotes,
you're far more unflappable than I am. :-) )

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

I agree.  One cool thing about more powerful inline tagging is that 
we don't have to add any more special characters.  If we want to add
substitution, or inline images, or the Spanish Inquisition, we can do
that with the tag syntax rather than more punctuation.

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

I misspoke again.  I meant "literal text", not just literal blocks.

I'd write that ``{'a':1, 'b':2}`` whether or not braces had any special
meaning, just out of habit, both for output formatting and to avoid any
problems with backquotes or backslashes.

But even with my suggestion, you can still write {'a':1, 'b':2}.  What
you can't write without escaping is::

    `{'a':1, 'b':2}`__

    __ /docs/dictionary.html

I really can't think of a common case where link text would contain
curly braces, even when you're talking about code a lot.

> > 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]_

To cover roles.  In general I was suggesting that ``:rolename:`text```
could be written as ```rolename:: text```.  However, as I wrote in my
reply to David, this is a side issue; keeping the ``:rolename:`text```
syntax wouldn't really change things.  Fergetaboutit.

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

It'd be a literal display of markup.  As the spec says:

    No markup interpretation (including backslash-escape 
    interpretation) is done within inline literals.

Anyway, summary: I think we have the same goals.  But I think the
suggestions I'm making aren't as difficult or complex as you seem
to believe.

Alan