Re: Proposal: Abandoning monolithic Boost documentation.

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

On 4/23/25 2:04 AM, Дмитрий Архипов via Boost wrote:
> ср, 23 апр. 2025 г. в 06:08, Robert Ramey via Boost <boost_at_[hidden]>:
>> Right.  But people shouldn't do that.
>> ...
>> Right.  But people shouldn't do that. Same as above.
> 
> Right, people shouldn't make mistakes. Silly them.
> 
>> Hmmm ... I'm not understanding this.  A contributor makes and issue
>> describing a problem with the documentation.  The maintainer updates the
>> documentation to fix the issue.  Presumable the maintainer knows how to
>> change the documentation source and regenerate the html.
> 

> I take it you've never had contributors that actually changed the
> documentation themselves. I have. For those people it would be useful
> to be able to regenerate the docs locally.

1) With few acceptions I find it unacceptable that a "contributor" 
directly change any files in a library that I maintain.  Such changes 
should be in PRs.  Then as maintainer I can merge them or not.  If the 
PR contains a documentation change in the html, I can hand transfer it 
to the documentation source and regenerate the html - which I do from 
time to time.  In my case, all html documents on the master branch are 
always in sync with the documentation source.  And the documentation 
source on the master branch is always in sync with the code - unless 
I've made a mistake - which happens occasionally.

> BTW, I have a suspicion that you don't have many contributors willing
> to fix docs, because IIRC you generate your docs using a proprietary
> program that is installed on your computer.

I don't know how "contributors" (I'm not sure whom you're referring to) 
generally don't have access to files in the library.  And if they did, I 
would not expect them to necessarily have access to the documentaion 
generation tool or have interest in learning out to use it.
> 
> This may blow your mind, but a user can do that even without
> downloading the git repo as a zip file:
> https://www.boost.org/doc/libs/develop/

I'm aware of this. This may blow your mind, but I'm not always connected 
to the net.  And the version of the docs/library I find there might be 
identical to the one I downloaded.  I like having a complete known 
consistent package which constitutes the library.  If I use the library, 
I like knowing that it will be useful for decades - long after Boost 
might itself might have disappeared.  This is a common requirement in 
some environments.

> 
>> 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.
> 
> Here we discuss building documentation for several projects as a
> single entity, as opposed to building them as separate entities. Maybe
> it would be better to call it integrated vs. standalone documentation
> so that we don't mix this with modular library projects. The benefit
> of removing integrated builds is slightly simplified docs build
> process (for release) and docs build scripts (for all libraries).

One thing I'm not getting is how one does an "integrated documentation" 
build when there's no guarentee that everyone uses the same tool to do 
so.  At one time, it was "mandated" that Boost Book be used - but that 
was relaxed so each developer could indulge his creative genius and here 
we are.

> 
>> 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.
> 
> Can you share some thoughts on the benefits of PDFs? I find them
> inferior to HTML in every regard when reading from a computer (or a
> phone) screen. And printing docs is a fictional thing invented by Fred
> Brooks for Mythical Man-Month.

I'm not advocating for pdfs specifically.  And I agree that they are 
much less popular than they used to be.  My personal preference these 
days is for Boost Book (or DocBook).  I edit this with an XML editor 
(XMLMind) and generate the html with BoostBook toolchain.  As a free 
bonus it generates pdf as well - though it probably wouldn't be missed. 
Truth is, I'm sort of sucker for free stuff.  I do like that BoostBook 
has the capability of generating format for which there exists and xslt 
tranform for - though to be honest, I've only used it for pdf.

> 
>> 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.
> 
> Who are those users who have an aversion to going to the web? 

I am one of those users.

> How do they get your project's sources without going to the web? Do they have
> a short window where they have Internet access, like they are on an
> exoplanet? I have relatives that live in a village in taiga. They
> don't have indoor plumbing, but they have good enough Internet access
> to send GIFs daily.

LOL -  perhaps the world has lost it's way

Robert Ramey