wt., 2 sty 2024 o 12:52 Andrey Semashev via Boost
On 1/2/24 11:55, Andrzej Krzemienski via Boost wrote:
Hi Boost Developers, And a happy New Year (at least for those who recognize the Gregorian calendar).
While I consider improving the documentation quality of some Boost libraries, I wonder if there are any tool or workflow recommendations for the library authors regarding the documentation. I know we do not force any specific tool or format, so I am only asking about recommendations.
I note that page https://www.preview.boost.org has at
https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guide...
the following:
The format for documentation on the new website is AsciiDoc Syntax Quick Reference https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/.
Should I treat it as a recommendation to use AsciiDoc? I note that quite a few new libraries choose it. I also see the advantage: you need no special tool for it: a simple web browser knows how to format it.
But I found the documentation of libraries that use adoc to be uncomfortable to read. I do not know if this is the tool itself or maybe the correlation between the choice of the tool and the devotion to documentation quality, or maybe something else. It is quite subjective. The older libraries' documentation (using BoostDoc) seemed more friendly and easier to navigate. But to write and maintain such documentation is a challenge. Last year something broke in my pipeline (QuickDoc, xstlproc) and to this day I am not able to determine what it is. So, relying on too complex flows, which become obsolete over time, also doesn't seem like a good idea.
I wonder if any of you have similar thoughts, and if you can recommend something for writing good quality and user friendly documentation.
To me, QuickBook is the most powerful tool for writing documentation, so I'm not going to recommend anything new. As the changelog says, the latest version supports direct HTML output, but I haven't tried it. I imagine, it should work for simple docs without BoostBook/DocBook specific features.
I think, it would be very useful to continue improving QuickBook, in particular to support additional output formats, maybe even AsciiDoc. We have lots of documentation written in it, and new libraries use it as well.
Perhaps, if you post some details about your problems with QuickBook, someone will be able to help.
Thank you for the response. So, let me give you my story, and maybe you -- or anyone else in this list -- can give me some advice. As probably most of us, I have only limited time to devote to Boost maintenance. I have one library in charge that I inherited from Fernando: Boost.Optional. I inherited a working toolchain for producing documentation and I try not to touch it: only modify the content. There is a Jamfile that to the initiated probably tells everything: https://github.com/boostorg/optional/blob/develop/doc/Jamfile.v2 I do not know what it does exactly. I know it uses BoostBook and QuickBook. It uses xsltproc indirectly, I guess. Can I use QuickBook without a BoostBook for the Boost documentation? Is someone doing it already? I tried to have a look at QuickBook docs ( https://www.boost.org/doc/libs/1_84_0/doc/html/quickbook.html) and I cannot figure out if it is a format or a tool that transforms one format into another. I guess it is the latter, but what does it output? How many tools do I have to learn to write documentation for a Boost Library? Of course, I could learn all of it. If I had unlimited time. But I only have like a couple of hours in a week or sometimes month. I barely have time to do the maintenance of the source code and the tests. This is my experience, but I suppose something similar is faced by anyone who considers proposing their libraries into Boost. I enclose the output from my running the `b2` command in folder doc. I would greatly appreciate it if anyone can help me fix this. But even if this is fixed, I would still want to know why this chain of QuickBook -> BoostBook is needed. Regards, &rzej;
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost