[Python-Dev] 2.3.1 - minor nit in HTML Help docs (original) (raw)

Fred L. Drake, Jr. fdrake at acm.org
Thu Sep 25 02:12:30 EDT 2003

Moore, Paul writes:

The HTML Help documentation in the Windows installer has "Release 2.4a0" in the footer for each page. I'm guessing that this is a fairly minor tweak that might need adding to the list of tasks for preparing a release...

I'm pretty sure I know how this happened, and is actually a (fairly minor) accident of how I built the docs this time combined with the slow growth of the formatting tools from being a pile of scripts very specific to building the Python documentation to tools that can format the types of documents used in the Python documentation.

What I did this time that was new is this: I used the formatting tools from the head of the trunk instead of from the branch. They picked up all the right content files, but used the wrong "shared" files from the Doc/texinputs/ directory. (The trunk files were used instead of the branch files.)

This is a strong indication that the conflation of content and style files in Doc/texinputs/ is a bad thing; style should be provided by the tool, and additional directories of content should be configurable for the specific content. For TeX-based tools, additional directories of TeX source files are specified by the TEXINPUTS environment variable, but the Doc/tools/mkhowto script simply clobbers that currently. There are a bunch of conventions associated with path configuration in TeX (per the kpathsea library), but implementing this for mkhowto shouldn't take long.

I expect to be able to handle this over the next few days, after which I'll generate new documentation packages for Python 2.3.1. The fixes will be made on the trunk (since that's where the formatting tools are being maintained); some changes to the Makefile and the organization of the files in Doc/texinputs/ on the release23-maint branch will be needed; not sure when these should be committed (in particular, before/after a MacPython release).

Once I've got this done, I'll propose a more managable approach to dealing with maintenance of the formatting tools.

-Fred

-- Fred L. Drake, Jr. PythonLabs at Zope Corporation

More information about the Python-Dev mailing list