New Python regex Doc (was: Python documentation moronicities)

Fri May 6 19:55:51 EDT 2005

HTML Problems in Python Doc

I don't know what kind of system is used to generate the Python docs,
but it is quite unpleasant to work with manually, as there are
egregious errors and inconsistencies.

For example, on the “Module Contents” page (
http://python.org/doc/2.4.1/lib/node111.html ), the closing tags for
<dd> are never used, and all the tags are in lower case. However, on
the regex syntax page ( http://python.org/doc/2.4.1/lib/re-syntax.html
), the closing tages for <dd> are given, and all tages are in caps.

The doc's first lines declare a type of:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

yet in the files they uses "/>" to close image tags, which is a XHTML
syntax.

the doc litters <p> and never closes them, making it a illegal
XML/XHTML by breaking the minimal requirement of well-formedness.

Asides from correctness, the code is quite bloated as in generally true
of generated HTML. For example, it is littered with: <tt id='l2h-853'
xml:id='l2h-853'> which isn't used in the style sheet, and i don't
think those ids can serve any purpose other than in style sheet.

Although the doc uses a huge style sheet and almost every tag comes
with a class or id attribute, but it also profusively uses hard-coded
style tags like <b>, <big> and Netcsape's <nobr>.

It also abuse tables that effectively does nothing. Here's a typical
line:
<table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-851' xml:id='l2h-851'
class="function">compile</tt></b>(</nobr></td>
  <td><var>pattern</var><big>[</big><var>,
flags</var><big>]</big><var></var>)</td></tr></table>

If Python is supposed to be a quality language, then its
documentation's content and code seems indicate otherwise.
-----------------------

This email is archived at:
http://xahlee.org/perl-python/re-write_notes.html

 Xah
 xah at xahlee.org
∑ http://xahlee.org/

☄