[Doc-SIG] <tt> tagging (was Re: Some random thoughts)

[Peter Funk]

Hi!

[...partly false citiations not repeated here...
    jump into the thread at  
    http://www.python.org/pipermail/doc-sig/2000-March/001828.html
]
 
Edward Welbourne wrote:
> Peter: you make a clear case for us to include a verbatim keyword among
> the Keyword:-and-indent idioms previously considered.  What you
> *haven't* made a case for is an equivalent of an *in-paragraph* form,
> which is what I thought you were asking for.

Well.  I think you missunderstood me.  So I will try to explain
it again:  From my observations and personal use of doc-strings I
see no necessity for a construct to markup arbitray *in-paragraph*
code sequences, because they are not really often needed.  So I've
no objections against the idea to using #code code# for markup of
such sequences.  But I really don't care much.

What is far more often needed is to markup *in-paragraph* uses of 
identifiers, because they should act as hyperlinks to the 
particular definition/description of the identifier in 
HTML/XML output and they should be look different from the 
surrounding text in printed documentation.  I suggested the
use of the uparrow or caret ('^') character as markup symbol:
see <http://www.python.org/pipermail/doc-sig/2000-March/001817.html>

> I don't think anyone would disagree with the need for a Verbatim: tag to
> introduce preformatted text that needs a monospaced font.  I'm fairly
> sure we'd all be happy with this being a separate tag from the Code: or
> Example: tag (however it gets spelled).

Apart from Python code examples  ---which I prefer to be marked with 
the default Python prompt ('>>>') rather than some doc "keywords" 
like Example: Code: or the like--- we have three other special
kinds of paragraphs:

 1. tables (automatic recognition without a special keyword should
    be possible --- may be I can outline some code later)
 2. figures (box diagrams) automatic recognition without a special
    keyword should also be possible here.
 3. code snippets form other languages (so markup with '>>>' would
    play havoc with doctest).  Since these should be rare, the need
    for a special Verbatim: keyword to mark these paragraphs is okay.

Regards and have a nice weekend, Peter