On Mon, 2007-12-03 at 22:22 -0700, Robert Dodier wrote:
> This version builds and runs OK (run_testsuite is happy, ? shows
> documentation, plotting works, categories appear in html docs).
> Running texinfo to generate categories (separate from the texinfo run
> to generate the .info files for on-line documentation) generates
> warnings about duplicate anchors, but not errors.
Sure, "sh bootstrap; ./configure; make; make install" works fine, THE
FIRST TIME. However, you are left with a broken system:
cd src
mv zero.lisp temp; mv temp zero.lisp
cd ..
make
fails because makeinfo fails.
I see two serious problems with the current categories system:
1. The texinfo files, which have a valid texinfo syntax in the CVS
repository, are being transformed into files with an invalid texinfo
syntax. You see only warnings and no errors because the modifications
are made after makeinfo is executed (make) and texi2html (make install)
only reports those errors as warnings. The second time you attempt to
run makeinfo, it will fail because the use of duplicate texinfo anchors
is a texinfo error and not just a warning.
2. By modifying several texinfo files during the installation process,
you are left with your own, uncommitted copy of the repository. The next
time you do "cvs update", if you miss the messages warning you that you
have modified versions of the texinfo files, any modification made by
others to the manual will not be updated in your CVS copy. You'd have to
manually remove several texinfo files from your CVS snapshot and
retrieve them again, which is time consuming and very annoying.
It would be better if the anchors used by the category system were
already present in the CVS repository and not added during installation;
they should be unique and not repeated. The python script could be used
only by the developers who work on the manual, before committing new
versions of the manual. If the python script can only be run during the
installation, it could probably create new files with the meta-data
needed by the categories system, rather than modifying files which were
retrieved from the repository.
Regards,
Jaime