On Mon, Dec 4, 2023 at 8:49 AM Andrey Semashev via Boost < boost@lists.boost.org> wrote:
Thanks. Looks like the tool might become a good alternative to Doxygen in the future, if it is configurable enough and integrates well with QuickBook.
The kind words are appreciated! I will address some points, leaving the other responses to Krystian. 1. In general, avoid wasting space on the sides of the content. Make the
output span the majority of the display width.
That's a function of the templates used by the asciidoc tool and not something that mrdocs controls. What you are seeing in this demo is the result of running asciidoc on the output of mrdocs. The mrdocs tool produces Asciidoc output. For example here is one of the output files produced by our tool: https://mrdocs.com/demos/develop/boost-scope/multi/adoc/boost/scope.adoc 2.
https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope...
I would prefer if there was a separation of components by headers instead of alphabetical lists of types, functions, etc.
For our first mrdocs deliverable we are targeting libraries like Boost.URL, Boost.JSON, Boost.Beast, et. al. which present the reference in the same style as Boost.Asio from which they were copied. I recognize that this is completely different from the other model of presenting the reference which works on an individual header file basis and also shows the full declaration of the class. Personally I prefer the Asio style over the per-header/full declaration but to each their own. A core principle of mrdocs is that it is not opinionated and will permit full customization of the output and style. Therefore our roadmap includes a set of mrdocs templates and features to be able to completely replicate the per-header/full declaration style found in other Boost documentation. 3.7. Any links to GitHub should use permalinks rather than links to
branches.
This is configured by the author in the mrdocs.yml file I don't want private stuff like types in detail namespace to be present in the generated docs. The mrdocs.yml permits namespace blacklists and whitelists with wildcards.
7. I hope there is a way to export information from the reference documentation in an XML
Currently there are three Generators: Asciidoc, HTML, and XML. The XML generator is intended to capture the entire metadata generated during AST traversal at full fidelity. We use the XML generator to test metadata output. or QuickBook format Well no we do not have a Quickbook generator, nor is there one planned. We chose Asciidoc because the Quickbook toolchain is old, unmaintained, and represents an existential risk to libraries which depend on it. Mrdocs has a plugin system using shared libraries which allows anyone to write a generator without the need to recompile mrdocs or to install and build clang/llvm locally.
so that it is possible to add links to specific classes and functions reference
pages from the main documentation in QuickBook. (Yes, QuickBook is a requirement from me, plain AsciiDoc doesn't offer some very useful features for me to consider it a format to write in.) We are positioning Antora as the premiere solution for modernization of Boost documentation. It is important to distinguish Asciidoc from Asciidoctor. Asciidoc is the markdown format while Asciidoctor is the tool which converts Asciidoc files into HTML. Antora ingests Asciidoc files and emits HTML. The Antora system has a more rich set of features than straight Asciidoc. If you have specific features from Quickbook that are not present when running Asciidoctor, I would ask that you open issues or identify these features so we can ensure they are available in the Antora solution which we are building. This is an example of Antora output. The input files are Asciidoc: https://www.preview.boost.org/doc/contributor-guide/index.html Thanks