RE: [Doc-SIG] master plan for interpreted text?
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.
participants (1)
-
Moore, Paul