[Doc-SIG] Re: [Fink-users] Python 2.32b2-2

[Skip Montanaro]

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