boostorg / boostbook Goto Github PK

I'm a happy user of boostbook and quickbook to generate the documentation for my software. This software is also part of Debian and there I run into the problem that my packages are not reproducible, due to the fact that quickbook writes out the current date as a last-revised string.
The solution to this is really very simple, patch quickbook to pick up the value of the environment variable SOURCE_DATE_EPOCH and use that instead of time() as the last-revised date.

The patch might look like this:

diff tools/quickbook/src/quickbook.cpp tools/quickbook/src/quickbook-n.cpp
469c469,473
<             time_t t = std::time(0);
---
>             time_t t;
>                       if (getenv("SOURCE_DATE_EPOCH"))
>                               t = strtol(getenv("SOURCE_DATE_EPOCH"), nullptr, 10);
>                       else
>                               t = std::time(0);

More information on reproducible builds can be found at https://reproducible-builds.org/ and https://wiki.debian.org/ReproducibleBuilds/Howto

Hope this can be fixed.

-maarten

Selecting the link http://boost.org/libs/boostbook on the github page results in a page with the error message:

404 Not Found
File "/home/www/shared/archives/live/boost_1_80_0/libs/boostbook/" not found.
Unable to find file.

Boost Org header for page appears correct. Footer shows missing Revised date (variable name showing).

Example:
https://www.boost.org/doc/libs/1_78_0/libs/json/doc/html/json/ref/boost__json__value/swap/overload1.html

The headings (Synopsis, Description, Complexity, Exception Safety, and Parameters) all are displayed with link styling (blue text, underline-on-hover, etc.). This is because boostbook.css only handles the valid HTML heading elements (up to H6). The imported DocBook stylesheets, however, can sometimes output H7.

The setup scripts download the dtd and xsl libraries into the repository directory but they need to be gitignored and are not:

The Python and bash setup scripts need to use docbook-xsl version 1.79.1 or else there are errors applying templates. To make things interesting, the archives are only offered in bz2 and not gzip anymore, so the scripts also need to be modified to reflect that.

BoostBook XSLT generate a double closing parenthesis after noexcept(cond) in Doxygen-generated documentation. For example, if you run Doxygen over this code:

struct foo
{
    void method() noexcept(cond);
};

and then apply BoostBook XSLTs, the generated documentation will have the method signature as void method() noexcept(cond)) (note the double closing parenthesis at the end). Here's a real world example.

I suspect, the problematic rules are these.

(This was initially posted to the Boost mailing list, but maybe this is a more specific location)

Hi, it seems that Boost fails building boostbook docs if xsltproc and libxslt1 version 1.1.35 is installed (it works with version up to 1.1.34).

Specifically, I can reproduce the failure following these steps:

• recursively clone [email protected]:boostorg/boost.git
• ./bootstrap.sh
• echo "using boostbook ;" > user-config-doc.jam
• ./b2 -j32 -q -d2 --ignore-site-config --enable-index --user-config=user-config-doc.jam --build-dir=build-doc
• ./b2 -j32 -q -d2 --ignore-site-config --enable-index --user-config=user-config-doc.jam --build-dir=build-doc doc

On my Debian unstable system this works when xsltproc and libxslt1.1 version 1.1.34 are installed, but fails when 1.1.35 is installed, with the following error:

"xsltproc" --stringparam boost.defaults "Boost" --stringparam boost.root "../../../.." --path "build-doc/boost/bin.v2/libs/logic/doc/docbook" --xinclude -o "build-doc/boost/bin.v2/libs/logic/doc/docbook/tribool.docbook" "/<<PKGBUILDDIR>>/tools/boostbook/xsl/docbook.xsl" "/<<PKGBUILDDIR>>/libs/logic/doc/tribool.boostbook"
runtime error: file /<<PKGBUILDDIR>>/tools/boostbook/xsl/annotation.xsl line 432 element element
xsl:element: The effective name '' is not a valid QName.
runtime error: file /<<PKGBUILDDIR>>/tools/boostbook/xsl/annotation.xsl line 432 element element
xsl:element: The effective name '' is not a valid QName.
runtime error: file /<<PKGBUILDDIR>>/tools/boostbook/xsl/annotation.xsl line 432 element element
xsl:element: The effective name '' is not a valid QName.
[repeated many times]

Many different libraries are failing in the same way, so I guess that the real problem is in boostbook. However I don't know enough of XSLT and libxslt to give a proper diagnosis.

By bisection I found that the first commit in libxslt causing the failure is https://gitlab.gnome.org/GNOME/libxslt/-/commit/b0074eeca3c6b21b4da14fdf712b853900c51635.

For the context, this bug was discovered during a test rebuild of the Debian package for Boost. However it can be reproduced with master doing the steps above.

Thanks in advance for any help you can provide, Giovanni.

The directory contains this license file, which seems to be a form of the MTLL license:
https://github.com/boostorg/boostbook/blob/develop/xsl/caramel/LICENSE

However, the other three files in that directory all say:

Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at
http://www.boost.org/LICENSE_1_0.txt)

So which is it? If those files are distributed under BSL-1.0 then why is the other license file there?

This complicates things for downstream packagers like Linux distros, who need to audit and record all relevant licenses used by a package.

When building doxygen reference documentation with the Quickbook -> BoostBook -> html path of generating docs in a doc jamfile, the documentation for the top-level namespace entities is correctly generated but the documentation for nested namespace entities is not occurring. The output shows that doxygen is correctly generating the XML elements for the nested namepace but when running xsltproc to transform these elements to BoostBook format the nested namespace XML information is lost, and the final reference documentation, based on doxygen, does not contain the nested namespace entities. If I just run doxygen directly to produce documentation, the nested namespace entities are correctly generated and shown in the doxygen output.

I first posted this as an issue for Boost Build at bfgroup/b2#18, but was told there it is a BoostBook issue. I have attached a file which illustrates this issue for an "example" Boost library.
example.zip