[Python-Dev] 2.3.1 - minor nit in HTML Help docs

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.  <fdrake at acm.org>
PythonLabs at Zope Corporation



More information about the Python-Dev mailing list