ср, 23 апр. 2025 г. в 06:08, Robert Ramey via Boost <boost@lists.boost.org>:
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@lists.boost.org>:
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.