[PYTHON DOC-SIG] Structured documentation syntax

Graham C. Hughes graham@resnet.ucsb.edu
Wed, 11 Sep 1996 15:35:41 -0700


-----BEGIN PGP SIGNED MESSAGE-----

Content-Type: text/plain; charset=us-ascii

In message <3235704B.5666@digicool.com>, 
    Jim Fulton writes:
>Graham C. Hughes wrote:
>> Underscores are traditionally used for citations in (e.g.) Usenet.
>> You would refer to _Running_Linux_ by Matt Welsh, or _The_TeXBook_ by
>> Knuth.  Asterisks have traditionally been used for emphasis, but there
>> isn't the difference between (in HTML) <STRONG> and <EMPH>.  There is
>> some prior art for using /slashes/ for italics, but I don't know how
>> well that goes over.  Emacs-w3 mode uses ~tildes~ for general
>> emphasis, as did earlier versions of gendoc.
>
>As I said in my other message, my concern is that what ever is 
>done, the text should still be readable as is.

Then the tildes are definitely out.  I don't find the slashes too evil, but **this** is occasionally offensive :).

I can understand your reluctance on the underscores.  Double quotes doesn't seem like a really acceptable substitute, because they aren't as visually distinctive.  There is a problem when normal text looks for the most part like cited text...  Using square brackets seems to solve this nicely, and there's enough prior art that I doubt the usage will be new to anyone.

The only problem is formatting...  I find that Python Home Page[1] (where 1 is a cookie for the lookup routines at the end) to be more readable than [Python Home Page].  But we have a problem determining where the hypertext reference in the former starts and ends...

>Yup.  See my other message.

Saved for future reference.

>If gendoc supports TIM, then it will get LaTex, texinfo, info, and
>Postscript nearly for free.  The tool I posted a while ago, module2html
>does roff. (But probably not as robustly.)

I'll have to look through the archives for that.  Which macro package does it use?

>Jim


- -- 
Graham Hughes (graham@resnet.ucsb.edu)  finger for PGP key
``Unix is many things to many people, but it's never been 
		everything to anybody.''
Home page at: http://www.cs.ucsb.edu/~ghughes/


-----BEGIN PGP SIGNATURE-----
Version: 2.6.2

iQCVAwUBMjc+uSqNPSINiVE5AQFiSwP/dG00S58YEPwNKsZlNBRYvyMsy4FDlzVt
e35TY5N1tmAAT5HypQyK59kAeAbAGP9ZetrUOsSoc/IDA8eM/nCYFG1CgHXN1YOo
9lea3trBKFHa6DDaBPVSFYkEoMS18nKUys55IkWg9maONb829agykpOLi1295TPg
QgMxx6Nvqc0=
=Xhl6
-----END PGP SIGNATURE-----

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================