Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Artyom Beilis (artyom.beilis_at_[hidden])
Date: 2016-01-11 01:19:57

>> ??? 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.

+1

I just wanted to add small notes

1. I totally agree that requiring to build documentation to see one is
just not an option.
    I used plain Doxygen in first place for Boost.Locale and will for
other libraries
    just because setting up all the toolchain required too much effort
and I'm susually
    working on Linux that makes stuff much simpler in terms of installation of
    multiple packages

2. I can agree that having pregenerated documentation in git is bad.
I'd suggest to
   have some nightly doc build available on boost.org for each library
master and develop.

However I think more generation tools should be supported out of the
box like plain
Doxygen instead of quickbook.

> So if those got replaced with something else
> that's "built-in", it would be easier.
>

Now this one is big "-1"

Boost community already had reinvented 1001 tools just because they
and they always think they know better and now we stuck with boost.build
that I think vast majority of boost developers would be glad to get rid of.

Now creating of documentation is very complex thing. Doxygen does it
very well - not that it is trouble free - but it is de-facto industry standard
and widely available. Maybe quick book can do some stuff nicer or better
but I don't think it outweighs the maintainability requirements
and ease for Boost.Developers.

So... if you want to fix something please start use widely available
and popular tools rather that reinventing yet another (...) that would
make life of Boost.Developers even harder - just because you can.

Do you want to make Quick Book better? Work with Doxygen
developers community and integrate it into Doxygen toolchain.

Artyom