Re: [boost] boost-cmake and quickbook

Subject: Re: [boost] boost-cmake and quickbook
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2018-10-24 09:08:57

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Raffi Enficiaud via Boost
> Sent: 23 October 2018 20:53
> To: boost_at_[hidden]
> Cc: Raffi Enficiaud
> Subject: [boost] boost-cmake and quickbook
> 
> On 23.10.18 21:29, Edward Diener via Boost wrote:
> > On 10/23/2018 2:36 PM, Robert Ramey via Boost wrote:
> >> On 10/23/18 11:17 AM, Peter Dimov via Boost wrote:
> >>> Robert Ramey wrote:
> >>>
> >>>> And I place the html and pdf versions into the repo so users don't
> >>>> have to build it.
> >>>
> >>> Placing the .html/pdf files into the repo is one - unquestionably
> >>> modular - way to do it, but it does have its downsides.
> >>
> >> Both true.
> >>
> >> downside
> >> - "wastes" a lot of space
> >> - redundant - docs could get out sync with the code.
> >>
> >>
> >> upside
> >>
> >> - current documentation is always available to the user.  In the two
> >> libraries of mine - documentation is an important part and I don't
> >> think the either would be usable without them.
> >> - only needs to be built on one machine no hassle for users
> >> - document build doesn't have to be "portable"
> >> - potential users can easily browse the documentation before they
> >> clone/download the package.  This works well with github.  I think
> >> this is very valuable - especialy for safe_numerics which most people
> >> don't actually see the need for.  Call it a sales tool.
> >
> > I am sure you know that github already has support for viewing the
> > documentation via the github io mechanism, so your last '-' item is not
> > really applicable to your argument.
> >
> > My argument is simply that lots and lots of libraries use Boost Build to
> > generate the docs, very often through the quickbook -> docbook ->
> > pdf/html mechanism and unless we are going to continue to do it that way
> > when Boost uses CMake we will eventually need a way to duplicate the
> > Boost Build mechanism for creating the docs in CMake.
> >
> > Nonetheless I continue to believe that the move to CMake by Boost should
> > be achieved in small steps, so that we can assure success in one step
> > for all libraries before we even think about attempting the next. I
> > still have the same fear that trying to accomplish everything at one
> > time will mean that nothing really will ever get done. I only added item
> > 5) to Peter's list because that is something we will eventually have to
> > decide about.
> 
> Talking about small steps, feel free to copy paste this wherever you
> need it:
> 
> https://github.com/raffienficiaud/boost-cmake/blob/master/boost-cmake/quickbook.cmake
> 
> I compiled Boost.Test documentation with this, this is fully cmake and
> it does the catalog generation on the fly.
> 
> This is a small step, usually this is where collaboration starts, since
> I do not have all the knowledge of quickbook/docbook nor the bandwidth ATM.
> 
> *But* if somebody is kind enough to assist me on this, in particular
> explaining me if we would want
> 
>     --stringparam chunk.first.sections "1"
>     --stringparam chunk.section.depth "4"
>     --stringparam generate.section.toc.level "3"
>     --stringparam html.stylesheet "boostbook.css"
>     --stringparam toc.max.depth "3"
>     --stringparam toc.section.depth "10"
> 
> to be exposed when compiling a documentation, or how to run the doxygen
> part, then porting things to cmake will be definitely faster.

You probably don't need all of these for Boost.Test  (lots devised by John Maddock for the MASSSIVE and complex structured Boost.Math docs - so much that I ran out of the number of XSLT options permitted!).

--stringparam html.stylesheet "boostbook.css"  is probably needed to get the right style sheets.

http://www.sagehill.net/docbookxsl/ tells you about these in general.

http://www.sagehill.net/docbookxsl/ChunkingCustomization.html about chunking in general

http://www.sagehill.net/docbookxsl/Chunking.html on chunking ...

https://github.com/boostorg/math/blob/develop/doc/Jamfile.v2

documents the chunking and TOC settings for Math docs.

My user-config.jam contains
  :
    "I:/modular-boost/dist/bin/quickbook.exe"
  ;

to use Quickbook

using xsltproc
  :
    "C:/Program Files (x86)/xsltproc_win32/xsltproc.exe"
  ;

using boostbook
  : "C:/Program Files (x86)/DocBookXSL/docbook-xsl-1_77_1"
  # Contains eXtended Style Sheet programs.
  :
    "C:/Program Files (x86)/DocbookXML/42" # dir exists and contains docbookx.dtd 4.2
  ;

and get this OLD version, not the latest

# Generating html from xml
# using boostbook ;
# boostbook standalone : array.xml : <xsl:param>boost.root=../../../.. ;

# DTD (a document type definition), or schema, that provides instructions
# about the structure of your particular XML document.
# It's a rule book that states which tags <a_tag> are legal, and where.

Doxygen

# Doxygen info must come *after* boostbook info
using doxygen
  #: "C:/Program Files/doxygen" # NOT OK - because doesn't search from path into /bin?
  :
    "C:/Program Files/Doxygen/bin/doxygen.exe" # OK
  ;

using auto-index
  :
   "I:/modular-boost/dist/bin/auto_index.exe"
  ;

Generating PDF is more complicated and I won't try here.

Math doesn't use Doxygen (and making it do so would be a big job to make it useful to the reader).

A jamfile section like

doxygen autodoc
  :
    [ glob ../../../boost/svg_plot/*.*pp ]
    [ glob ../../../boost/quan/*.hpp ]
    [ glob ../../../boost/svg_plot/detail/*.hpp ]
  :

    #<doxygen:param>INPUT="filename1 directoryname2" # Separate with spaces.
    # But also see paths specified above.
    <doxygen:param>RECURSIVE=YES # Search subdirectories as well.

... 

should be present to build Doxygen too.  Setting it up is tricky but I could advise in detail.

Writing in Quickbook is pretty easy - and you can make the docs very user friendly by providing lots of links with some extra effort.

Yes - it is hideously complicated, but once set up, it does the job very painlessly and the result is very nice.

HTH

Paul