Re: Recommendations for documentation authors

From: Joel de Guzman (djowel_at_[hidden])
Date: 2024-01-04 15:02:11

On 1/4/24 7:46 PM, René Ferdinand Rivera Morell wrote:
> On Wed, Jan 3, 2024 at 10:25 AM Joel de Guzman via Boost
> <boost_at_[hidden]> wrote:
>> (* aside * René, I did not know you can write reference docs directly in
>> the cpp source in Asciidoc. How do you do that?)
> You use the region tagged inclusion
> <https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/>.
> It works similarly to the Quickbook snippets (which I used heavily and
> extended and easily transitioned for asciidoctor). Some examples:
>
> * B2: <https://github.com/bfgroup/b2/blob/main/src/engine/mod_jam_errors.h>,
> rendered as <https://www.bfgroup.xyz/b2/manual/release/index.html#b2.reference.modules.errors>.
> * Predef: <https://github.com/boostorg/predef/blob/develop/include/boost/predef/compiler/clang.h>,
> rendered as <https://www.boost.org/doc/libs/1_84_0/libs/predef/doc/index.html#_boost_comp_clang>
> * Lyra: <https://github.com/bfgroup/Lyra/blob/develop/include/lyra/opt.hpp>,
> rendered as <https://www.bfgroup.xyz/Lyra/lyra.html#lyra_opt>
>
> And a non-reference, but still code inclusion example..
> <https://github.com/bfgroup/Lyra/blob/develop/examples/doc_groups.cpp>
> rendered as <https://www.bfgroup.xyz/Lyra/lyra.html#_argument_groups>.
> That mixes both including the doc and source code itself from the cpp
> file with callouts in the code. And obviously the code is tested to
> work in B2. So I know the examples are not accidentally broken.

Sweet! Just what I need. Thanks!

Cheers,

-- 
Joel de Guzman