Opened 14 years ago
Last modified 9 years ago
#2232 new Feature Requests
Documentation build needs to detect missing prerequisites
| Reported by: | Beman Dawes | Owned by: | No-Maintainer |
|---|---|---|---|
| Milestone: | To Be Determined | Component: | Documentation |
| Version: | Boost 1.36.0 | Severity: | Problem |
| Keywords: | Cc: | john@…, daniel@… |
Description
Building documentation requires a lengthy tool chain to work correctly.
The following tools have to be installed:
libxml2, libxslt, doxygen, docbook-xml42, docbook-xsl, tetex (?), ghostscript
user-config.jam needs to supply usings for:
xsltproc, boostbook with docbook-xsl and docbook/4.2, doxygen, quickbook
Experience has shown that (1) even very experienced Boost developers can have missing tool chain items, and (2) missing tool chain items are very difficult to diagnose and repair because the current bjam setup does not issue meaningful error messages, produces partial documentation, and gives the appearance of working.
The requested fix is twofold:
- Specific error messages should be issued if the tool chain is not complete. The messages should distinguish between tools not being installed and user-config.jam not having all the required entires. The error messages should name the specific missing tool or missing user-config.jam entry.
- If one of the above errors is detected, the process should stop at that point. Currently partial documentation is built, and that can be very misleading and time-consuming. If the tool chain is wrong, nothing at all should be built.
Change History (8)
comment:1 by , 14 years ago
| Cc: | added |
|---|
comment:2 by , 14 years ago
| Cc: | added |
|---|
Latex and ghostscript aren't directly supported by boost build. They just get called by doxygen when the accumulators documentation is built. So at the moment, the check for those two should probably be in the accumulators jamfile. It would be nice if they were better integrated with boost build, but that isn't urgent.
A bit off topic: tetex is an obsolete unix distribution, but seems to be the best thing available for cygwin. There are several distributions. I'm currently using MikTeX on windows. But TeX Live looks quite promising, as it supports several platforms (including windows).
comment:4 by , 14 years ago
Not really no, I've fixed up the accumulators Jamfiles so they check for latex etc, but I don't think we have meaningful checks (and error messages) for the tools that are configured in user-config.jam still?
comment:5 by , 14 years ago
| Milestone: | Boost 1.39.0 → To Be Determined |
|---|
Thanks, I mainly wanted to know for the release notes.
comment:6 by , 12 years ago
| Component: | None → Documentation |
|---|---|
| Owner: | set to |
comment:7 by , 10 years ago
| Owner: | changed from to |
|---|
comment:8 by , 9 years ago
I still don't know how to do this in Boost.Build, but my documentation build script does check for executables before running the build. It's available at: https://github.com/danieljames/boost-build-docs
Some random thoughts:
1) Aren't libxml2 and libxslt prerequisites for xsltproc anyway? So maybe a quick verification that xsltproc is present and working would be enough?
2) TaTex is just a Windows port/distribution of Tex/LaTex, we should check that LaTex is in the path. Checking for ghostscript is harder because the command line (ie name of the executable to check for) differs between Windows and Linux OS's :-(
3) Checks for Doxygen / Latex / Ghostscript should occur only when those tools are used: they're not necessary for those of us who use straight Quickbook/DocBook.
Cheers, John.