Modify

Opened 9 years ago

Last modified 5 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.

Attachments (0)

Change History (8)

comment:1 Changed 9 years ago by John Maddock

Cc: john@… added

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.

comment:2 Changed 9 years ago by Daniel James

Cc: daniel@… 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:3 Changed 9 years ago by Daniel James

Milestone: Boost 1.36.0Boost 1.39.0

John, is this fixed?

comment:4 Changed 9 years ago by anonymous

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 Changed 9 years ago by Daniel James

Milestone: Boost 1.39.0To Be Determined

Thanks, I mainly wanted to know for the release notes.

comment:6 Changed 8 years ago by Marshall Clow

Component: NoneDocumentation
Owner: set to Matias Capeletto

comment:7 Changed 5 years ago by Matias Capeletto

Owner: changed from Matias Capeletto to No-Maintainer

comment:8 Changed 5 years ago by Daniel James

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

Modify Ticket

Change Properties
Set your email in Preferences
Action
as new The owner will remain No-Maintainer.

Add Comment


E-mail address and name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.