[Doc-SIG] Alternative inline markup

[Paul Moore]

On Wed, 7 Nov 2001 15:05:39 -0500 (EST), Alan Jaffray
<jaffray@pobox.com> wrote:

>On Wed, 7 Nov 2001, Moore, Paul wrote:
>> Bold italic, in most web browsers.
>
>That's not semantics or structure, it's presentation.

You're right. Sorry.

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

Hmm. I'll have to think about this. I'm not sure I agree (that linking
anything is a basic need). I suspect that there are very few cases where
I'd try to link anything other than straight text - in fact, other than
a single word or *very* short phrase. And where I was inclined to link
something more complex, a rewrite would probably remove the need (and
simplify the text at the same time).

But I'm not sure, and my needs aren't the only ones involved.

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

I don't think that people should be able to do this. But you're offering
a two-minute rundown. What is "obvious" depends strongly on what goes
into that rundown [1]_. If nesting isn't allowed, it takes a couple of
seconds to say "nesting isn't allowed - anywhere". But if you don't say
it, I agree people might well expect it to work. It depends on what
counts as basic tenets...

.. [1] I know I'm making too much of your passing comment - I hope
       my point is still valid.

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

Possibly I would, too. But I'd rather be doing it because I thought it
was clearer in raw form, than because I wasn't sure what the effect of
the non-literal version was.

>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

Snmfrglph. Can you encapsulate the rule that makes this true in a simple
statement. David's substitutions can be easily encapsulated as "starts
with ```/`` and ends with ``/```". Are you defining a construct which
starts with ```{`` and ends with ``}`__``? If so, please clarify what it
is (I've lost context here, and forgotten). If not, what *is* the rule?

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

See above. I can't see link text containing curly braces ever. But
that's not the point - I'm not so much worried about losing the option,
as understanding what I'm losing it *for*. Consistency is high on my
list of priorities. I don't really like David's ```/subst/``` syntax,
either, because it loses the "anything in \` characters is interpreted
text" rule. (Which links don't break for me, as the rule "anything
ending in ``_`` is a link" overrides it) [2]_. I can't find a rule
matching your syntax here...

.. [2] Note - these "rules" are just my mental heuristics, not specs.

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

You may well be right. This message (yours) has certainly eased some of
my concerns, in theory. But I'd like to see:

1. Clearer definitions of the syntax rules, in the context of the
   reST spec (so I can see what are exceptions, and what fall naturally
   into the overall scheme.

2. More use cases, and examples. In context others can relate to. Your
   user example does nothing for me, as I can't see how it would fit
   into my model (marked up text documents being processed into a
   printable form, ut eradable in "raw" form as well).

3. Better separation of distinct cases. I think there is more than
   one concept being discussed at once, here...

Of course, whether you feel the need to provide for these unreasonable
demands is entirely up to you...

Thanks for keeping up with this - we seem to be getting closer.

Paul.