[Doc-SIG] master plan for interpreted text?

[Moore, Paul]

From: David Goodger [mailto:goodger@python.org]
> 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)

I think there's a *very* good case for the "special terminology" case -
so good, that I'd argue that it should be the default role in 99% of
cases. Consider - what does a document use `...` for? The best answer
(IMHO) would be "special words, in the context of this document". Which
pretty much qualifies as "special terminology".

We already have emphasis.

I don't see the need for the others. Just possibly for foreign words,
but I have to admit that I don't tend to bother with that level of
precision myself.

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

I'd say that they are very precisely defined, just that they are the
most often misused for things which are not their defined purpose!

The *least* well defined is interpreted text - at least, I never know
how I should use it! (That's probably because it's still in flux).

And on the other hand, the one logical element of my documents I always
have trouble marking up is "special terms". I'd love interpreted text
(in the default case) to take on that role for me.

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

-1. The other inline markup has strongly defined, fixed meaning. Don't
change this.

Paul.