Mailman 3 July 2003 - Doc-SIG

State of XHTML in browsers
by Fred L. Drake, Jr. July 31, 2003

July 31, 2003

I'd like to get a rough idea of how painful it would be for users if python.org and the Python documentation were converted to strictly conforming XHTML 1.1. I presume we'd still serve web pages as text/html, but the content would conform to XHTML 1.1 with all the HTML compatibility hacks. In particular: Are there any actively used browsers that don't support proper XHTML? I'm think especially about linking behavior: Are all current browsers able to use the "id" attributes on arbitrary elements, or is the <a name='...'> construct still needed? I'd really appreciate feedback on this. Thanks! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

3 6

Emphasized URLs, how?
by Dinu Gherman July 28, 2003

July 28, 2003

Hi, I'm failing to get emphasized, clickable URL as I would expect them. Is there any trick to do it? Here's what I tried, all in vain: As expected: normal *emphasis* http://normal.com `Normal.com <http://normal.com>`__ Not as expected (emphasized clickable URL): *http://emphasis.com* *`Emphasis.com <http://emphasis.com>`__* `*Emphasis.com* <http://emphasis.com>`__ Thanks, Dinu -- Dinu C. Gherman ...................................................................... "Je m'appelle Érik Satie comme tout le monde." (Érik Satie)

2 1

epydoc 2.0 released
by Edward Loper July 28, 2003

July 28, 2003

I just released version 2.0 of epydoc. Of special note to some of the members in this list is the fact that it supports ReStructuredText. :) ---------------------------------------------------------------------- Epydoc is a tool for generating API documentation for Python modules, based on their docstrings. <http://epydoc.sourceforge.net/> For some examples of the documentation generated by epydoc, see: - The API documentation for epydoc. (HTML) <http://epydoc.sourceforge.net/api/> - The API documentation for epydoc. (PDF) <http://epydoc.sourceforge.net/epydoc.pdf> - The API documentation for the Python 2.2 standard library. <http://epydoc.sourceforge.net/stdlib/> - The API documentation for NLTK, the natural langauge toolkit. <http://nltk.sourceforge.net/ref/> - The API documentation for Docutils <http://epydoc.sourceforge.net/docutils/> Epydoc currently understands four markup languages: - Epytext, a lightweight markup language with support for basic formatting constructs. - ReStructuredText, an "easy-to-read, what-you-see-is-what-you-get plaintext markup syntax." - Javadoc, the standard markup language for documenting java source. - Plaintext. New features added since 1.1 include: Improvements to Docstring processing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Support for ReStructuredText docstrings. - Support for Javadoc docstrings. - Many new documentation fields for docstrings. - More robust crossreference link resolving. Improvements to Output Generation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - New output formats: LaTeX, DVI, PostScript, and PDF. - Three new formats for displaying inherited methods and variables: listed, grouped, and included. Improvements to Inspection ~~~~~~~~~~~~~~~~~~~~~~~~~~ - Support for new Python 2.2+ objects, including class methods, static methods, properties, and metaclasses. - Automatic detection of imported variables. - Documentation inheritance for inherited methods and variables. Improvements to Efficiency ~~~~~~~~~~~~~~~~~~~~~~~~~~ - Epydoc 2.0 runs 50%-200% faster than epydoc 1.1. (e.g., it runs 2.6 times as fast when documenting the Python standard library). A complete list of new features and the change log are available at: <http://sourceforge.net/project/shownotes.php?release_id=173036> -Edward

2 1

Doc/ tree on trunk closed
by Fred L. Drake, Jr. July 24, 2003

July 24, 2003

I'm closing the Doc/ tree on the trunk until Python 2.4 final has been released. Not even typo corrections should go in at this point. Thanks! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

3 3

reST editor experiments...
by Dinu Gherman July 20, 2003

July 20, 2003

Hi, I'm experimenting with a prototype reST editor on OS X, and made a little QuickTime MPEG4 movie displaying the current state of it (since few people here might have OS X available): http://python.net/~gherman/tmp/ReSTedit0.mov (5 min, 1486 KB) It's only a start, I'm just using docutils.core.publish_string(text, writer_name='html'), but it raises for me several questions about: - changing the default CSS (or parts thereof) - suppressing warning messages (e.g. about empty sections) - raising visual significance of warning messages (e.g. color, etc.) Thanks for any insight into these issues! Dinu CC'ed to the PyObjC list... -- Dinu C. Gherman ...................................................................... "Even if you do learn to speak correct English, whom are you going to speak it to?" (Clarence Darrow)

2 2

Re: [Fink-users] Python 2.32b2-2
by Skip Montanaro July 17, 2003

July 17, 2003

I'm cc'ing Andrew Hartung from the fink-users mailing list as he's who brought this problem to my attention, and Milan Zamazal, as he's the py2texi author. The subject of critical problems to be solved before the 2.3 release came up on python-dev. Andrew is having trouble building the info docs: Jeff> On Fri, 11 Jul 2003, Andrew Hartung wrote: >>> Second, I am having trouble building the info documentation >>> files. Here is the error when I run make in the >>> /sw/share/doc/python23/doc/info directory: >>> >>> Unknown environment: comment >>> Args out of range: 405210, 405212 >>> make: *** [python-lib.info] Error 255 I thought originally that it was an Emacs problem, but it turns out to really be a limitation of regular expressions (the "re's can't count" problem). I doubt it's a Mac-specific thing. Here's what I was able to determine. I haven't completely solved the problem, but perhaps someone here can move this problem closer to a solution before 2.3rc1 is released. Doc/tools/py2texi.el attempts to process all the bits of Latex markup it finds, converting them into equivalent info markup. It tries to skip over optional macro args and does a decent job of this. It can handle \command{stuff here} fine, and can handle \command[optional stuff here]{stuff here} as long as "optional stuff here" doesn't include any right square brackets. This happens in py2texi-process-commands where it executes (py2texi-search-safe "\\\\\\([a-zA-Z*]+\\)\\(\\[[^]]*\\]\\)?" Unfortunately, libre.tex changed recently. This text was added to the end: \versionchanged[Simple uses of the \regexp{*?} pattern are now special-cased to avoid recursion. Thus, the above regular expression can avoid recursion by being recast as \regexp{Begin [a-zA-Z0-9_ ]*?end}. As a further benefit, such regular expressions will run faster than their recursive equivalents.]{2.3} Note the character set in the \regexp macro. py2texi-search-safe thus gobbles up [Simple uses of the \regexp{*?} pattern are now special-cased to avoid recursion. Thus, the above regular expression can avoid recursion by being recast as \regexp{Begin [a-zA-Z0-9_ ] as the second group, leaving *?end}. As a further benefit, such regular expressions will run faster than their recursive equivalents.] ungobbled. I can think of a hack or two. The simplest might to add an \rbrack macro to python.sty. That seems to work, though py2texi may have to be tweaked to map "\rbrack " into "]". This change at the bottom of libre.tex seems to avoid the above error: \newcommand{\rbrack}{]} \versionchanged[Simple uses of the \regexp{*?} pattern are now special-cased to avoid recursion. Thus, the above regular expression can avoid recursion by being recast as \regexp{Begin [a-zA-Z0-9_ \rbrack *?end}. As a further benefit, such regular expressions will run faster than their recursive equivalents.]{2.3} I still get makeinfo errors, but don't know what to do with them. At least Emacs doesn't crap out. ;-) I have a documentation bug opened on SF and originally thought I had a fix for py2texi.el (but it is no fix so ignore it). Unfortunately the damn SF site is down again so I can't refer you to the id number. You'll have to search for a doc bug submitted by me (montanaro) in the past few days. This is obviously not a showstopper for the 2.3rc1 releases, but it would be nice if it could be solved. Skip

3 2

Doc/ tree closes at noon, US/Eastern
by Fred L. Drake, Jr. July 17, 2003

July 17, 2003

The Doc/ portion of the Python source tree will be closed at noon, US/Eastern time. That leaves one hour and 40 minutes for finding typos and making it really easy for me to fix your favorite documentation bugs/omissions. No complicated changes will be accepted. If you have an outstanding doc bug/patch on SourceForge that you feel absolutely *must* be addressed in Python 2.3, raise the priority to 7, but realize that the amount of time I can make available is fairly limited today. Thanks! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

German Umlauts
by Christian Tismer July 16, 2003

July 16, 2003

Hi! I've started using reStructuredText for my Wiki pages, and I like RST quite much. Where I have problems are so-called "Umlauts". I know this is kinda Unicode issue, but I'd just like to know if and how this is handled in RST? The simple HTML way of ü doesn't work (why?). Is something planned here? (I'd be happy to help) Or is it at leat possible do define a default encoding? thanks a lot for any pointer -- chris -- Christian Tismer :^) <mailto:tismer@tismer.com> Mission Impossible 5oftware : Have a break! Take a ride on Python's Johannes-Niemeyer-Weg 9a : *Starship* http://starship.python.net/ 14109 Berlin : PGP key -> http://wwwkeys.pgp.net/ work +49 30 89 09 53 34 home +49 30 802 86 56 pager +49 173 24 18 776 PGP 0x57F3BF04 9064 F4E1 D754 C2FF 1619 305B C09C 5A3B 57F3 BF04 whom do you want to sponsor today? http://www.stackless.com/

6 9

VIRUS NOTIFICATION
by postmaster＠osb.hu July 1, 2003

July 1, 2003

#################### VÍRUSJELZÉS ##################### Ön (Doc-SIG(a)python.org) az alábbi címre küldött üzenetet: <sp(a)osb.hu> Az üzenet vírust vagy hasonlót tartalmaz, ezért nem kézbesítettük. Dátum : Tue, 1 Jul 2003 23:51:35 +0800 Tárgy : Re: Movie Vírus : W32/Sobig-E Lehetséges, hogy az Ön számítógépe fertõzött, anélkül, hogy Ön tudna róla. Ellenõrizze a gépét egy friss víruskeresõvel, vagy forduljon szakemberhez. ###################################################### ################# VIRUS NOTIFICATION ################# A message you (Doc-SIG(a)python.org) sent to <sp(a)osb.hu> contains a virus or a worm, and was not delivered. Date : Tue, 1 Jul 2003 23:51:35 +0800 Subject : Re: Movie Virus : W32/Sobig-E It is possible your computer is infected without your knowledge. Check your computer with a current virus scanner or ask a specialist. ######################################################

1 0

docutils (rst) User Documentation in Microsoft HTML Help (chm) format
by Axel Kollmorgen July 1, 2003

July 1, 2003

hi all, i just converted a big part of the docutils (rst) User Documentation (Intro, Primer, Quick rst, spec, FAQ, ...) into chm format. this is quite handy (for people who can use chm ;)) - it's all in one place, with a single toc, and fully searchable. you can download it from http://build.kollm.org/rst.zip (the chm plus the HTML Help project and toc files). i just applied for a docutils sandbox and will put this and possible future versions there (probably http://docutils.sourceforge.net/sandbox/ax-/). for future versions, i'll try one of the rst-to-docbook converters and the docbook chm writer to automatically generate a complete documentation. current version doesn't include all documentation and doesn't link all toc entries to their subheadings properly. regards. -- ax [Maris had a surgical procedure called botox injections] Dr. Niles Crane: They use those toxins that you put in the forehead, it deadens the muscles and takes away the wrinkles. I gave it to her as a gift one year for our anniversary. Dr. Frasier Crane: Oh, yes, probably your tenth. That's toxins, isn't it?

1 0