[Doc-SIG] nesting (was re: reStructuredText inline markup)

[David Goodger]

[Alan]
> In the current reStructuredText specification, inline markup can't
> be nested and is not extensible. IMHO this is a problem.
> 
> Nesting is needed in some very simple cases::
> 
>     Most recent interpretation of the Second Amendment has been
>     based on `*USA vs. Miller* (1939)`__.
> 
>     __ http://caselaw.lp.findlaw.com/scripts/getcase.pl?
>        court=us&vol=307&invol=174

BTW, the ``__`` syntax is now implemented. There have been some changes to
the doc tree though: "reference" replaces "link", and "target" now uses a
"refuri" attribute to hold what used to be data (the data is now used for an
inline target).

> I'm not sure about nesting. Some cases are easy, but any time you
> have two constructs that involve backquotes, problems will ensue
> because backquotes don't nest. But backquotes are a really nice
> unobtrusive delimiter for sections of text, and it'd be a shame to
> replace them with braces or angle brackets or something. I have some
> bad ideas. Anyone have some good ideas?

[Ueli]
> I'll keep out of this battle -- but you should find plenty of material
> in the archive.

[Alan]
> The only comments I can find, searching on "nested inline doc-sig"
> or "nested inline restructuredtext", are David's remark of "that way
> lies madness" with no explanation and Tony's note that it'd be a
> pain to implement and he wasn't certain how important it was.

You didn't look back far enough, and your search may have been too
specific (try searching for only "nest"). Try, for example, Ed Loper's
2001-03-21 post, which details some rules for nested inline markup. I
think the complexity is prohibitive for the marginal benefit. (And if
you can understand that tree without going mad, you're a better man
than I. ;-)

Inline markup is already fragile. Allowing nested inline markup would
only be asking for trouble IMHO. If it proves absolutely necessary, it
can be added later. The rules for what can appear inside what must be
well thought out first though.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net