[Doc-SIG] master plan for interpreted text?

[David Goodger]

In response to a request for a new interpreted text role, I recently
wrote,

    I don't want to let in all kinds of inline elements with
    marginal uses.

I think this needs further discussion.

In `The Chicago Manual of Style`, the section "Distinctive Treatment
of Words" (6.62 through 6.91 in 14th ed.) lists many cases:

* emphasis
* foreign words
* special terminology & technical terms
* words used as words
* letters as letters
* musical dynamics (pianissimo as italic "pp" etc.)
* letters indicating ryme schemes (as "aabba" for a limerick)

All of these are mapped to italics.  Should we have roles for each of
them?  Even if we combine closely-related cases (words as words &
letters as letters; musical dynamics as a case of foreign words), we
have 4 or 5 cases here.  DocBook has dozens more inline elements.  How
far should we go?

Apart from the purely-functional markup (hyperlink-related,
substitutions), we have 4 types of inline markup:

    ``inline literals``
    *emphasis*
    **strong**
    `interpreted text`

*Emphasis* and **strong** are probably the most common inline markup
used; they're also the most vaguely-defined.  They're typically (but
not always!) mapped as emphasis -> italic, and strong -> boldface.

Should we have a slew of inline elements, with interpreted text roles
mapping to them?  The advantage is that the Docutils doc model becomes
very rich, allowing fine distinctions of nuance.  The disadvantage is
code bloat: a lot more elements the Writers have to handle.  If we
want to set a limit, where?

The to-do list has this item: add a runtime setting (directive and/or
command-line option) to set the default role of interpreted text.
I.E., map "`" to something.  Should we have a directive to map other
inline markup (i.e., "*" & "**", maybe even "``") to arbitrary inline
element types?

There are two sides to be considered: the reStructuredText markup, and
the Docutils document model.  Currently they can be considered two
aspects of one system, but in the future there may be more markup
languages supported.  The reStructuredText markup is merely an
interface to the document model, and the document model shouldn't
pander to the markup too much.

Comments?

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv