Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2016-01-10 21:52:04

On Sun, Jan 10, 2016 at 4:51 PM, Louis Dionne <ldionne.2_at_[hidden]> wrote:

> Robert Ramey <ramey <at> rrsd.com> writes:
>
> >
> > On 1/9/16 6:45 PM, Louis Dionne wrote:
> > > Rene Rivera <grafikrobot <at> gmail.com> writes:
> > >
> > >>
> > >> [...]
> > >>
> > >> 1. A library is required to have HTML documentation.
> > >> 2. A library *can* integrate into the global Boost documentation.
> > >> 3. If a library doesn't do #2 it *must* provide prebuilt HTML
> documentation.
> > >>
> > >> Hence, even though Predef uses quickbook, it's never done #2.
> Therefore
> > >> Predef does #3
> > >
> > > Can't a library provide a Jamfile that generates the documentation,
> even if
> > > that documentation does not integrate with the global Boost
> documentation?
> >
> > Many libraries do not "integrate with the "global Boost documentation"
> >
> > > It would be straightforward to require that doing `cd doc && b2`
> generates
> > > the documentation into `doc/html`, with index.html as an entry point.
> >
> > You might think it would be straightforward - but it's not.  The
> > toolchain is long and finicky.
>
> ??? How is it more difficult to require `cd doc && b2` to generate the
> documentation rather than having it in place already? You already have
> to do `cd doc && b2` for libraries that integrate with the rest of Boost
> anyway.. There must be something I'm not getting.
>

The requirement is actually something like this:

1. Install all the requirements for what *all* the libraries want for
building their docs.. CORRECTLY.
2. Run "cd doc && b2" for each library.

It's the CORRECTLY of #1 that the's "not easy" part. As it varies from
system to system. And we don't have a requirement to limit the tools used.
Although in reality it's a small number.. three (plus their dependencies):
DocBook XSL, DocUtils, and RapidXML. And the last two are in use by a
single handful of libraries. So if those got replaced with something else
that's "built-in", it would be easier.

NOTE: I'm not for or against pre-generated or always generate. Just
pointing out current reality :-)

-- 
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail