Re: Proposal: Abandoning monolithic Boost documentation.

From: Дмитрий Архипов (grisumbras_at_[hidden])
Date: 2025-04-23 09:04:25

ср, 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.
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.

ср, 23 апр. 2025 г. в 06:24, Robert Ramey via Boost <boost_at_[hidden]>:
> 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.

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/

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

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

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