Bug 1244268

What exactly should be in that package, i.e. which binaries and other files?

I despise reading Jam files and am struggling to figure out what pieces need packaging.

Do you want Apache FOP support included? It would add dependencies to boost-build, but as that isn't pulled in by the boost and boost-devel metapackages that might be OK.

The tools I would start with are QuickBook and BoostBook. The former is a binary, the latter just a set of DTDs and XSL stylesheets (it uses xsltproc for HTML generation, and possibly fop for pdf generation).

I'm not sure whether fop support requires anything special, i.e. other than bundling the XSL stylesheets for FO generation.

The tools/boostbook/setup_boostbook.sh script allows developers to set up their environment to build Boost documentation inside a Boost source tree. It essentially downloads specific versions of DTDs and XSL stylesheets. For a binary "boost-tools" package it would make most sense to just depend on and use the equivalent system packages instead.

(In reply to Stefan Seefeld from comment #2)
> The tools I would start with are QuickBook and BoostBook. The former is a
> binary, the latter just a set of DTDs and XSL stylesheets (it uses xsltproc
> for HTML generation, and possibly fop for pdf generation).

I understand that much, what I need to know is which specific files, and reading jam files is about as much help as smashing myself in the face with a hammer.

It looks like bin.v2/tools/quickbook/src/gcc-5.1.1/release/link-static/quickbook is the relevant binary.

> I'm not sure whether fop support requires anything special, i.e. other than
> bundling the XSL stylesheets for FO generation.

It adds a dependency on fop itself, which depends on java and xalan and other java tools. That adds dozens of megabytes of packages if you don't have them already.

> The tools/boostbook/setup_boostbook.sh script allows developers to set up
> their environment to build Boost documentation inside a Boost source tree.
> It essentially downloads specific versions of DTDs and XSL stylesheets. For
> a binary "boost-tools" package it would make most sense to just depend on
> and use the equivalent system packages instead.

Yes, I've already got this in user-config.jam to use the system packages:

using xsltproc ;
using boostbook
  : /usr/share/sgml/docbook/xml-dtd-4.2/
  : /usr/share/sgml/docbook/xsl-stylesheets
using doxygen ;

(In reply to Jonathan Wakely from comment #3)
> > I'm not sure whether fop support requires anything special, i.e. other than
> > bundling the XSL stylesheets for FO generation.
> 
> It adds a dependency on fop itself, which depends on java and xalan and
> other java tools. That adds dozens of megabytes of packages if you don't
> have them already.

What is 'it' ? I really don't think boost-tools needs to depend on fop.
In fact, the user can configure in his user-config.jam file what
specific fop tool to use (which version, what path, etc.).

> > The tools/boostbook/setup_boostbook.sh script allows developers to set up
> > their environment to build Boost documentation inside a Boost source tree.
> > It essentially downloads specific versions of DTDs and XSL stylesheets. For
> > a binary "boost-tools" package it would make most sense to just depend on
> > and use the equivalent system packages instead.
> 
> Yes, I've already got this in user-config.jam to use the system packages:
> 
> using xsltproc ;
> using boostbook
>   : /usr/share/sgml/docbook/xml-dtd-4.2/
>   : /usr/share/sgml/docbook/xsl-stylesheets
> using doxygen ;

Mine contains this:

using docutils ;
using quickbook : /usr/local/Boost/bin/quickbook ;
using boostbook
 : /usr/share/sgml/docbook/xsl-stylesheets-1.78.1
 : /usr/share/sgml/docbook/xml-dtd-4.5
 : /home/stefan/projects/modular-boost/tools/boostbook
 ;
using xsltproc : /bin/xsltproc ;
using doxygen : /bin/doxygen ;
using fop : /usr/local/Apache/fop-1.1/fop ;

so I'm using current DTDs and stylesheets. That generates some warnings
but otherwise works well.
(And as you can see, I'm not using the system fop, as that is buggy.)

Thanks,
         Stefan

I still can't figure out which files need to be packaged so I'm giving up, as I don't want to waste any more of my life looking at jam files.

(In reply to Jonathan Wakely from comment #5)
> I still can't figure out which files need to be packaged so I'm giving up,
> as I don't want to waste any more of my life looking at jam files.

Do you have fragments of build infrastructure for a boost-tools package (such as a spec file) ? I may give it a try myself...

There's a scratch build running at http://koji.fedoraproject.org/koji/taskinfo?taskID=10804941

You can grab the SRPM from there, it contains my modified spec file. It should produce a boost-doctools package containing:

/usr/bin/quickbook
/usr/share/sgml/boostbook/dtd/*
/usr/share/sgml/boostbook/xsl/*

OK that seems to work. I can remove some of the dependencies too, as doxygen and xsltproc are not necessarily needed.

Stefan, the package https://kojipkgs.fedoraproject.org//work/tasks/4942/10804942/boost-doctools-1.58.0-8.fc24.x86_64.rpm installs cleanly on F22. If you can test it for your use cases that would be great.

I think I prefer the name "boost-doctools" (or maybe "boost-docbook" or "boost-book"?) to just "boost-tools".

Yes, I like "boost-doctools", too.

The package installs a file

  /usr/share/sgml/boostbook/dtd

that contains the text

"Inspect complains that this directory is called '1.1', but that's the
standard naming style for DTDs, and this needs to match the url of the
DTD on the website. Any platform which has problems with this domain
name probably won't be able to build the documentation anyway."

(Note that in the boost source tree the above ".../dtd" is actually a directory, so I guess something went wrong as I expect that directory should be installed, rather than the file above.)

The package also installs a file

  /usr/share/sgml/boostbook/xsl

which is an XSL stylesheet, while the equivalent in the source tree

   .../boostbook/xsl/

is the full directory full of XSL stylesheets.

Doh, that's a last-minute change I made, which ended up installing a single file instead of a directory full of files.

New build on the way ...

New build: https://kojipkgs.fedoraproject.org//work/tasks/8670/10808670/boost-doctools-1.58.0-8.fc24.x86_64.rpm

Now dtd/ and xsl/ are folders, but redundant: I find the actual content in .../dtd/dtd/ and .../xsl/xsl/ respectively. Once I fixed this manually, my local build works with these tools.

boost-1.58.0-9.fc24 is in rawhide now, with a boost-doctools subpackage.

The boostbook files are in /usr/share/boostbook, and registered with the XML catalog so that validating the following doctype won't need to use the network:

<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">

I might also push it to F23 late this week.

Hi Jonathan,

I just upgraded to Fedora 23 and noticed that boost-doctools doesn't exist there. Would you mind backporting the boost-doctools package to F23, please ?

Thanks,

boost-1.58.0-10.fc23 has been submitted as an update to Fedora 23. https://bodhi.fedoraproject.org/updates/FEDORA-2015-2572ce7e27

Hi Stefan, I've built it and submitted it to the f23 updates-testing repo.

Awesome, many thanks !

boost-1.58.0-10.fc23 has been pushed to the Fedora 23 testing repository. If problems still persist, please make note of it in this bug report.
See https://fedoraproject.org/wiki/QA:Updates_Testing for
instructions on how to install test updates.
You can provide feedback for this update here: https://bodhi.fedoraproject.org/updates/FEDORA-2015-2572ce7e27

boost-1.58.0-10.fc23 has been pushed to the Fedora 23 stable repository. If problems still persist, please make note of it in this bug report.