Mailman 3 June 2001 - Doc-SIG

Error in pyexpat docs
by uche.ogbuji＠fourthought.com July 9, 2002

July 9, 2002

An excerpt from the Python 2.0 docs for pyexpat: """ ParseFile (file) Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, returning the empty string when there's no more data. [snip] The following attributes contain values relating to the most recent error encountered by an xmlparser object, and will only have correct values once a call to Parse() or ParseFile() has raised a xml.parsers.expat.error exception. ErrorByteIndex Byte index at which an error occurred. [etc.] """ The wrong, "xml.parsers.expat" is the first indicator that there might be a problem, yet I took the docs at their word and wrapped the call to ParseFile in a blanket try/except, only to find that no exception of any sort is ever raised by ParseFile. It turns out that ParseFile actually returns 0 on error, returning 1 otherwise. The first matter is that the code and the docs need to be reconciled. However, I would _much_ rather prefer that things were as in the docs. I think ParseFile should raise an exception rather than return an error flag. Interestingly enough, this is the same argument I had with a colleague just last week. -- Uche Ogbuji Principal Consultant uche.ogbuji(a)fourthought.com +1 303 583 9900 x 101 Fourthought, Inc. http://Fourthought.com 4735 East Walnut St, Ste. C, Boulder, CO 80301-2537, USA Software-engineering, knowledge-management, XML, CORBA, Linux, Python

3 2

Python 2.1 docs in GNU info format
by Fred L. Drake, Jr. June 29, 2001

June 29, 2001

Milan Zamazal has contributed Python 2.1 documentation in GNU info format. It is available on python.org: ftp://ftp.python.org/pub/python/doc/2.1/ and on SourceForge: http://sourceforge.net/project/showfiles.php?group_id=5470&release_id=41415 Thanks, Milan! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Digital Creations

1 0

Announce: RTX 1.0.0 yet another plain-text-ish markup
by Mark Summerfield June 27, 2001

June 27, 2001

Hi, If you're interested in plain text-ish markup you might find RTX of interest: http://www.ourobourus.com It is vaguely reminiscent of doxygen since it takes lots of ideas from qdoc (of which doxygen is a public implementation). Basically you can write with a minimally intrusive markup and produce HTML, SGML (docbook), Lout (which generates postscript and PDF) and plain text. It handles lists and tables as well as 'categorising' markup, e.g. \key Alt+F. It does not support much 'formatting' markup, e.g. fonts etc. in the text itself, but you have considerable control over how the output works in the supported formats (so you can control fonts, colours etc. globally for consistency by changing simple configuration files). It is quite easy to subclass to produce your own format (it's all written in pure Python). I don't use it to markup Python code, at least not yet, but doing so should be straightforward. Below are some notes on this possibility (but extracting marked up text from Python code isn't supported yet -- but hopefully will be soon). Here's how a fragment of David Goodger's documentation looks using his reStructuredText: def __init__(self, stateclasses, initialstate, debug=0): """ Initialize a `StateMachine` object; add state objects. Parameters: - `stateclasses`: a list of `State` (sub)classes. - `initialstate: a string, the name of the initial state (class name). - `debug`: a boolean; produce verbose output if true (nonzero). """ here's how you'd achieve the same thing using RTX (only I wouldn't do this; see the final example): def __init__(self, stateclasses, initialstate, debug=0): """ Initialize a \class StateMachine object; add state objects. Parameters: \list \e \p stateclasses a list of \class State (sub)classes. \e \p initialstate a string, the name of the initial state (class name). \e \p debug a boolean; produce verbose output if true (nonzero). \endlist """ The \e is a cell or list element, the \p is a parameter. (If you need to group a phrase you'd do \b[bold phrase] -- yes bold and italic are supported even though they aren't categorisation.) The way I'd have written the thing is like this: def __init__(self, stateclasses, initialstate, debug=0): ''' Initialize a \class StateMachine object; add state objects. The \p stateclasses is a list of \class State (sub)classes. The initial state (which is a class name) is in the \p initialstate string. If you want verbose output set \p debug to true (its default is false). ''' If you wanted to do this you'd have to extract the text yourself and then run it through RTX. I will make RTX capable of doing this itself soon. BTW I am not keen on defining the presentational structure within the description itself. For me the presentation is a concern of the output formatter and what I want to feed into that is categorisation, i.e. this is a class name, this is a method name, etc. -- Mark.

1 0

[development doc updates]
by fdrake＠beowolf.digicool.com June 24, 2001

June 24, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ A couple of small updates, including spelling the keywords correctly in the language reference. This version brings back the hyperlinked grammar productions I played around with earlier. They still need work, but they are somewhat better than plain text.

1 0

Browsers & the Python documentation
by Fred L. Drake, Jr. June 23, 2001

June 23, 2001

Ok, between a few responses I've received from my query about browser support for ± and ∞, and the browsers I happen to have installed, here's what I've found: Browser | Version | O/S | ± | ∞ -----------|-------------|-------|----------|-------- Mozilla | 0.9, 0.9.1 | Linux | ok | ok Navigator | 4.76, 4.77 | Linux | ok | no! Opera | 5.0 | Linux | ok | no! Amaya | 4.3.2 | Linux | ok | ok Konqueror | 1.9.8 | Linux | ok | no! StarOffice | 5.2 | Linux | ok | no! gnome-help | 0.4 | Linux | ok | no! (but it sucks anyway) Lynx | 2.8.4dev.8 | Linux | ok | no! Links | 0.92 | Linux | kinda | no! -----------|-------------|-------|----------|-------- MSIE | 5.5 |Win98SE| ok | ok -----------|-------------|-------|----------|-------- MSIE | 6.0 preview | Win2K | ok | ok Mozilla | 0.9 | Win2K | ok | ok Navigator | 6.0 | Win2K | ok | ok Opera | 5.11 | Win2K | ok | no! I'd love to hear about browsers on Mac OS as well! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Digital Creations

2 1

Re: [Doc-SIG] Browsers & the Python documentation
by Michael Hudson June 23, 2001

June 23, 2001

"Fred L. Drake, Jr." <fdrake(a)acm.org> writes: > Ok, between a few responses I've received from my query about > browser support for ± and ∞, and the browsers I happen to > have installed, here's what I've found: > > > Browser | Version | O/S | ± | ∞ > -----------|-------------|-------|----------|-------- > Mozilla | 0.9, 0.9.1 | Linux | ok | ok > Navigator | 4.76, 4.77 | Linux | ok | no! > Opera | 5.0 | Linux | ok | no! > Amaya | 4.3.2 | Linux | ok | ok > Konqueror | 1.9.8 | Linux | ok | no! > StarOffice | 5.2 | Linux | ok | no! > gnome-help | 0.4 | Linux | ok | no! (but it sucks anyway) > Lynx | 2.8.4dev.8 | Linux | ok | no! > Links | 0.92 | Linux | kinda | no! w3m | 0.1.6 | Linux | ok | no Is there an infinity symbol in iso-8859-1? That would make it tricky for text-mode browsers at the moment... Cheers, M. -- . <- the point your article -> . |------------------------- a long way ------------------------| -- Cristophe Rhodes, ucam.chat

2 1

[development doc updates]
by fdrake＠beowolf.digicool.com June 22, 2001

June 22, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Changed the revised cmath documentation to use "j" as a suffix for complex literals instead of using "i" as a prefix; this is more similar to Python. Changed the font of the suffix to match that used elsewhere in the documentation. This should be a little more readable, but does not change any potential browser compatibility issues, so I still need reports of compatibility or non-compatibility. See my prelimiary report on the topic at: http://mail.python.org/pipermail/doc-sig/2001-June/001940.html

1 0

[development doc updates]
by fdrake＠beowolf.digicool.com June 22, 2001

June 22, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Lots of smallish updates and corrections, moved the license statements to an appendix. This version includes some contributed changes to the documentation for the cmath module. To make the LaTeX to HTML conversion work, I have made the resulting HTML contain entity references for the "plus/minus" and "infinity" symbols (± and ∞, respectively). These may be problematic for some browsers. Please let me know how it looks on your browser by sending an email to python-docs(a)python.org. Be sure to state your browser name and version, and what operating system you are using. Thanks! http://python.sourceforge.net/devel-docs/lib/module-cmath.html

1 0

[maintenance doc updates]
by fdrake＠beowolf.digicool.com June 22, 2001

June 22, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/maint-docs/ Lots of smallish updates and corrections, moved the license statements to an appendix.

1 0

Implicit Link Targets
by castor＠snafu.de June 21, 2001

June 21, 2001

Reading the `specification docs`_ once more, I realized it might be pretty desirable to have implicit link targets. More specifically, I suggest that titles of sections like Section Titles ============== as well as figure captions A figure (a graphic with a caption) could be placed like this:: .. figure:: larch.png The larch. could be made available as implicit link targets (I'm not quite sure whether figure captions are actually recognized as a distinct element in the spec; I'd have to check that). Since "Whitespace is normalized within hyperlink names, which are case-insensitive", authors can then refer to `section titles`_ and `the larch`_. It might be desirable to issue warnings in case non-unique titles/captions are actually referred to within the text. Implicit targets could be supplemented/overridden by explicit targets; their use would obliterate the need for most explicit targets seen in a text like the specification itself. Is that desirable/implementable? -wolf . _specification docs: http://structuredtext.sourceforge.net/

3 3