On 4/23/25 2:04 AM, Дмитрий Архипов via Boost wrote:
ср, 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.
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