From ikds@fashion-forum.de Wed Sep 4 23:46:22 1996 From: ikds@fashion-forum.de (Marc-Andre Lemburg) Date: Thu, 05 Sep 1996 00:46:22 +0200 Subject: [PYTHON DOC-SIG] Automatic Documentation Message-ID: <322E06BE.3F052D1A@fashion-forum.de> Hi ! I've just put a new version of my little html-doc-tool on our server. You can fetch it from the URL below (PythonStuff) by following the Sourcecode-Link. That file itself was made using the tool, so you can get an impression of what it's output looks like. It still isn't a beauty, but seems to work on most files now... well at least it does on all my files and the whole Python distribution (try: doc.py PythonDist /usr/local/lib/python -- just takes 2 minutes or so on my Linux box). To Michal: hope this fixes your problem !-) To all others: feedback is most welcome. To Daniel Larsson: is there a doc-sig-archive I can download from the net, other than the one using majordomo (I have to pay for e-mail... but not for ftp). -- ! iH ----------------------------------------------------------------------------- Marc-Andre Lemburg http://fashion-forum.de/ikds ----------------------------------------------------------------------------- Please reply by mailto:ikds@fashion-forum.de, thank you <<< http://www.fashion-forum.de/x.cgi?ikds/python/PythonStuff.html >>> ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From fdrake@CNRI.Reston.Va.US Tue Sep 3 16:39:46 1996 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Tue, 3 Sep 1996 11:39:46 -0400 (EDT) Subject: [PYTHON DOC-SIG] Parser module activity Message-ID: <199609031539.LAA00520@weyr.CNRI.Reston.Va.US> The parser module bundled with the Python distribution has been revised significantly since the previous release. More importantly, the documentation as been expanded with reasonable examples. Since the Python 1.4b3 release, there has been one bugfix and some re-organization of the documentation as well. For the complete package of parser module files, see the new parser module page at http://www.python.org/sigs/progenv-sig/parser/. Since I've added a lot of documentation, I'd really appreciate any constructive criticism on the documentation (which is why this is getting posted to Doc-SIG as well as Progenv-SIG). The organization changes are not in the Python 1.4b3 release, so the entire documentation for the module is available at the parser module page as well as summary of major changes from the older versions of the module. I appreciate any constructive criticism and bug reports! Thanks for your time. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Mon Sep 9 17:28:40 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Mon, 9 Sep 1996 11:28:40 -0500 Subject: [PYTHON DOC-SIG] New GENDOC released. Message-ID: <199609091628.LAA07736@darwin.rsoc.rockwell.com> Daniel Larsson has released gendoc 0.6 for your documentation pleasure. The big change here is the adoption of structured text for the doc string formatting standard. (I will post up my HTMLgen 1.0 package tomorrow which uses this standard for it's doc strings and the resulting online documentation turned out rather well.) Check out http://www.python.org/sigs/doc-sig for the release and a detailed explanation of the doc string format. Daniel is off line for a month so I'll field as many questions as I can. Below is from his README. -Robin Friedrich gendoc release 0.6 ================== Again, this release is done the day before my 4 week vacation in Spain. This is a somewhat hasty release, so I guess I might expect the Spanish inquisition when I come back. Anyways, most setext markups are now gone in favor of Jim Fulton's structured text approach. This means some new goodies, such as nested and numbered lists, definition lists and nested headings. Take a look in gendoc_test.py to see how to write your markups. By my mistake, the previous releases missed the important file 'gendoc', which is the main program (just imports gendoc.py). This is now corrected. The Makefile now uses BSD style install, instead of the HP/UX convoluted version (thanks to David Morley, morley@aaii.oz.au). -- Daniel Larsson dlarsson@sw.seisy.abb.se ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From s-ping@orange.cv.tottori-u.ac.jp Tue Sep 10 02:08:38 1996 From: s-ping@orange.cv.tottori-u.ac.jp (Ka-Ping Yee) Date: Tue, 10 Sep 1996 10:08:38 +0900 Subject: [PYTHON DOC-SIG] Structured documentation syntax Message-ID: <3234BF96.6181F217@sse.tottori-u.ac.jp> Hi -- i just saw the following on python-list: > Daniel Larsson has released gendoc 0.6 for your documentation > pleasure. The big change here is the adoption of structured text > for the doc string formatting standard. -- and went to have a look at the doc-sig page to find out what the formatting syntax was. Syntactic things: ----------------- I know that it may not be my place to speak so soon, as i have not spent any time researching what has been done, but a look at the description on the doc-sig page produced these thoughts (in order of decreasing strength): - Double-quotes seem too common to be used as hyperlink delimiters. More in keeping with common practice might be the use of [], the way most people use them to mark references. - Also, it would make sense for double and single quotes to both mark example code. What if you need to talk about a single-quoted string, for example? - As noted on the page, use of "--" is reasonably common for em-dashes (in fact, i'd even suggest turning them into real &emdash; entities in HTML). Why not use "::" instead for tagged list elements? - Couldn't you just choose one bullet marker for list elements, instead of three? - Is it true that a first-level list begins "12 First sentence..." but deeper levels begin "3.4. First sentence..."? That is, the description on the page seems to imply that the periods follow each ordering component, rather than separate them. - It might be nicer (simpler) to use _underscores_ for italics and use *single asterisks* for bold. (Special Python names that start and end with underscores should be marked as code examples anyway...) Btw, how do you make headings? Do you just make everything a sub-paragraph of a short paragraph containing the heading? Semantic things: ---------------- Has there been any thought towards a well-defined standard for documenting functions? I'm thinking of things about the interface, like parameter lists and descriptions of parameters, and maybe a defined place for a one-sentence (or even one-predicate) summary of what the function does, and/or what circumstances it expects to be run under. I think this could be fairly useful. A project i'm working on now (called MINSE, for the representation of structured expressions -- like math -- in HTML documents) needs a way to describe just these kinds of things about functions, and not just for the sake of documentation but actually as a real part of its operation. I want it to produce semantic information attached to the structures in the expression, and the perfect place to describe this seems to be __doc__. So i am thinking about designing a way to specify this information, but after reading the post thought that it might be better for gendoc and MINSE to understand things the same way. For more info on MINSE, please see http://www.lfw.org/math/. (Slightly out of date, so i can give more details if anyone has questions.) It currently has a working renderer for math expressions, which makes it possible for anyone to write math directly in their HTML and anyone to view it in any graphical OR textual browser. It's done in Python, of course. :) Ping ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From graham@resnet.ucsb.edu Tue Sep 10 05:52:31 1996 From: graham@resnet.ucsb.edu (Graham C. Hughes) Date: Mon, 09 Sep 1996 21:52:31 -0700 Subject: [PYTHON DOC-SIG] Structured documentation syntax In-Reply-To: Your message of "Tue, 10 Sep 1996 10:08:38 +0900." <3234BF96.6181F217@sse.tottori-u.ac.jp> Message-ID: <199609100452.VAA11054@graham.resnet.ucsb.edu> -----BEGIN PGP SIGNED MESSAGE----- In message <3234BF96.6181F217@sse.tottori-u.ac.jp>, Ka-Ping Yee writes: >I know that it may not be my place to speak so soon, as i have >not spent any time researching what has been done, but a look >at the description on the doc-sig page produced these thoughts >(in order of decreasing strength): I'm in the same boat here, but I've seen more than a few auto-docs in my time. Mostly, I agree with Ping, except for one or two points... > - Couldn't you just choose one bullet marker for list elements, > instead of three? This is probably to accomodate existing text, which uses a bewildering variety of markers. FYI, nroff uses an asterisk overstruck with a dash as a list marker... > - It might be nicer (simpler) to use _underscores_ for italics > and use *single asterisks* for bold. (Special Python names > that start and end with underscores should be marked as code > examples anyway...) 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) and . 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. >Has there been any thought towards a well-defined standard >for documenting functions? I'm thinking of things about >the interface, like parameter lists and descriptions of >parameters, and maybe a defined place for a one-sentence >(or even one-predicate) summary of what the function does, >and/or what circumstances it expects to be run under. This is needed. Now, I've just jumped in here, so there may be some as-yet-unpublished standards doc on this very subject. But it's not on the Python web page... All that exists at the moment is expressed in the Python manuals: the first line should be a concise summary of the function, the second line should be blank, and anything else should be wonderfully illustrative. I suppose I should be more specific about this; I'll have to look through all my documentation stuff before I make up my mind. Javadoc has different conventions for Perl's POD, which is in turn different from (say) cxref and cxx2html. Finally, is anyone else working on formatters for [nt]roff and LaTeX? - -- 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 Comment: Processed by Mailcrypt 3.4, an Emacs/PGP interface iQCVAwUBMjT0BSqNPSINiVE5AQFTqQQApLp0fHja4kU2/8vn7SqjP1f9V+8lGgeJ poVWGOnJrXLRHOLcdC7QvcAIBKp5D31lUk/x7mlGS7NglEioaPHEb3LSxX/rl8Dh D4zpH7UJcozyFaxSXHKNqKwH3OzwA7fyA9wRTmeBrZRkMkk2TdNgmeZJ6kT5x7XN fK5FbHQEXyM= =N88r -----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 ================= From janssen@parc.xerox.com Tue Sep 10 10:10:02 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Tue, 10 Sep 1996 02:10:02 PDT Subject: [PYTHON DOC-SIG] Python TIM processor... Message-ID: I've started re-writing my TIM stuff in Python (see ftp://ftp.parc.xerox.com/pub/ilu/2.0/20a8-manual-html/manual_17.html). So far I've got a Python script that takes TIM with arbitrary domain-specific macros, and produces text, info, Texinfo, Postscript, or HTML output. Both diagrams and pictures are supported via encapsulated Postscript; URLs are supported as well. For the text and info part, you need GNU makeinfo. For the Postscript, you need TeX, GNU texindex, and dvips. For the HTML, you need another script, a mildly expanded version of Lionel Cons' texinfo2html perl script; this script also uses a script called eps2gif, another perl script written by Gisle Aas, which in turn requires ghostscript with GIF output drivers. Or, to put it another way: TIM->Texinfo requires only Python TIM->Text requires Python & GNU makeinfo TIM->Info requires Python & GNU makeinfo TIM->Postscript requires Python, TeX, GNU texindex & dvips TIM->HTML requires Python, Ghostscript & Perl 1) Do these seem like reasonable resource constraints? 2) Is there some Python script for turning texinfo into HTML, so that I could drop the Perl dependency? 3) How should the various pathnames that have to be configured into the various scripts be configured in? 4) Is there a free dvips implementation? Bill ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Tue Sep 10 14:10:47 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Tue, 10 Sep 1996 09:10:47 -0400 Subject: [PYTHON DOC-SIG] Python TIM processor... References: Message-ID: <323568D7.7527@digicool.com> Bill Janssen wrote: > > I've started re-writing my TIM stuff in Python (see > ftp://ftp.parc.xerox.com/pub/ilu/2.0/20a8-manual-html/manual_17.html). > So far I've got a Python script that takes TIM with arbitrary > domain-specific macros, and produces text, info, Texinfo, Postscript, or > HTML output. Both diagrams and pictures are supported via encapsulated > Postscript; URLs are supported as well. For the text and info part, you > need GNU makeinfo. For the Postscript, you need TeX, GNU texindex, and > dvips. For the HTML, you need another script, a mildly expanded version > of Lionel Cons' texinfo2html perl script; this script also uses a script > called eps2gif, another perl script written by Gisle Aas, which in turn > requires ghostscript with GIF output drivers. > > Or, to put it another way: > > TIM->Texinfo requires only Python > TIM->Text requires Python & GNU makeinfo > TIM->Info requires Python & GNU makeinfo > TIM->Postscript requires Python, TeX, GNU texindex & dvips > TIM->HTML requires Python, Ghostscript & Perl Whew! > 1) Do these seem like reasonable resource constraints? Yes. > 2) Is there some Python script for turning texinfo into HTML, so that I > could drop the Perl dependency? That would be nice. > ================= > DOC-SIG - SIG for the Python Documentation Project > > send messages to: doc-sig@python.org > administrivia to: doc-sig-request@python.org > ================= -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ## ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Tue Sep 10 14:16:57 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Tue, 10 Sep 1996 08:16:57 -0500 Subject: [PYTHON DOC-SIG] Structured documentation syntax Message-ID: <199609101316.IAA08617@darwin.rsoc.rockwell.com> |> Date: Tue, 10 Sep 1996 10:08:38 +0900 |> From: Ka-Ping Yee |> |> Syntactic things: |> ----------------- |> |> I know that it may not be my place to speak so soon, as i have |> not spent any time researching what has been done, but a look |> at the description on the doc-sig page produced these thoughts |> (in order of decreasing strength): |> |> - Double-quotes seem too common to be used as hyperlink delimiters. |> More in keeping with common practice might be the use of [], |> the way most people use them to mark references. Text found in double quotes are checked against the footnote references found at the bottom of the doc string. If no match is found, it's just left alone. |> |> - Also, it would make sense for double and single quotes to both |> mark example code. What if you need to talk about a single-quoted |> string, for example? I'll let Jim Fulton answer this one. The double quotes would be overused if applied to this case as well, IMO. Single quoted text gets marked as but the quotes remain, I believe. |> |> - As noted on the page, use of "--" is reasonably common for |> em-dashes (in fact, i'd even suggest turning them into real |> &emdash; entities in HTML). Why not use "::" instead for |> tagged list elements? Again the effort here was to make it as natural looking as possible. I originally chose :: but changed it after Jim objected. I think it's more likely to be found in existing docs with dashes. |> |> - Couldn't you just choose one bullet marker for list elements, |> instead of three? Again, the intent is to minimize the need for overhaul of existing doc strings. |> |> - Is it true that a first-level list begins "12 First sentence..." |> but deeper levels begin "3.4. First sentence..."? That is, the |> description on the page seems to imply that the periods follow |> each ordering component, rather than separate them. The nesting paragraph stuff isn't fully functional in the current gendoc beta. But as it stands now both of your examples above would be treated as OL and be numbered according to indentation. |> |> - It might be nicer (simpler) to use _underscores_ for italics |> and use *single asterisks* for bold. (Special Python names |> that start and end with underscores should be marked as code |> examples anyway...) Again, we used to do exactly this when setext was used as the standard. But it makes things difficult to distinguish things like __init__ as not needing to be marked up. |> |> Btw, how do you make headings? Do you just make everything a |> sub-paragraph of a short paragraph containing the heading? Yes. |> |> Semantic things: |> ---------------- |> |> Has there been any thought towards a well-defined standard |> for documenting functions? I'm thinking of things about |> the interface, like parameter lists and descriptions of |> parameters, and maybe a defined place for a one-sentence |> (or even one-predicate) summary of what the function does, |> and/or what circumstances it expects to be run under. This hasn't been dicussed much yet but needs to be. That's precisely what this group is about! |> |> I think this could be fairly useful. A project i'm working |> on now (called MINSE, for the representation of structured |> expressions -- like math -- in HTML documents) needs a way |> to describe just these kinds of things about functions, and |> not just for the sake of documentation but actually as a real |> part of its operation. I want it to produce semantic information |> attached to the structures in the expression, and the perfect |> place to describe this seems to be __doc__. So i am thinking |> about designing a way to specify this information, but after |> reading the post thought that it might be better for gendoc |> and MINSE to understand things the same way. |> |> For more info on MINSE, please see http://www.lfw.org/math/. |> (Slightly out of date, so i can give more details if anyone |> has questions.) |> |> It currently has a working renderer for math expressions, |> which makes it possible for anyone to write math directly |> in their HTML and anyone to view it in any graphical OR |> textual browser. It's done in Python, of course. :) |> |> |> Ping Looks promising. I'm looking forward to your contributions. -Robin ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From guido@CNRI.Reston.Va.US Tue Sep 10 14:27:10 1996 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Tue, 10 Sep 1996 09:27:10 -0400 Subject: [PYTHON DOC-SIG] Python TIM processor... In-Reply-To: Your message of "Tue, 10 Sep 1996 09:10:47 EDT." <323568D7.7527@digicool.com> References: <323568D7.7527@digicool.com> Message-ID: <199609101327.JAA17013@monty> > 2) Is there some Python script for turning texinfo into HTML, so that I > could drop the Perl dependency? Yes. Doc/texi2html.py in the Python distribution. It's not great, but it once worked, and I'm sure it can be salvaged with not too much effort (any volunteers?). --Guido van Rossum (home page: http://www.python.org/~guido/) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Tue Sep 10 14:36:06 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Tue, 10 Sep 1996 09:36:06 -0400 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: <3234BF96.6181F217@sse.tottori-u.ac.jp> Message-ID: <32356EC5.6F0A@digicool.com> Ka-Ping Yee wrote: > > Hi -- i just saw the following on python-list: > > > Daniel Larsson has released gendoc 0.6 for your documentation > > pleasure. The big change here is the adoption of structured text > > for the doc string formatting standard. > > -- and went to have a look at the doc-sig page to find out > what the formatting syntax was. > > Syntactic things: > ----------------- > > I know that it may not be my place to speak so soon, as i have > not spent any time researching what has been done, but a look > at the description on the doc-sig page produced these thoughts > (in order of decreasing strength): > > - Double-quotes seem too common to be used as hyperlink delimiters. > More in keeping with common practice might be the use of [], > the way most people use them to mark references. > > - Also, it would make sense for double and single quotes to both > mark example code. What if you need to talk about a single-quoted > string, for example? You can always use double-quoted strings, rather than single-quoted strings to show string literals. Using *only* single-quoted strings for examples leaves the option of using double quoted strings for string literals in examples. > > - As noted on the page, use of "--" is reasonably common for > em-dashes (in fact, i'd even suggest turning them into real > &emdash; entities in HTML). Why not use "::" instead for > tagged list elements? > > - Couldn't you just choose one bullet marker for list elements, > instead of three? The goal of this effort is to be able to use unprocessed doc strings. It us often useful, when reading the raw text to have a visual distinction between different types of bullets. Also, there are many conventions for typing bullets and there's no harm in trying to support most or all of them. I'd like structured text to be as unrestrictive as possible so that people writing doc strings don't have to thing hard about formatting. > - Is it true that a first-level list begins "12 First sentence..." > but deeper levels begin "3.4. First sentence..."? That is, the > description on the page seems to imply that the periods follow > each ordering component, rather than separate them. Right. You can also use: '1. First sentance' > - It might be nicer (simpler) to use _underscores_ for italics > and use *single asterisks* for bold. (Special Python names > that start and end with underscores should be marked as code > examples anyway...) Actually, *spam* is used for emphasis, not italics. It just happens that most browsers use italics for emphasis. Personally, I don't like how _underscores_ looks. I would never type a text document that way. I would have no problem with having single asterisks indicate strong, rather than emphasized. > Btw, how do you make headings? Do you just make everything a > sub-paragraph of a short paragraph containing the heading? Single-line paragraphs with sub-paragraphs are treated as headings. > Semantic things: > ---------------- > > Has there been any thought towards a well-defined standard > for documenting functions? I'm thinking of things about > the interface, like parameter lists and descriptions of > parameters, and maybe a defined place for a one-sentence > (or even one-predicate) summary of what the function does, > and/or what circumstances it expects to be run under. The first line of the doc string provides a short description of the function (or any other documented object). This is your one-sentance description. For Python functions there are function object attributes for getting function argument names and defaults. For built-in (C, C++, Fortran, etc.) functions, there is an agreed-upon convention for including signatures (argument names and defaults) in the one-line summary, like this: spam(foo,bar,[def1,def2]) -- Summary of spam Everything above is standard, although perhaps not well known. :-) For argument descriptions, I like and follow the example of the Python library manual, which includes argument descriptions in the prose of the full descriptions, at least for simple functions whose doc strings are only a paragraph or two. For more complex functions, I use somthing like: The arguments to this function are: foo -- description of foo bar -- description of bar def1 -- description of def1, including the default value def2 -- description of def2, including the default value Note that this is very readable as text and will be converted to a nice descriptive list in HTML. It would also be quite easy to write a function to find and extract the argument descriptions from the text, if necessary. Jim -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ## ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From fdrake@CNRI.Reston.Va.US Tue Sep 10 14:35:40 1996 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Tue, 10 Sep 1996 09:35:40 -0400 (EDT) Subject: [PYTHON DOC-SIG] Python TIM processor... In-Reply-To: from "Bill Janssen" at Sep 10, 96 02:10:02 am Message-ID: <199609101335.JAA25543@weyr.CNRI.Reston.Va.US> Hey Bill! Have you had a chance to look at my patches for the ILU build procedure? I'd like to know if any problems turned up with them. > 1) Do these seem like reasonable resource constraints? (from earlier in the post:) > TIM->Postscript requires Python, TeX, GNU texindex & dvips > TIM->HTML requires Python, Ghostscript & Perl texindex or makeindex? The requirement on ghostscript seems high, but I think I understand what you're trying to do. I'd be more tempted to write something like @picture base-file-name and have the processor add the extension based on output format and availability. If the required image isn't available in the right format, the conversion should be applied on an as-needed basis. This would allow the conversion policy used in the released version to be highly flexible while still providing effection implementation of the specific policy you describe. For users who prefer to do images in formats other than EPS, the option is fairly clean. (Then do conversions based on table lookup, with a configurable table... see Grail: html2ps.py. ;-) > 2) Is there some Python script for turning texinfo into HTML, so that I > could drop the Perl dependency? See texi2html.py in the Doc/ subdirectory of the Python distribution. This is the script used to produce HTML from a texinfo file produced from the LaTeX document source. It's not trivial (nothing interesting is!), but does a farily reasonable job. The version packaged with Python 1.4 produces fairly tight HTML that seems to work with the major browsers to which I have access (Grail, Mosaic, Netscape). I don't have a conveniently available Windows (or varient) box, so I haven't checked with MSIE, but it doesn't do anything weird. If you have to hack on it to get it working for TIM (likely, to add the flexibility you describe), we'd be interested in hearing from you. > 3) How should the various pathnames that have to be configured into the > various scripts be configured in? Please elaborate.... -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Tue Sep 10 14:42:35 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Tue, 10 Sep 1996 09:42:35 -0400 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: <199609100452.VAA11054@graham.resnet.ucsb.edu> Message-ID: <3235704B.5666@digicool.com> Graham C. Hughes wrote: > > -----BEGIN PGP SIGNED MESSAGE----- > > In message <3234BF96.6181F217@sse.tottori-u.ac.jp>, > Ka-Ping Yee writes: > >I know that it may not be my place to speak so soon, as i have > >not spent any time researching what has been done, but a look > >at the description on the doc-sig page produced these thoughts > >(in order of decreasing strength): > > I'm in the same boat here, but I've seen more than a few auto-docs in > my time. Mostly, I agree with Ping, except for one or two points... > > > - Couldn't you just choose one bullet marker for list elements, > > instead of three? > > This is probably to accomodate existing text, which uses a bewildering > variety of markers. FYI, nroff uses an asterisk overstruck with a > dash as a list marker... > > > - It might be nicer (simpler) to use _underscores_ for italics > > and use *single asterisks* for bold. (Special Python names > > that start and end with underscores should be marked as code > > examples anyway...) > > 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) and . 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. > >Has there been any thought towards a well-defined standard > >for documenting functions? I'm thinking of things about > >the interface, like parameter lists and descriptions of > >parameters, and maybe a defined place for a one-sentence > >(or even one-predicate) summary of what the function does, > >and/or what circumstances it expects to be run under. > > This is needed. Now, I've just jumped in here, so there may be some > as-yet-unpublished standards doc on this very subject. Yup. See my other message. > But it's not > on the Python web page... > > All that exists at the moment is expressed in the Python manuals: the > first line should be a concise summary of the function, the second > line should be blank, and anything else should be wonderfully > illustrative. > > I suppose I should be more specific about this; I'll have to look > through all my documentation stuff before I make up my mind. Javadoc > has different conventions for Perl's POD, which is in turn different > from (say) cxref and cxx2html. > > Finally, is anyone else working on formatters for [nt]roff and LaTeX? 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.) Jim > > ================= > DOC-SIG - SIG for the Python Documentation Project > > send messages to: doc-sig@python.org > administrivia to: doc-sig-request@python.org > ================= -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ## ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From fdrake@CNRI.Reston.Va.US Tue Sep 10 14:48:23 1996 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Tue, 10 Sep 1996 09:48:23 -0400 (EDT) Subject: [PYTHON DOC-SIG] Python TIM processor... In-Reply-To: <199609101327.JAA17013@monty> from "Guido van Rossum" at Sep 10, 96 09:27:10 am Message-ID: <199609101348.JAA25621@weyr.CNRI.Reston.Va.US> > Yes. Doc/texi2html.py in the Python distribution. It's not great, > but it once worked, and I'm sure it can be salvaged with not too much > effort (any volunteers?). > > --Guido van Rossum (home page: http://www.python.org/~guido/) Guido, When did you break it? The version in the current Python (and released with 1.4b3) works just fine. Is there a problem with it which I'm not aware of? -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Tue Sep 10 14:55:22 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Tue, 10 Sep 1996 09:55:22 -0400 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: <199609101316.IAA08617@darwin.rsoc.rockwell.com> Message-ID: <3235734A.4B74@digicool.com> Robin Friedrich wrote: > > |> Date: Tue, 10 Sep 1996 10:08:38 +0900 > |> From: Ka-Ping Yee > |> > |> Syntactic things: > |> ----------------- > |> > |> I know that it may not be my place to speak so soon, as i have > |> not spent any time researching what has been done, but a look > |> at the description on the doc-sig page produced these thoughts > |> (in order of decreasing strength): > |> > |> - Double-quotes seem too common to be used as hyperlink delimiters. > |> More in keeping with common practice might be the use of [], > |> the way most people use them to mark references. > > Text found in double quotes are checked against the footnote references > found at the bottom of the doc string. If no match is found, it's just > left alone. > |> > |> - Also, it would make sense for double and single quotes to both > |> mark example code. What if you need to talk about a single-quoted > |> string, for example? > > I'll let Jim Fulton answer this one. The double quotes would be overused > if applied to this case as well, IMO. Single quoted text gets marked as > but the quotes remain, I believe. No, the quotes are stripped. Double quotes are not used for examples specifically so that you can use them for string literals and for actually quoting other text. > |> > |> - As noted on the page, use of "--" is reasonably common for > |> em-dashes (in fact, i'd even suggest turning them into real > |> &emdash; entities in HTML). Why not use "::" instead for > |> tagged list elements? > > Again the effort here was to make it as natural looking as possible. > I originally chose :: but changed it after Jim objected. I think it's > more likely to be found in existing docs with dashes. > > |> > |> - Couldn't you just choose one bullet marker for list elements, > |> instead of three? > > Again, the intent is to minimize the need for overhaul of existing > doc strings. When reading the text itself, the various types of bullets are helpful for visually separating different levels. Also, the goal should be to make the formatter as smart as possible about detecting formatting so that authors can spend time thinking about documenting their software and less time thinking about formatting. > |> > |> - Is it true that a first-level list begins "12 First sentence..." > |> but deeper levels begin "3.4. First sentence..."? That is, the > |> description on the page seems to imply that the periods follow > |> each ordering component, rather than separate them. > > The nesting paragraph stuff isn't fully functional in the current > gendoc beta. You said this in another message a while ago and I didn't have a chance to get back to you. (sorry:) Could you send me a sample text that isn't converted properly? > But as it stands now both of your examples above would > be treated as OL and be numbered according to indentation. I guess another option would be to treat numbered lists like descriptive lists to retain the original numbering. So iii. foo would become:
iii
foo
Perhaps then there could be a separate notation for auto-numbering, like: #. foo Does this make sense??? > |> > |> - It might be nicer (simpler) to use _underscores_ for italics > |> and use *single asterisks* for bold. (Special Python names > |> that start and end with underscores should be marked as code > |> examples anyway...) > > Again, we used to do exactly this when setext was used as the standard. > But it makes things difficult to distinguish things like __init__ as > not needing to be marked up. I wouldn't mind if *python is my favorite language* became python is my favorite language But I'm note sure what to use for emphasis except that I don't like using _ because of the overloaded language meaning. Some possabilities: /python is my favorite language/ **python is my favorite language** bleh > |> > |> Btw, how do you make headings? Do you just make everything a > |> sub-paragraph of a short paragraph containing the heading? > Yes. Specifically, one-line paragraphs. > |> > |> Semantic things: > |> ---------------- > |> > |> Has there been any thought towards a well-defined standard > |> for documenting functions? I'm thinking of things about > |> the interface, like parameter lists and descriptions of > |> parameters, and maybe a defined place for a one-sentence > |> (or even one-predicate) summary of what the function does, > |> and/or what circumstances it expects to be run under. > > This hasn't been dicussed much yet but needs to be. That's > precisely what this group is about! Most of it has been clearly defined, but not will documented. Jim -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ## ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From fredrik_lundh@ivab.se Tue Sep 10 14:59:10 1996 From: fredrik_lundh@ivab.se (Fredrik Lundh) Date: Tue, 10 Sep 1996 15:59:10 +0200 Subject: [PYTHON DOC-SIG] Structured documentation syntax In-Reply-To: <32356EC5.6F0A@digicool.com> (message from Jim Fulton on Tue, 10 Sep 1996 09:36:06 -0400) Message-ID: <9609101359.AA02560@arnold.image.ivab.se> > > - It might be nicer (simpler) to use _underscores_ for italics > > and use *single asterisks* for bold. (Special Python names > > that start and end with underscores should be marked as code > > examples anyway...) > Actually, *spam* is used for emphasis, not italics. It just happens > that most browsers use italics for emphasis. Personally, I don't > like how _underscores_ looks. I would never type a text document > that way. I would have no problem with having single asterisks > indicate strong, rather than emphasized. Well, typographically speaking, underscores are the same thing as italics, so I strongly agree with Ka-Ping on this issue. Basically, italics should be used when you need to emphasize (sp?) things in running text, while boldface should be used to mark out things that the reader might scan for on a page. So _em_ and *strong* are IMHO the appropriate way to go. /F ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From guido@CNRI.Reston.Va.US Tue Sep 10 16:51:51 1996 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Tue, 10 Sep 1996 11:51:51 -0400 Subject: [PYTHON DOC-SIG] Python TIM processor... In-Reply-To: Your message of "Tue, 10 Sep 1996 09:48:23 EDT." <199609101348.JAA25621@weyr.CNRI.Reston.Va.US> References: <199609101348.JAA25621@weyr.CNRI.Reston.Va.US> Message-ID: <199609101551.LAA17490@monty> > When did you break it? The version in the current Python (and > released with 1.4b3) works just fine. > Is there a problem with it which I'm not aware of? Apparently not, except for maintenance :-) --Guido van Rossum (home page: http://www.python.org/~guido/) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From janssen@parc.xerox.com Wed Sep 11 02:20:18 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Tue, 10 Sep 1996 18:20:18 PDT Subject: [PYTHON DOC-SIG] Python TIM processor... In-Reply-To: <199609101335.JAA25543@weyr.CNRI.Reston.Va.US> References: <199609101335.JAA25543@weyr.CNRI.Reston.Va.US> Message-ID: Excerpts from direct: 10-Sep-96 Re: [PYTHON DOC-SIG] Python.. "Fred L. Drake"@cnri.res (2183*) > texindex or makeindex? texindex. > The requirement on ghostscript seems high, but I think I understand > what you're trying to do. I'd be more tempted to write something like > @picture base-file-name > and have the processor add the extension based on output format and > availability. If the required image isn't available in the right > format, the conversion should be applied on an as-needed basis. This > would allow the conversion policy used in the released version to be > highly flexible while still providing effection implementation of the > specific policy you describe. For users who prefer to do images in > formats other than EPS, the option is fairly clean. (Then do > conversions based on table lookup, with a configurable table... see > Grail: html2ps.py. ;-) It's a nice idea, but too complicated. We tried that here at PARC with System-33, and found it an untenable morass. EPS seems a good compromise that can be converted to most desired formats, and works reasonably well for both drawings and images. Bill ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From janssen@parc.xerox.com Wed Sep 11 09:18:07 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Wed, 11 Sep 1996 01:18:07 PDT Subject: [PYTHON DOC-SIG] TIM paper Message-ID: I've put out a short chapter from the ILU manual on TIM, appropriately modified for my current set of tools. I'll put out the tools themselves this week. The document is on ftp://ftp.parc.xerox.com/transient/tim.ps. Bill ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From s-ping@orange.cv.tottori-u.ac.jp Wed Sep 11 18:37:49 1996 From: s-ping@orange.cv.tottori-u.ac.jp (Ka-Ping Yee) Date: Thu, 12 Sep 1996 02:37:49 +0900 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: <3234BF96.6181F217@sse.tottori-u.ac.jp> <32356EC5.6F0A@digicool.com> Message-ID: <3236F8ED.4B83FEA5@sse.tottori-u.ac.jp> Hi again. Given that the goal is to have a more flexible syntax, i can understand now why you chose to allow three kinds of list bullets, why it's better to leave double-quotes visible, and why we might as well allow "1 Heading" or "1. Heading" or "1.2 Heading" or "1.2. Heading". Thank you for the explanations. I was just expressing a personal preference about **emphasis**, *emphasis*, and _emphasis_, but i don't feel as strongly about that as Fredrik Lundh seems to. Mostly, though, i do still feel that double-quotes aren't really the best choice for hyperlinks (and i don't think any existing doc strings contain hyperlinks, anyway). Are there typical uses of brackets, other than [references], that i haven't thought of? Are there really many doc-strings already that use -- to make definition lists? I have seen very few definition-list structures anywhere, and those i have seen use just ":". I would prefer to avoid "--", but i guess i can live with it. I'm looking through Grail source while thinking about this. Noticed in a few places: maybe it would be safe to assume that an identifier followed by () is a function name, and thus treat it as (and possibly hyperlink it)? Specifically, this regex: [A-Za-z_]+(\.[A-Za-z_]+)*\(\) using AWK syntax. I was glad to hear that there's a convention for function documentation. I was about to propose something specific. To make the one-line description consistent in its form, i was thinking of: nouns (classes, attributes, variables): Use an object phrase, e.g. "a can of spam" verbs (functions, methods): Use the imperative form, e.g. "Count to (exactly) three." Format as a complete sentence (capital and period). > For Python functions there are function object attributes for > getting function argument names and defaults. Yes, but their descriptions would still be in the doc-string, right? > For more complex functions, I use somthing like: > > The arguments to this function are: > > foo -- description of foo > > bar -- description of bar > > def1 -- description of def1, including the default value > > def2 -- description of def2, including the default value > > Note that this is very readable as text and will be converted to > a nice descriptive list in HTML. It would also be quite easy to write > a function to find and extract the argument descriptions from the > text, if necessary. Yes, this stands out very nicely. Can we agree to put such a list immediately after the one-line description, if there is to be one, and not worry about explicitly preceding it with "the arguments are..." -- thus establishing the use of a definition list in this position as a convention? Ping ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Wed Sep 11 18:59:34 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Wed, 11 Sep 1996 12:59:34 -0500 Subject: [PYTHON DOC-SIG] HTMLgen and gendoc Message-ID: <199609111759.MAA10210@darwin.rsoc.rockwell.com> In order to illustrate the results of gendoc 0.6 we've unpacked the HTMLgen online documentation on the python server so you can browse it directly. When you get there, click the Manual button to spawn a new browser with the framed manual autogenerated with gendoc's HTMLgen formatter module. http://www.python.org/sigs/web-sig/HTMLgen/html/main.html ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Wed Sep 11 19:44:59 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Wed, 11 Sep 1996 13:44:59 -0500 Subject: [PYTHON DOC-SIG] Structured documentation syntax Message-ID: <199609111844.NAA10237@darwin.rsoc.rockwell.com> |> From: Ka-Ping Yee |> To: Jim Fulton |> Cc: doc-sig@python.org |> Subject: Re: [PYTHON DOC-SIG] Structured documentation syntax |> |> Hi again. Given that the goal is to have a more flexible |> syntax, i can understand now why you chose to allow three |> kinds of list bullets, why it's better to leave double-quotes |> visible, and why we might as well allow "1 Heading" or |> "1. Heading" or "1.2 Heading" or "1.2. Heading". |> |> Thank you for the explanations. |> |> I was just expressing a personal preference about **emphasis**, |> *emphasis*, and _emphasis_, but i don't feel as strongly |> about that as Fredrik Lundh seems to. Just to clarify. Gendoc uses *emphasis* and **strong** to delineate text. The underscores were rejected partly because they are harder to segregate from normal Python names like __init__ which appear in doc strings often. |> |> Mostly, though, i do still feel that double-quotes aren't |> really the best choice for hyperlinks (and i don't think |> any existing doc strings contain hyperlinks, anyway). Are |> there typical uses of brackets, other than [references], |> that i haven't thought of? This is easy to change. I really didn't care, much I just picked double quotes out of the air. [] & {} would have worked as well. I have used this hyperlink feature in my doc strings and it works fine. |> |> Are there really many doc-strings already that use -- to |> make definition lists? I have seen very few definition-list |> structures anywhere, and those i have seen use just ":". |> I would prefer to avoid "--", but i guess i can live with it. I use them whenever I list out the parameters of the function and the public attributes. Is this an esthetic thing only or do you wish to really reserve it for emdash? |> |> I'm looking through Grail source while thinking about this. |> Noticed in a few places: maybe it would be safe to assume |> that an identifier followed by () is a function name, and |> thus treat it as (and possibly hyperlink it)? |> Specifically, this regex: |> |> [A-Za-z_]+(\.[A-Za-z_]+)*\(\) |> |> using AWK syntax. |> The gendoc approach is not to parse through the source files (unless you use the -p option) at all. It lets python import do that and then just walk through the symbol dictionaries to collect doc strings. So no assumptions need to be made. In fact gendoc does generate hyperlinks for other functions/modules. See http://www.python.org/sigs/web-sig/HTMLgen/html/index.html |> |> I was glad to hear that there's a convention for function |> documentation. I was about to propose something specific. |> To make the one-line description consistent in its form, |> i was thinking of: |> |> nouns (classes, attributes, variables): |> Use an object phrase, e.g. "a can of spam" |> |> verbs (functions, methods): |> Use the imperative form, e.g. "Count to (exactly) three." |> Format as a complete sentence (capital and period). |> |> > For Python functions there are function object attributes for |> > getting function argument names and defaults. |> |> Yes, but their descriptions would still be in the doc-string, right? Well this is debateble by some but I agree with you on this. |> |> > For more complex functions, I use somthing like: |> > |> > The arguments to this function are: |> > |> > foo -- description of foo |> > |> > bar -- description of bar |> > |> > def1 -- description of def1, including the default value |> > |> > def2 -- description of def2, including the default value |> > |> > Note that this is very readable as text and will be converted to |> > a nice descriptive list in HTML. It would also be quite easy to write |> > a function to find and extract the argument descriptions from the |> > text, if necessary. |> |> Yes, this stands out very nicely. Can we agree to put such |> a list immediately after the one-line description, if there |> is to be one, and not worry about explicitly preceding it |> with "the arguments are..." -- thus establishing the use of |> a definition list in this position as a convention? I think this convention may be too restrictive. Again, gendoc detects def lists by their structure not their position. This could be part of a style guide though. -Robin ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From s-ping@orange.cv.tottori-u.ac.jp Wed Sep 11 19:59:45 1996 From: s-ping@orange.cv.tottori-u.ac.jp (Ka-Ping Yee) Date: Thu, 12 Sep 1996 03:59:45 +0900 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: <199609111844.NAA10237@darwin.rsoc.rockwell.com> Message-ID: <32370C21.4D88C2CF@sse.tottori-u.ac.jp> Robin Friedrich wrote: > > Just to clarify. Gendoc uses *emphasis* and **strong** to delineate > text. The underscores were rejected partly because they are harder to > segregate from normal Python names like __init__ which appear in doc > strings often. Sure. I follow your reasons. > This is easy to change. I really didn't care, much I just picked > double quotes out of the air. [] & {} would have worked as well. > I have used this hyperlink feature in my doc strings and it works > fine. Okay. My vote is for []. > |> Are there really many doc-strings already that use -- to > |> make definition lists? I have seen very few definition-list > |> structures anywhere, and those i have seen use just ":". > |> I would prefer to avoid "--", but i guess i can live with it. > > I use them whenever I list out the parameters of the function > and the public attributes. > Is this an esthetic thing only or do you wish to really reserve > it for emdash? Primarily i'm concerned about emdash, i'd say. It's not a big deal, but *if* there's still time to choose, i'd like to choose well. > |> I'm looking through Grail source while thinking about this. > |> Noticed in a few places: maybe it would be safe to assume > |> that an identifier followed by () is a function name [...] > The gendoc approach is not to parse through the source files > (unless you use the -p option) at all. Yeah, i saw that. I'm talking about making this assumption when someone talks about another function *within* the __doc__ string, though -- as part of parsing __doc__. > |> Yes, this stands out very nicely. Can we agree to put such > |> a list immediately after the one-line description, if there > |> is to be one, and not worry about explicitly preceding it > |> with "the arguments are..." -- thus establishing the use of > |> a definition list in this position as a convention? > > I think this convention may be too restrictive. Again, gendoc > detects def lists by their structure not their position. This could > be part of a style guide though. I'm not suggesting that def lists be only allowed to appear immediately after the one-liner. I agree that def lists should be allowed anywhere, detected only by structure -- my suggestion is that we form a convention to reserve the position of "right after the one-liner" for the one particular def list which *describes the arguments*. This way, it is possible to ask for the description of a particular argument and to automatically find and return it with confidence. Ping ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From janssen@parc.xerox.com Wed Sep 11 20:04:06 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Wed, 11 Sep 1996 12:04:06 PDT Subject: [PYTHON DOC-SIG] HTMLgen and gendoc In-Reply-To: <199609111759.MAA10210@darwin.rsoc.rockwell.com> References: <199609111759.MAA10210@darwin.rsoc.rockwell.com> Message-ID: <0mBkoa4B0KGW04Emc3@holmes.parc.xerox.com> Excerpts from ext.python: 11-Sep-96 [PYTHON DOC-SIG] HTMLgen an.. Robin Friedrich@rose.rso (526) > In order to illustrate the results of gendoc 0.6 we've unpacked the > HTMLgen online documentation on the python server so you can browse > it directly. When you get there, click the Manual button to spawn a > new browser with the framed manual autogenerated with gendoc's HTMLgen > formatter module. > http://www.python.org/sigs/web-sig/HTMLgen/html/main.html Hmmm, not good. I go to my Emacs, type "M-x w3-fetch http://www.python.org/sigs/web-sig/HTMLgen/html/main.html", and see nothing. Frames are not supported by several useful browsers; I'd like to see a solution which doesn't use them. Bill ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From fredrik_lundh@ivab.se Wed Sep 11 20:48:03 1996 From: fredrik_lundh@ivab.se (Fredrik Lundh) Date: Wed, 11 Sep 1996 21:48:03 +0200 Subject: [PYTHON DOC-SIG] Structured documentation syntax In-Reply-To: <3236F8ED.4B83FEA5@sse.tottori-u.ac.jp> (message from Ka-Ping Yee on Thu, 12 Sep 1996 02:37:49 +0900) Message-ID: <9609111948.AA12819@arnold.image.ivab.se> > I was just expressing a personal preference about **emphasis**, > *emphasis*, and _emphasis_, but i don't feel as strongly > about that as Fredrik Lundh seems to. Oh, whatever people might think, I'm a pragmatic fellow. If people start using this, I will too. Now could I just find the time to take a careful look at the stuff and use it in PIL 0.2. Regards /F (back from the stables ;-) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Wed Sep 11 21:09:15 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Wed, 11 Sep 1996 15:09:15 -0500 Subject: [PYTHON WEB-SIG] Re: [PYTHON DOC-SIG] HTMLgen and gendoc Message-ID: <199609112009.PAA10294@darwin.rsoc.rockwell.com> |> From: Bill Janssen |> |> Excerpts from ext.python: 11-Sep-96 [PYTHON DOC-SIG] HTMLgen an.. Robin |> Friedrich@rose.rso (526) |> |> > In order to illustrate the results of gendoc 0.6 we've unpacked the |> > HTMLgen online documentation on the python server so you can browse |> > it directly. When you get there, click the Manual button to spawn a |> > new browser with the framed manual autogenerated with gendoc's HTMLgen |> > formatter module. |> |> > http://www.python.org/sigs/web-sig/HTMLgen/html/main.html |> |> Hmmm, not good. I go to my Emacs, type "M-x w3-fetch |> http://www.python.org/sigs/web-sig/HTMLgen/html/main.html", and see |> nothing. Frames are not supported by several useful browsers; I'd like |> to see a solution which doesn't use them. |> |> Bill Not to worry. Gendoc supports vanilla HTML emission via the -f HTML option (which is the default btw). The HTMLgen formatter is for the more tooty-fruity style of pages :-) The vanilla HTML, MIF, and ASCII versions could have been emitted at no extra effort. -Robin ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From janssen@parc.xerox.com Wed Sep 11 21:08:27 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Wed, 11 Sep 1996 13:08:27 PDT Subject: [PYTHON DOC-SIG] New TIM tools, alpha-tester release Message-ID: I've re-written our TIM tools, used for the ILU documentation, as a more general Python script, instead of the extremely constrained Perl script we were using. If you'd like to try it out, and look for problems, it's available as ftp://ftp.parc.xerox.com/pub/ilu/misc/tim.tar.gz. If you aren't sure what TIM is, here's a bit from the README: TIM is essentially a superset of the GNU texinfo language, version 2. It adds several features such as support for pictures and URLs, but its most important extension is to provide domain-specific markup commands to allow adding arbitrary meta-information to Texinfo documents. Introduction ============ Both TIM and Texinfo input files contain text `marked up' with document markup commands. These commands are similar to LaTeX commands, except that they start with an at-sign character rather than a backslash. They contain meta-information about the area of the text to which they apply. For example: A kernel server @dfn{export}s its objects by making them available to other modules. It may do so via one or more @dfn{port}s, which are abstractly a tuple of (@metavar{rpc protocol}, @metavar{transport type}, @metavar{transport address}). For example, a typical port might provide access to a kernel server's objects via @code{(@protocol{Sun RPC}, @transport{TCP/IP}, UNIX port 2076)}. Another port on the same kernel server might provide access to the objects via @code{(@protocol{Xerox Courier}, @transport{XNS SPP}, XNS port 1394)}. When formatted, this paragraph would look like A kernel server exports its objects by making them available to other modules. It may do so via one or more ports, which are abstractly a tuple of (RPC PROTOCOL, TRANSPORT TYPE, TRANSPORT ADDRESS). For example, a typical port might provide access to a kernel server's objects via `(`Sun RPC', `TCP/IP', UNIX port 2076)'. Another port on the same kernel server might provide access to the objects via `(`Xerox Courier', `XNS SPP', XNS port 1394)'. Extensions to GNU Texinfo ========================= TIM removes the need to begin every file with `\input texinfo', and to end every file with `@bye'. These lines are added automatically by TIM as needed. This allows a file to define both a stand-alone document, and to be included as a section in some larger document. TIM Domain-Independent Format ----------------------------- TIM domain-independent format (DIF) is basically Texinfo with four new built-in commands. They are: * `@url', a style command, is used to mark World Wide Web URL forms that appear in the text. * `@picture', a command with arguments, is used to include an Encapsulated Postscript picture into the document. It takes two arguments, the name of the file, and a caption for the picture. The caption may be omitted. * `@ttitalic', a style command, is used to indicate that this span should be rendered in an italic typewriter font, if available. * `@timmacro', a command with arguments, allows the user to define domain-specific markup commands. The two arguments are the macro name, and the macro's replacement in vanilla DIF. For example, to define a style command used to mark Python literals appearing in your document, you'd use a command like @timmacro Python code which defines a new style command `Python', which will be treated like the standard Texinfo command `code' for purposes of output formatting. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From graham@resnet.ucsb.edu Wed Sep 11 23:35:41 1996 From: graham@resnet.ucsb.edu (Graham C. Hughes) Date: Wed, 11 Sep 1996 15:35:41 -0700 Subject: [PYTHON DOC-SIG] Structured documentation syntax In-Reply-To: Your message of "Tue, 10 Sep 1996 09:42:35 EDT." <3235704B.5666@digicool.com> Message-ID: <199609112235.PAA31234@graham.resnet.ucsb.edu> -----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) and . 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 ================= From klm@CNRI.Reston.Va.US Thu Sep 12 05:16:09 1996 From: klm@CNRI.Reston.Va.US (Ken Manheimer) Date: Thu, 12 Sep 1996 00:16:09 -0400 (EDT) Subject: [PYTHON DOC-SIG] Structured documentation syntax In-Reply-To: <199609111844.NAA10237@darwin.rsoc.rockwell.com> Message-ID: On Wed, 11 Sep 1996, Robin Friedrich wrote: > |> From: Ka-Ping Yee > |> > |> Mostly, though, i do still feel that double-quotes aren't > |> really the best choice for hyperlinks (and i don't think > |> any existing doc strings contain hyperlinks, anyway). Are > |> there typical uses of brackets, other than [references], > |> that i haven't thought of? > > This is easy to change. I really didn't care, much I just picked > double quotes out of the air. [] & {} would have worked as well. > I have used this hyperlink feature in my doc strings and it works > fine. Having not kept track of the specifics, i don't know what disqualifies what i would consider the obvious candidate - angle brackets, eg, "". This is the way i've frequently seen URLs distinguished - is there a reason not to use them generally for hyperlinks? Maybe because they specifically imply URLs, or because they're already dedicated to some other purpose? Ken Manheimer klm@cnri.reston.va.us 703 620-8990 x268 (orporation for National Research |nitiatives ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From s-ping@orange.cv.tottori-u.ac.jp Thu Sep 12 05:28:47 1996 From: s-ping@orange.cv.tottori-u.ac.jp (Ka-Ping Yee) Date: Thu, 12 Sep 1996 13:28:47 +0900 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: Message-ID: <3237917F.54DE72AC@sse.tottori-u.ac.jp> Ken Manheimer wrote: > > Having not kept track of the specifics, i don't know what disqualifies > what i would consider the obvious candidate - angle brackets, eg, > "". It probably didn't feel very obvious to me because URLs usually go in them, not the text of hyperlink anchors. But it would be fine with me (as long as Tim doesn't decide he wants to in his documentation). Ping ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From ikds@fashion-forum.de Thu Sep 12 10:25:16 1996 From: ikds@fashion-forum.de (Marc-Andre Lemburg) Date: Thu, 12 Sep 1996 11:25:16 +0200 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: Message-ID: <3237D6FC.56DA8785@fashion-forum.de> Ken Manheimer wrote: > Having not kept track of the specifics, i don't know what disqualifies > what i would consider the obvious candidate - angle brackets, eg, > "". This is the way i've frequently seen URLs > distinguished - is there a reason not to use them generally for > hyperlinks? Maybe because they specifically imply URLs, or because > they're already dedicated to some other purpose? > Why not simply use the Netscape-style of highlighting links, e.g. simply write http://somewhere/outthere and have that converted directly to a link ? (using the http://, ftp://,... as tag to recognize them) ---------------------------------------------------------------------- Marc-Andre Lemburg http://fashion-forum.de/ikds ---------------------------------------------------------------------- Please reply by mailto:ikds@fashion-forum.de, thank you <<< http://www.fashion-forum.de/x.cgi?ikds/python/PythonStuff.html >>> ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From ikds@fashion-forum.de Thu Sep 12 10:44:17 1996 From: ikds@fashion-forum.de (Marc-Andre Lemburg) Date: Thu, 12 Sep 1996 11:44:17 +0200 Subject: [PYTHON DOC-SIG] HTMLgen and gendoc References: <199609111759.MAA10210@darwin.rsoc.rockwell.com> Message-ID: <3237DB71.2FE25230@fashion-forum.de> Robin Friedrich wrote: > > In order to illustrate the results of gendoc 0.6 we've unpacked the > HTMLgen online documentation on the python server so you can browse > it directly. When you get there, click the Manual button to spawn a > new browser with the framed manual autogenerated with gendoc's HTMLgen > formatter module. > > http://www.python.org/sigs/web-sig/HTMLgen/html/main.html I just had a look at the page... nice buttons, but they take too long downloading. Wouldn't a simple text link do as well ? ---------------------------------------------------------------------- Marc-Andre Lemburg http://fashion-forum.de/ikds ---------------------------------------------------------------------- Please reply by mailto:ikds@fashion-forum.de, thank you <<< http://www.fashion-forum.de/x.cgi?ikds/python/PythonStuff.html >>> ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From skip@calendar.com (Skip Montanaro) Thu Sep 12 13:22:54 1996 From: skip@calendar.com (Skip Montanaro) (Skip Montanaro) Date: Thu, 12 Sep 1996 08:22:54 -0400 Subject: [PYTHON DOC-SIG] Structured documentation syntax In-Reply-To: References: <199609111844.NAA10237@darwin.rsoc.rockwell.com> Message-ID: <199609121222.IAA02284@dolphin.automatrix.com> Ken Manheimer writes: Having not kept track of the specifics, i don't know what disqualifies what i would consider the obvious candidate - angle brackets, eg, "". This is the way i've frequently seen URLs distinguished - is there a reason not to use them generally for hyperlinks? Maybe because they specifically imply URLs, or because they're already dedicated to some other purpose? That was my thought also. I believe the "official" way to distinguish URLs in otherwise plain ASCII text is with a URL: prefix, as in: FWIW. Skip Montanaro | Musi-Cal: http://concerts.calendar.com/ skip@calendar.com | Conference Calendar: http://conferences.calendar.com/ (518)372-5583 | Python: http://www.python.org/ ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Thu Sep 12 13:49:21 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Thu, 12 Sep 1996 07:49:21 -0500 Subject: [PYTHON DOC-SIG] Structured documentation syntax Message-ID: <199609121249.HAA10952@darwin.rsoc.rockwell.com> |> From skip@automatrix.com Thu Sep 12 07:25 CDT 1996 |> Date: Thu, 12 Sep 1996 08:22:54 -0400 |> From: Skip Montanaro |> To: klm@CNRI.Reston.Va.US |> Cc: Robin Friedrich , |> s-ping@orange.cv.tottori-u.ac.jp, doc-sig@python.org |> Subject: Re: [PYTHON DOC-SIG] Structured documentation syntax |> Reply-To: skip@calendar.com (Skip Montanaro) |> Content-Type: text |> Content-Length: 802 |> |> Ken Manheimer writes: |> |> Having not kept track of the specifics, i don't know what disqualifies |> what i would consider the obvious candidate - angle brackets, eg, |> "". This is the way i've frequently seen URLs |> distinguished - is there a reason not to use them generally for |> hyperlinks? Maybe because they specifically imply URLs, or because |> they're already dedicated to some other purpose? |> |> That was my thought also. I believe the "official" way to distinguish URLs |> in otherwise plain ASCII text is with a URL: prefix, as in: |> |> |> OK guys. Here's the reasoning. You want the doc string to be as easy to read and devoid of uninformative markups as possible. Placing the actual link address (which can be quite long) in the body of the doc string really hurts that. IMHO moving the link address to a footnote area solves this and still provides enough data for the processor to generate the appropriate HTML. That leaves only some kind of delimiter of what text is to be highlighted in the flow of the text. This I feel preserves the readability of the doc string for those reading source. This idea came from setext. -Robin ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From skip@calendar.com (Skip Montanaro) Thu Sep 12 14:00:08 1996 From: skip@calendar.com (Skip Montanaro) (Skip Montanaro) Date: Thu, 12 Sep 1996 09:00:08 -0400 Subject: [PYTHON DOC-SIG] Structured documentation syntax In-Reply-To: <3237D6FC.56DA8785@fashion-forum.de> References: <3237D6FC.56DA8785@fashion-forum.de> Message-ID: <199609121300.JAA02373@dolphin.automatrix.com> Why not simply use the Netscape-style of highlighting links, e.g. simply write http://somewhere/outthere and have that converted directly to a link ? (using the http://, ftp://,... as tag to recognize them) The problem is in knowing where to stop when the URL is embedded in a sentence. In many operating systems, common punctuation characters (commas, periods, etc) are valid in URLs. So, if I write: Check out the Python documentation at http://www.python.org. Where is the end of the URL? Since the common parenthetical character pairs occur much less frequently in URLs, they become a much safer choice. In particular, using < and > works the best because start and end HTML tags and so must be used in their entity forms (< and >) within a URL (at least in an HTML context). So, it's easy for a dumb program to pick out the URL in the following: Check out the Python documentation at . The "URL:" is pretty much superfluous these days, but there are other address-like things presumably waiting in the wings like URIs (Uniform Resourse Identifiers, I believe) that are supposed to give a measure of location indepence to information. Skip Montanaro | Musi-Cal: http://concerts.calendar.com/ skip@calendar.com | Conference Calendar: http://conferences.calendar.com/ (518)372-5583 | Python: http://www.python.org/ ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From fdrake@CNRI.Reston.Va.US Thu Sep 12 14:18:20 1996 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Thu, 12 Sep 1996 09:18:20 -0400 (EDT) Subject: [PYTHON DOC-SIG] Structured documentation syntax In-Reply-To: <199609121300.JAA02373@dolphin.automatrix.com> from "Skip Montanaro" at Sep 12, 96 09:00:08 am Message-ID: <199609121318.JAA19220@weyr.CNRI.Reston.Va.US> > The "URL:" is pretty much superfluous these days, but there are other > address-like things presumably waiting in the wings like URIs (Uniform > Resourse Identifiers, I believe) that are supposed to give a measure of > location indepence to information. URIs include both URLs and URNs. URNs are Uniform Resource Names, and are location independent. Some systems support format independence as well. Check out ; there are some interesting links at the bottom of the page. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Thu Sep 12 14:42:47 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Thu, 12 Sep 1996 09:42:47 -0400 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: <199609121249.HAA10952@darwin.rsoc.rockwell.com> Message-ID: <32381357.3457@digicool.com> Robin Friedrich wrote: > > |> From skip@automatrix.com Thu Sep 12 07:25 CDT 1996 > |> Date: Thu, 12 Sep 1996 08:22:54 -0400 > |> From: Skip Montanaro > |> To: klm@CNRI.Reston.Va.US > |> Cc: Robin Friedrich , > |> s-ping@orange.cv.tottori-u.ac.jp, doc-sig@python.org > |> Subject: Re: [PYTHON DOC-SIG] Structured documentation syntax > |> Reply-To: skip@calendar.com (Skip Montanaro) > |> Content-Type: text > |> Content-Length: 802 > |> > |> Ken Manheimer writes: > |> > |> Having not kept track of the specifics, i don't know what disqualifies > |> what i would consider the obvious candidate - angle brackets, eg, > |> "". This is the way i've frequently seen URLs > |> distinguished - is there a reason not to use them generally for > |> hyperlinks? Maybe because they specifically imply URLs, or because > |> they're already dedicated to some other purpose? > |> > |> That was my thought also. I believe the "official" way to distinguish URLs > |> in otherwise plain ASCII text is with a URL: prefix, as in: > |> > |> > |> > > OK guys. Here's the reasoning. > You want the doc string to be as easy to read and devoid of > uninformative markups as possible. Placing the actual link address > (which can be quite long) in the body of the doc string really hurts > that. IMHO moving the link address to a footnote area solves this and > still provides enough data for the processor to generate the > appropriate HTML. That leaves only some kind of delimiter of what text > is to be highlighted in the flow of the text. This I feel preserves the > readability of the doc string for those reading source. This idea came > from setext. Absolutely. I like the idea of using []s. Furthermore, I can see a usage where instead of saying: blah blah blah [spam] blah blah .... .. [spam] http://... One could say: blah blah blah spam [42] blah blah .... .. [42] http://... Where "[42]" gets highlighted. Which I would fine more readable as text and just as readable as hypertext. It would also be useful to define a URL hierarchy for gendoc and allow relative references in footnotes, so that a doc string could include links to documentation for other objects in the same module or other modules. This would also help to reduce HTML dependencies. For example, relative references might work for info files as well. Jim -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ## ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Thu Sep 12 15:03:15 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Thu, 12 Sep 1996 09:03:15 -0500 Subject: [PYTHON DOC-SIG] Structured documentation syntax Message-ID: <199609121403.JAA11443@darwin.rsoc.rockwell.com> |> Date: Thu, 12 Sep 1996 09:42:47 -0400 |> From: Jim Fulton ... |> I like the idea of using []s. |> |> Furthermore, I can see a usage where instead of saying: |> |> blah blah blah [spam] blah blah |> |> .... |> |> .. [spam] http://... |> |> One could say: |> |> blah blah blah spam [42] blah blah |> |> .... |> |> .. [42] http://... |> |> Where "[42]" gets highlighted. Which I would fine more readable |> as text and just as readable as hypertext. |> |> It would also be useful to define a URL hierarchy for gendoc |> and allow relative references in footnotes, so that a doc string could |> include links to documentation for other objects in the same module |> or other modules. This would also help to reduce HTML dependencies. |> For example, relative references might work for info files as well. OK now where getting somewhere. Does anyone volunteer to hack something up to try out? ;-) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Thu Sep 12 15:14:42 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Thu, 12 Sep 1996 10:14:42 -0400 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: <199609121403.JAA11443@darwin.rsoc.rockwell.com> Message-ID: <32381AD2.1979@digicool.com> Robin Friedrich wrote: > > |> Date: Thu, 12 Sep 1996 09:42:47 -0400 > |> From: Jim Fulton > ... > |> I like the idea of using []s. > |> > |> Furthermore, I can see a usage where instead of saying: > |> > |> blah blah blah [spam] blah blah > |> > |> .... > |> > |> .. [spam] http://... > |> > |> One could say: > |> > |> blah blah blah spam [42] blah blah > |> > |> .... > |> > |> .. [42] http://... > |> > |> Where "[42]" gets highlighted. Which I would fine more readable > |> as text and just as readable as hypertext. > |> > |> It would also be useful to define a URL hierarchy for gendoc > |> and allow relative references in footnotes, so that a doc string could > |> include links to documentation for other objects in the same module > |> or other modules. This would also help to reduce HTML dependencies. > |> For example, relative references might work for info files as well. > > OK now where getting somewhere. Does anyone volunteer to hack something > up to try out? ;-) Hm. Well, for the first part, "" -> [], I assume that this would be a fairly minor change. The second part needs some thinking by someone who is very familiar with the URL hierarchy defined by gendoc. (Is this documented somewhere?) My thought is that the hierarchy should be reviewed before any hacking takes place. To me, this feels like an exercise for the gendoc author. Jim > > ================= > DOC-SIG - SIG for the Python Documentation Project > > send messages to: doc-sig@python.org > administrivia to: doc-sig-request@python.org > ================= -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ## ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Thu Sep 12 15:30:30 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Thu, 12 Sep 1996 09:30:30 -0500 Subject: [PYTHON DOC-SIG] Structured documentation syntax Message-ID: <199609121430.JAA11461@darwin.rsoc.rockwell.com> |> Date: Thu, 12 Sep 1996 10:14:42 -0400 |> From: Jim Fulton |> |> Robin Friedrich wrote: |> > OK now where getting somewhere. Does anyone volunteer to hack something |> > up to try out? ;-) |> |> Hm. Well, for the first part, "" -> [], I assume that this would be |> a fairly minor change. trivial. |> |> The second part needs some thinking by someone who is very familiar |> with the URL hierarchy defined by gendoc. (Is this documented |> somewhere?) My thought is that the hierarchy should be reviewed |> before any hacking takes place. To me, this feels like an exercise |> for the gendoc author. True. But he's in Barcelona for 4 weeks. Can we at least define the features/requirements for such a thing while he's gone? Other things he wondered outload to me was an approach for representing packages. Any thoughts? ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From s-ping@orange.cv.tottori-u.ac.jp Thu Sep 12 15:52:11 1996 From: s-ping@orange.cv.tottori-u.ac.jp (Ka-Ping Yee) Date: Thu, 12 Sep 1996 23:52:11 +0900 Subject: [PYTHON DOC-SIG] Structured documentation syntax References: <199609121403.JAA11443@darwin.rsoc.rockwell.com> Message-ID: <3238239B.4B3EFF03@sse.tottori-u.ac.jp> Skip Montanaro wrote: > That was my thought also. I believe the "official" way to > distinguish URLs in otherwise plain ASCII text is with a > URL: prefix, as in: > > It is, but (as i said in response to Ken M.) i thought we were talking about the hyperlinked *text*, not the URL. Jim Fulton wrote: > One could say: > > blah blah blah spam [42] blah blah > > .... > > .. [42] http://.. > > Where "[42]" gets highlighted. Which I would fine more readable > as text and just as readable as hypertext. This is exactly what i had in mind when i suggested [], as this kind of usage is fairly common practice. Sometimes the brackets contain numbers, sometimes small identifiers like [ROSSUM96], or the author can choose to just [use the flow] of text. Robin Friedrich wrote: > OK now where getting somewhere. Does anyone volunteer to > hack something up to try out? ;-) Sorry, but i thought gendoc already implemented this? It looks like all you'd have to do is change a couple of lines in docregex.py. Line 86 defines hypertext_regex as: regex.compile('\([ \t\n]\)\"\([^"\n]*\)\"' + endm) ^^ ^^ make that \[ and \] and line 90 defines hyperdef_word as: hyperdef_word = '"\\([^"\n]*\\)"' ^ ^ make that \[ and \] Or am i missing something? Unfortunately, i can't test this out because whenever i run 'gendoc', i always get Traceback (innermost last): File "./gendoc", line 2, in ? import ni File "/usr/local/lib/python1.4/ni.py", line 435, in ? install() . . . File "./__init__.py", line 1, in ? path = __.__path__[0] TypeError: unsubscriptable object I would like to see 'gendoc' in action, so if someone knows what's going wrong here, please let me know. (I'm using a recently-downloaded release 0.6.) By the way, can i put in a plug for RE_SYNTAX_AWK here? They would be an awful lot easier to read, what with all the parentheses you don't have to backslash. Ping ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Thu Sep 12 16:41:58 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Thu, 12 Sep 1996 10:41:58 -0500 Subject: [PYTHON DOC-SIG] Structured documentation syntax Message-ID: <199609121541.KAA11489@darwin.rsoc.rockwell.com> |> Date: Thu, 12 Sep 1996 23:52:11 +0900 |> From: Ka-Ping Yee |> |> Skip Montanaro wrote: |> > That was my thought also. I believe the "official" way to |> > distinguish URLs in otherwise plain ASCII text is with a |> > URL: prefix, as in: |> > |> > |> |> It is, but (as i said in response to Ken M.) i thought we |> were talking about the hyperlinked *text*, not the URL. |> |> Jim Fulton wrote: |> > One could say: |> > |> > blah blah blah spam [42] blah blah |> > |> > .... |> > |> > .. [42] http://.. |> > |> > Where "[42]" gets highlighted. Which I would fine more readable |> > as text and just as readable as hypertext. |> |> This is exactly what i had in mind when i suggested [], as |> this kind of usage is fairly common practice. Sometimes the |> brackets contain numbers, sometimes small identifiers like |> [ROSSUM96], or the author can choose to just [use the flow] |> of text. |> |> Robin Friedrich wrote: |> > OK now where getting somewhere. Does anyone volunteer to |> > hack something up to try out? ;-) |> |> Sorry, but i thought gendoc already implemented this? It |> looks like all you'd have to do is change a couple of lines |> in docregex.py. |> ... |> Or am i missing something? I was refering to the internal reference scheme Jim had in mind. The external reference scheme is implimented and works fine. And yes, the above trivial change with make the delimiters brackets rather that quotes. This seems to be the consensus so it'll change in the next release. (or in your local copy) |> |> Unfortunately, i can't test this out because whenever i |> run 'gendoc', i always get |> |> Traceback (innermost last): |> File "./gendoc", line 2, in ? |> import ni |> File "/usr/local/lib/python1.4/ni.py", line 435, in ? |> install() |> . |> . |> . |> File "./__init__.py", line 1, in ? |> path = __.__path__[0] |> TypeError: unsubscriptable object |> |> I would like to see 'gendoc' in action, so if someone |> knows what's going wrong here, please let me know. |> (I'm using a recently-downloaded release 0.6.) |> OK this is a symptom of trying to run the gendoc script in place. It needs to be moved somewhere in your $PATH. The make install would do this, but you have to have GNU make:-( The gendoc directory should be in your PYTHONPATH. The gendoc script should be in your PATH. |> By the way, can i put in a plug for RE_SYNTAX_AWK |> here? They would be an awful lot easier to read, what |> with all the parentheses you don't have to backslash. Plug away:-) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From klm@CNRI.Reston.Va.US Fri Sep 13 19:20:21 1996 From: klm@CNRI.Reston.Va.US (Ken Manheimer) Date: Fri, 13 Sep 1996 14:20:21 -0400 (EDT) Subject: [PYTHON DOC-SIG] Structured documentation syntax In-Reply-To: <3238239B.4B3EFF03@sse.tottori-u.ac.jp> Message-ID: On Thu, 12 Sep 1996, Ka-Ping Yee wrote: > Skip Montanaro wrote: > > That was my thought also. I believe the "official" way to > > distinguish URLs in otherwise plain ASCII text is with a > > URL: prefix, as in: > > > > > > It is, but (as i said in response to Ken M.) i thought we > were talking about the hyperlinked *text*, not the URL. That was my confusion. And i also prefer the square bracketing for the text-to-footnote (or whatever) coupling... Ken Manheimer klm@cnri.reston.va.us 703 620-8990 x268 (orporation for National Research |nitiatives # If you appreciate Python, consider joining the PSA! # # . # ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From Barry A. Warsaw" <0mBkoa4B0KGW04Emc3@holmes.parc.xerox.com> Message-ID: <199609161727.NAA05376@anthem.CNRI.Reston.Va.US> >>>>> "BJ" == Bill Janssen writes: BJ> Hmmm, not good. I go to my Emacs, type "M-x w3-fetch BJ> http://www.python.org/sigs/web-sig/HTMLgen/html/main.html", BJ> and see nothing. Frames are not supported by several useful BJ> browsers; I'd like to see a solution which doesn't use them. It shouldn't be too difficult to generate both Frame and non-Frame versions from a single base. That would be pretty useful! -Barry ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Thu Sep 19 16:44:25 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Thu, 19 Sep 1996 11:44:25 -0400 Subject: [PYTHON DOC-SIG] New Module StructuredText Message-ID: <3241580A.767D@digicool.com> This is a multi-part message in MIME format. --------------23206CC4745 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit I've added logic so that paragraphs that end with '::' and that have subparagraphs introduce sample code. This was necessary becaus it sometimes doesn't make sense to end the introductory paragraph with the word 'example'. I propose that this be incorporated into gendoc. See: http://www.digicool.com/jim/python/StructuredText.html Jim -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ## Python is my favorite language ## ## http://www.python.org/ ## --------------23206CC4745 Content-Type: text/html; charset=us-ascii; name="StructuredText.html" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="StructuredText.html" Content-Base: "http://www.digicool.com/jim/python/Str ucturedText.html" Module StructuredText

StructuredText

Structured Text Manipulation

Description

Parse a structured text string into a form that can be used with structured formats, like html.

Structured text is text that uses indentation and simple symbology to indicate the structure of a document.

A structured string consists of a sequence of paragraphs separated by one or more blank lines. Each paragraph has a level which is defined as the minimum indentation of the paragraph. A paragraph is a sub-paragraph of another paragraph if the other paragraph is the last preceedeing paragraph that has a lower level.

Special symbology is used to indicate special constructs:

  • A paragraph that begins with a -, *, or o is treated as an unordered list (bullet) element.

  • A paragraph that begins with a sequence of digits followed by a white-space character is treated as an ordered list element.

  • A paragraph that begins with a sequence of sequences, where each sequence is a sequence of digits or a sequence of letters followed by a period, is treated as an ordered list element.

  • A paragraph with a first line that contains some text, followed by some white-space and -- is treated as a descriptive list element. The leading text is treated as the element title.

  • Sub-paragraphs of a paragraph that ends in the word example or the word examples, or :: is treated as example code and is output as is.

  • Text enclosed single quotes (with white-space to the left of the first quote and whitespace or puctuation to the right of the second quote) is treated as example code.

  • Text surrounded by * characters (with white-space to the left of the first * and whitespace or puctuation to the right of the second *) is emphasized.

  • Text surrounded by ** characters (with white-space to the left of the first ** and whitespace or puctuation to the right of the second **) is emphasized.

Module Functions

indent_level(aString)

Find the minimum indentation for a string, not counting blank lines.

untabify(aString)

Convert indentation tabs to spaces.

Class HTML (StructuredText)

An HTML structured text formatter.

Constructor For HTML

StructuredText(aStructuredString, [level])

Convert a string containing structured text into a structured text object.

Aguments:

aStructuredString

The string to be parsed. level -- The level of top level headings to be created.

General Services Provided by HTML

str(aHTML)

Return an HTML string representation of the structured text data.

Class StructuredText

Model text as structured collection of paragraphs.

Structure is implied by the indentation level.

This class is intended as a base classes that do actual text output formatting.

Constructor For StructuredText

StructuredText(aStructuredString, [level])

Convert a string containing structured text into a structured text object.

Aguments:

aStructuredString

The string to be parsed. level -- The level of top level headings to be created.

General Services Provided by StructuredText

str(aStructuredText)

Convert a StructuredText to a string.

Download StructuredText.py
Last Modified: 17 September 1996 --------------23206CC4745-- ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From friedric@rose.rsoc.rockwell.com Thu Sep 19 17:00:51 1996 From: friedric@rose.rsoc.rockwell.com (Robin Friedrich) Date: Thu, 19 Sep 1996 11:00:51 -0500 Subject: [PYTHON DOC-SIG] New Module StructuredText Message-ID: <199609191600.LAA26653@darwin.rsoc.rockwell.com> |> From owner-doc-sig@python.org Thu Sep 19 10:57 CDT 1996 |> Date: Thu, 19 Sep 1996 11:44:25 -0400 |> From: Jim Fulton |> Organization: Digital Creations, L.C. |> X-Mailer: Mozilla 3.0b5 (WinNT; I) |> Mime-Version: 1.0 |> To: doc-sig@python.org |> Subject: [PYTHON DOC-SIG] New Module StructuredText |> Sender: owner-doc-sig@python.org |> Content-Type: multipart/mixed; boundary="------------23206CC4745" |> Content-Length: 5522 |> |> I've added logic so that paragraphs that end with '::' and that have |> subparagraphs introduce sample code. This was necessary becaus it |> sometimes doesn't make sense to end the introductory paragraph with the |> word 'example'. I propose that this be incorporated into gendoc. Cool. You got my vote. |> |> See: http://www.digicool.com/jim/python/StructuredText.html |> |> Jim |> |> -- |> Jim Fulton Digital Creations |> jim@digicool.com 540.371.6909 |> ## Python is my favorite language ## |> ## http://www.python.org/ ## ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From s-ping@orange.cv.tottori-u.ac.jp Fri Sep 20 07:03:37 1996 From: s-ping@orange.cv.tottori-u.ac.jp (Ka-Ping Yee) Date: Fri, 20 Sep 1996 15:03:37 +0900 Subject: [PYTHON DOC-SIG] Re: New Module StructuredText References: <3241580A.767D@digicool.com> Message-ID: <324233B9.7CA7EAEA@sse.tottori-u.ac.jp> Jim Fulton wrote: > > I've added logic so that paragraphs that end with '::' and that have > subparagraphs introduce sample code. This was necessary becaus it > sometimes doesn't make sense to end the introductory paragraph with the > word 'example'. I propose that this be incorporated into gendoc. This is a cool idea. What about "variables" in documentation? For instance, you may want to describe an HTTP URL as http://:/ In HTML you would use the tag for this. The common text usage, i believe, is to use as i have done above, and the common print rendering is italic. This is a fairly often-used element in technical documentation. Do you expect people to just use *emphasis* for this? Or could i suggest using specifically for descriptive names that take the place of other things? Ping 3B Computer Engineering, Waterloo (on exchange in Tottori, Japan) http://www.lfw.org/math/ brings math to the Web as easy as ?pi? ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org =================