Re: Proposal: Abandoning monolithic Boost documentation.

From: Robert Ramey (ramey_at_[hidden])
Date: 2025-04-23 03:24:16

On 4/22/25 2:30 PM, Andrey Semashev via Boost wrote:

> I don't think anyone suggested storing (in git) the generated html.
My libraries do that.  Basically it so anyone who download the git repo 
as a zip file (E.G. a user) can read the documentation right away and 
know that it is in sync with the code.

> I know some libraries do that, but maintainers of those libraries have
> taken the responsibility to keep the source and generated content in
> sync. 

That's what I have done.  Never had a complaint about it.

> Whether the docs are modularized or not is orthogonal to that.

> I think, what Robert suggested is to just build the monolithic docs from
> modularized. As far as html goes, nothing needs to be done as we already
> list all libraries on the website, whether they use modularized or
> centralized docs. 

To be honest, I've been having difficulty understanding the monolithic 
vs modularized discussion.  Every time I think I understand it, I come 
across some post which confuses me again.

<off topic>

Truth is I've never understood what the "release" process is.  This is 
after 20+ years as a Boost developer.  I had always assumed it just 
giant zip file with all the libs and toos which one installs on his 
machine and then follows the "getting started" section of Boost 
documentation. Make of this what you will
</off topic>

> For pdf, I don't think it would be easy or at all
> possible to generate a single pdf from multiple libraries. Though I
> doubt there is any demand for that nowdays.

I talked to some users at a conference maybe 15 years ago.  The 
expressed great affection for the pdf version of the docs.  I also very 
much like pdf for other non-boost projects I work on.  So I've always 
been a fan (maybe the last one) of BoostBook.  If everyone used 
BoostBook we could generate a giant Boost reference with index, table of 
contents etc.  Sounded cool at the time, but given the current size of 
boost it's utility would likely be limited.  However having one "book" 
per library and a cross reference would be pretty cool if I didn't have 
to build it and it just came along with the down load like html does (in 
my world).

>> And it doesn't solve the main problem with having multiple
>> documentation formats in the project: that a contributor will have a
>> hard time figuring out how to build docs for the library he is
>> interested in. This is because that contributor would still have to
>> get the necessary tool.

Right.  In my world the download for each library would contain both the 
html and the original document source.  Most have no interest in the 
document source, they just want to read the documentation so the use the 
library RIGHT NOW (users are very impatient) preferable without having 
to go to the web.

> This also doesn't change with this proposal. If anything, it has the
> potential to increase the tool diversity.

We've always had the view that the canonical form of documentation is 
html.  Thus, the tool the any individual developer chooses to use is 
totally up to him.  One can argue that this view is/has been misguided, 
but it has the advantage that developers across all time and space don't 
have to agree on a documentation build toolset.

Robert Ramey