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

[Peter Funk]

> > Sorry, I should have made myself clearer: genuine <tt> (typewriter style)
> > markup. I think there's a need for both.
 
David Ascher:
> Can you justify it a bit better?  IMO, <tt> is like <bold> -- it's
> presentation tagging, not content tagging.  Note that I think that *this*
> and **this** should correspond to <emph> and <strong> or vice versa, not
> <bold> and <italic>...

A <tt> (or monospaced) tag is not only pure presentation.

For some sorts of preformatted textual material the position of the 
glyphs *carry* the *content* not the glyphs itself.  
So the use of a monospaced font in any presentation of such material
is *essential* to preserve the carried content.  Examples of such material
are ASCII art diagrams like the following, which I pasted out of the doc 
string of the standard library module 'SocketServer.py':

        +-----------+        +------------------+
        | TCPServer |------->| UnixStreamServer |
        +-----------+        +------------------+
              |
              v
        +-----------+        +--------------------+
        | UDPServer |------->| UnixDatagramServer |
        +-----------+        +--------------------+

Monospaced fonts are ugly, no question.  

But we can't live completely without them for the following sorts of 
material:
   * textual diagrams like the one above (they won't die out to soon)
   * source code snippets (have been discussed here before)
   * ASCII tables like the following one:

	Directive   | Meaning
        ------------+--------------------------------------------------
	  %a        | Locale's abbreviated weekday name. 
	  %A        | Locale's full weekday name. 
	  %b        | Locale's abbreviated month name. 
	  %B        | Locale's full month name. 
	  %c        | Locale's appropriate date and time representation. 
	  %d        | Day of the month as a decimal number [01,31]. 

     and so on.

It might be possible to define some sophisticated rules, that allow
a appealing markup of tables in doc strings, which can be automatically
recognized (analysed) by a doc string parser, but that will that will become 
difficult.  

The automatic analysis of ASCII diagrams would become even more 
challenging.  So I come to the conclusion, that a clever doc string
parser should at least be able to classify certain *paragraphs* as items
containing performatted material and tag them as <tt> or monospaced
and so causing any output formatter to leave them *as is*.

Just my thoughts, Peter.
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen)