Mailman 3 February 2000 - Doc-SIG

Forthcoming doc release; request for help
by Fred L. Drake, Jr. March 1, 2000

March 1, 2000

Yes, the rumors are true: I'm planning to release the documentation for Python 1.5.2 one more time. The current target date is 17 March. Here's my planned schedule for short-term activity: Feb 29: Release documentation packages to Doc-SIG for review Mar 17: Release documentation version 1.5.2p2 (last 1.5.2 release) Apr 17: Finish merging 1.5.2p2 into documentation for 1.6 There are a couple of things I'd like help with. ;) First, I try to go throught the HTML version every so often using major browsers on major platforms. I *don't* have access to all platforms, though, and just don't have time to test for each major browser for each platform, and that's only gotten worse the last couple of releases. Second, I haven't been able to "close-read" the documentation for a long time; this is valuable to catch confusing passages, the random typo, and effects of whitespace-gobbling nanoviruses. Catching statements that are just plain wrong is also an important goal. Clearly, the second goal can be met while meeting the first goal; if you shoot for the second, the first falls out, at least for one browser/platform combination, but it requires a more substantial time commitment than browser-testing the HTML. I've often used a printed version for the close-reading instead of using the HTML. What I'm doing is asking for volunteers to help; with enough eyes, the work is highly partionable. If each of us picks one or more documents (the library reference can be partitioned by chapter) and a particular browser/platform combo, this shouldn't be too hard. I'd like to hit at least the following browser/platform combinations: MSIE 5.0 Windows, MacOS(?) Navigator 4.x Windows, MacOS, Unix Opera Windows, MacOS(?), Linux Mozilla M13 Windows, MacOS, Unix (I haven't been able to run the M13 binary for Solaris 2.6 on my 2.7 box; has anyone succeeded at this? The M12 runs OK... for a little while. I've not yet checked M13 for other platforms.) Could someone with a MacOS box please check that all the filenames, at least for the generated HTML, aren't too long or otherwise cause problems with HFS? Thanks! I can coordinate as well as do a portion of the work; who'll volunteer? -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives

3 4

Crystal 0.2
by Laurence Tratt Feb. 24, 2000

Feb. 24, 2000

Sorry for all those of you who may have experienced problems downloading Crystal 0.1; I'd completely forgotten that the web server it's on has a tendency to distribute .gz files as plain text with all the problems that that causes. Therefore to make up I'm making available Crystal 0.2 (24 February 1999) which is distributed in .zip format (as a temporary fix) and contains a few new things including indices. Crystal can be downloaded from: http://eh.org/~laurie/comp/python/crystal/ I have also updated the sample output on the webpage to give people a better idea of what Crystal can do. If you thought that automatically created Python module/packge documentation had to be ugly, hopefully the sample output can go some way to persuading you it can be functional and fairly pretty! For those of you wondering *what* Crystal is, it is a tool in the javadoc/pythondoc vein (with quite a lot of extra features on top of those two tools). Although in its very early stages, it is already capable of useful work as evidenced by the sample output on the webpage. Laurie

1 0

Documentation: "Installing Python Modules"
by Greg Ward Feb. 24, 2000

Feb. 24, 2000

Hi all -- well, I finally sat down and started spewing Distutils documentation. My plan is to write two howto-style manuals (maybe a bit bigger than "Documenting Python", but along those lines) to be included in the 1.6 manual set. (Clever of me to announce this intention in public before mentioning it to Fred or Guido, just to make it harder for them to tell me to get stuffed. ;-) The two manuals are tentatively entitled: Installing Python Modules Distributing Python Modules So far, I have written one section of the "Installing" manual, entitled "Custom Installation (Unix)". This one is kind of important: it explains how to use the Distutils to install modules to any non-standard place, with lots of commentary on good practices and multi-platform installations. I want feedback on this on several axes: * Distutils terminology: eg. does "install-lib" mean what you think it should mean, or do you have a better idea? * Distutils semantics: eg. is the behaviour of "install-lib" sensible? * documentation organization * documentation wording * spelling, typos, typesetting, etc. The docs are available at http://www.python.org/sigs/distutils-sig/documentation.html Currently only LaTeX source and PDF available -- HTML soon. -- Greg Ward - programmer-at-large gward(a)python.net http://starship.python.net/~gward/ If it can't be expressed in figures, it is not science--it is opinion.

1 0

pythondoc on mac; multi-platform file names
by David Goodger Feb. 23, 2000

Feb. 23, 2000

I am attempting to use Daniel Larsson's pythondoc (http://starship.python.net/crew/danilo/pythondoc/) on MacOS, and am running into trouble. Pythondoc wants to create files with names like 'module.class.html'. When the total is over 31 characters (Mac's filename length limit), pythondoc fails. I could hack the code to make it work, but I'd rather do something general which could be included in the next release. Also, there are inter-file cross references to consider. 1. Has anyone else successfully used pythondoc on MacOS, perhaps with modifications? If so, I'd like to see any modifications, or at least hear how you got around the OS problems. 2. Is there a general-purpose file naming utility module for Python which gets around the limitations of various operating systems? Perhaps something that checks the validity of a name, or creates a unique name (for a specified directory) based on the input. Mac files can have spaces & puntuation (except colon ':') in their names, but are limited to 31 characters. DOS (does anyone still use DOS? :-) is 8.3. Unix & Windows have their own (hard or soft) rules. I like Python for its multi-platform capabilities (among many other aspects). This type of utility would make multi-platform programming that much easier. Thanks. -- David Goodger dgoodger(a)bigfoot.com

1 0

Crystal 0.1
by Laurence Tratt Feb. 22, 2000

Feb. 22, 2000

I'd like to make a sort of low key announcement about a very early version of a new tool in the gendoc/pythondoc/javadoc mould. It's called Crystal and 0.1 is the first public version. I have been creating this system as part of my final year undergraduate project, so at the moment it's subject to whatever license my university wants to put on it. This first version is *very* rough, not very ready and has much unimplemented, much buggy etc. There is no documentation. There's no guaranteed support (but I'll try). If you're still not put off, here are some things worth noting: * Has plugin support for different languages, different doc string styles and different output formats (Currently only Python, StructuredText & HTML3 implemented though) * Flexible output (using a built in page layout language) * Good quality output (needs some work though) * Parses rather than imports .py files Here are some less good things worth noting: * StructuredText is *not* implemented using Jim Fulton's module, was only implemented today, and may be very weird * No indices yet * No list of inherited methods / fields etc yet; HRefs between pages mostly lacking * Not widely tested (though it runs OKish over the standard 1.5.2 library); Crystal has only been run on a couple of Unix machines * Lots of other little things not implemented * Has a tendency to show up Netscape 4.x tables limitations * Uses CPython parser interface; may not work under other Python implementations The download URL is: http://eh.org/~laurie/comp/python/crystal/ I have put up a few demonstration pages (including a file or two from the standard Python library as a point of comparison) on the web site to give people a vague idea of what Crystal does. I'm making this release because although this is early days, this might still be useful to some people; at the least, it's got some ideas which I don't think are seen in any other such tools, and so it might be useful to people doing the same sort of thing. Installation is currently a simple decompress. Crystal makes use of SPARK, and my thanks to John Aycock for that brilliant little package. If anyone has any comments, please feel free to mail me (or discuss it on the doc-sig), and happy documentation creating! Laurie

1 0

Documentation patches
by Fred L. Drake, Jr. Feb. 14, 2000

Feb. 14, 2000

I've just updated the page at python.org/patches/ to ask that documentation patches be sent to python-docs(a)python.org, with specific bug reports to be submitted through the bugs database (which I monitor). Hopefully this will clarify what should happen for documentation issues. It also means that the published documentation on the Web site isn't out of date! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives

1 0

MiniBloquiHeader
by Manuel Gutierrez Algaba Feb. 13, 2000

Feb. 13, 2000

I've just released MiniBloquiHeader http://www.ctv.es/USERS/irmina/Mini/MiniBloquiHeader.html very interesting for anybody that writes doc y TeX/LaTeX Regards/Saludos Manolo www.ctv.es/USERS/irmina /TeEncontreX.html /texpython.htm /pyttex.htm I'm going to live forever, or die trying! -- Spider Robinson

1 0

Cross-reference proposal
by Ka-Ping Yee Feb. 10, 2000

Feb. 10, 2000

One useful thing we can accomplish, as others have pointed out, is to come up with clear and simple rules for referring to other objects in documentation. To start things off, let me try proposing a set of lookup rules for people to evaluate and shoot down. I list the rules to be applied in order of decreasing priority. When a rule applies but the referent object does not exist, we proceed to test any lower-priority rules that apply. Note that simple bare words are never interpreted as references. To refer to something, an identifier must be capitalized and match a class name, or be followed with an open-parenthesis and match a function or method name, or be preceded by "self.". 1. Text: "self." <identifier> "(" In: class or method docstring Example: "self.foo(" mentioned in class "Zot" a. Refers to: method Zot.foo() b. Refers to: method foo() inherited by Zot 2. Text: "self." <identifier> In: class or method docstring Example: "self.foo" mentioned in class "Zot" a. Refers to: attribute "foo" of Zot instances 3. Text: [ <identifier> "." ]+ <capitalized-identifier> In: any docstring Example: "pkg.bar.Zot" a. Refers to: class pkg.bar.Zot 4. Text: [ <identifier> "." ]+ <identifier> "(" In: any docstring Example: "pkg.bar.foo(" a. Refers to: function pkg.bar.foo() 5. Text: <capitalized-identifier not preceded by "."> In: any docstring Example: "Zot" mentioned in module "bar" a. Refers to: class bar.Zot 6. Text: <identifier not preceded by "."> "(" In: module or function docstring Example: "foo(" mentioned in module "bar" a. Refers to: function bar.foo() 7. Text: <identifier not preceded by "."> "(" In: class or method docstring Example: "foo(" mentioned in class "Zot" in module "bar" a. Refers to: method Zot.foo() b. Refers to: method foo() inherited by Zot c. Refers to: function bar.foo() I have attempted to make this set of rules complete while having the "obvious" behaviour. Is the suggested behaviour sufficiently obvious? I am aiming to eliminate the possibility that these rules ever fail in an unexpected way. #7 may be a bit much, but i would like to hear your opinions. I think i am comfortable with #7a,b,c. Have a look at each rule and see if you can imagine a case where it will do the wrong thing. I hope to be able to claim that each rule "just has to be right". Thanks for your time and input! -- ?!ng

7 24

Poll-schmoll, READ THIS!
by Fred L. Drake, Jr. Feb. 9, 2000

Feb. 9, 2000

Doc-SIG readers, This is a long message, but please read it. Moshe Zadka writes: > Authority. Because arbitrary decisions (and it *is* arbitrary) should be > made by someone, and then followed. Same reason standards aren't done > by poles. At some point, I will make a recommendation to Guido substantially based on what comes out of this SIG. He will say "yes" or "fix ....", and that will be that. [What follows refers specifically to embedded documentation.] What *I'm* looking for is something to hand to Guido, with an implementation on hand. I want tools that don't require the import of a module's source code. I want it to produce a data structure that can be stored persistently, and I want to be able to produce really nice HTML. I want it written in 100% Python and work with both the CPython and JPython interpreters. Once this is available, I can start dealing with support for multiple formats and that sort of thing. [Back to your regularly scheduled SIG!] I think this SIG has made progress in fits and starts for a variety of reasons, including insufficient availability of my time to implement suggestions or keep up with the discussions. On the other hand, we have seen a number of things start to coalesce recently (never mind that they seem about to fall apart some days). While David seems to think we got very little out of the Doc-SIG session at the conference, I don't agree. David's current stance on StructuredText is good; it leverages existing work more than previous proposals and keeps the markup for embedded documentation quite minimal. It appears that sufficient support for rich hyperlinking can be built without costing too much. Let's support David and the StructuredText people so this can be a fruitful effort. What I got out of the conference was that the most important thing was to quite bickering about syntax and decide on one format for embedded documents and one for out-of-line documents. The attendees at the session seemed to be largely unconcerned about the specific syntax used. For inline, we've agreed here that the syntax should be minimal and that "just-text" docstrings should work. I stated that they would work *well*, so that's a specific requirement for tool builders on this one. I also got the message that nobody really cares about the SGML vs XML debate (it *is* a minor detail), and nobody really cares about the specific DTD. I will write one based on the existing conversion project; we can hash out details here a bit, but it will be frozen relatively quickly. I'll need someone to write stylesheets for typesetting; DSSSL or XSLT/XSL would be fine. We may be able to do the HTML conversion using DSSSL or XSLT as well; if so, I'd like to use the same stylesheet language for that if possible in order to keep the required tool set small, but whether we use multiple stylesheets or one parameterized stylesheet (a la Norm Walsh's modular stylesheets for DocBook) isn't terribly important. We will support at least HTML and one typeset format before we can "cut over" documentation maintenance to the new system. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> Corporation for National Research Initiatives

2 1

Docstring: a newbie's two bits
by David Goodger Feb. 8, 2000

Feb. 8, 2000

Let me introduce myself. I am an experienced programmer with a plethora of languages under my belt (C/C++, Pascal, the dreaded BASIC, Lisp/Scheme, Perl, csh/ksh/bash scripting, AppleScript, and others in passing). I delved into Python about a year ago, and loved it. I have 3 years intense experience in an SGML analysis/design/processing environment. I have been reading the Doc SIG digests for about a week, plus some back issues from the archive. Please forgive me if I cover old ground. I am about to release a set of (relatively small) open-source libraries & tools. I have been using the docstring mechanism for internal documentation all along, and was delighted to find there were tools available to extract & mark up docstrings into something usable as documentation. Imagine my relief when I learned that I didn't *have* to use TeX if I wanted to use standard tools! As a newbie, without any affiliation to one approach or another, I thought I'd give you some opinions about the current docstring discussions. Please take it as a vote from a typical (atypical?) member of the intended audience. No offense to anyone is intended (nor, I hope, taken). They take a little getting used to, but the rules of Structured Text (as at http://www.python.org/sigs/doc-sig/stext.html) are easy to apply. I wouldn't want to see much more tagging than this, however. I use docstrings as working documentation, to be written in parallel with (ok, slightly *after*) writing the code. And I refer to this documentation also, so it **must** be readable (see? I'm already using the StructText conventions!). The docstring documentation (as output by the tools) would only be a start for final publication-quality documentation, however, so I'm not worried about lack of fine-tweaking control. HTML is great for quick & dirty user documentation or for on-screen display, but its formatting-oriented tagging makes it next to useless for anything more ambitious. I am pleased to hear that an effort is underway to create an SGML/XML DTD, a la DocBook (PyBook?) or whatever. Specifics: - I would not use any kind of [tag content] or tag[content] or <tag/content/ explicit tagging. It's too confusing when reading the code itself. It's a fine line that must not be crossed if this docstring proposal is going to be used widely. - I do like the output of Ka-Ping Yee's manpy very much (colouring aside :-). When will it be available? This is what I call "usable" documentation. Little more is needed at this level. - Edward Welbourne's example (below) makes sense to me. Using quotes as implicit "code" tagging would interfere with using them as explicit content, and I don't see a better candidate than # on my keyboard. However, I am uncomfortable with the "!" (exclamation point). Is there a reason why ":" (colon) shouldn't be used? I think "mode : string" looks a lot more natural. Arguments: mode ! string -- the file access mode string ... If #mode#'s first letter is #'r'#, #file# must exist. -- David Goodger (pronounced as in "badger", but good) dgoodger(a)bigfoot.com

1 0