[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
=================