[Doc-SIG] <tt> tagging (was Re: Some random thoughts)
Peter Funk
pf@artcom-gmbh.de
Fri, 10 Mar 2000 22:46:14 +0100 (MET)
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