From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2020-04-20 17:59:40
Dear Glen,
> On 20. Apr 2020, at 17:18, Glen Fernandes via Boost <boost_at_[hidden]> wrote:
>
> On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
>>
>> Mateusz Loskot wrote:
>>
>>> Cem Bassoy wrote:
>>>>
>>>> Is GIL using AsciiDoc?
>>>
>>> No, GIL is using reStructuredText and Sphinx,
>>> but if I was migrating today, I'd go for AsciiDoc, I think.
>>
>> Can you shortly elaborate? I am asking for ublas.
>
> If you're interested, we've converted a few Boost library
> documentation from HTML to Asciidoc. For example:
>
> - Boost.Endian:
> Now: https://www.boost.org/doc/libs/1_72_0/libs/endian/doc/html/endian.html
> Before: https://www.boost.org/doc/libs/1_70_0/libs/endian/doc/index.html
>
> - Boost.IO:
> Now: https://www.boost.org/doc/libs/master/libs/io/doc/html/io.html
> Before: https://www.boost.org/doc/libs/1_72_0/libs/io/doc/index.html
>
> - Boost.Smart_Ptr:
> Now: https://www.boost.org/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html
> Before:
> https://www.boost.org/doc/libs/1_64_0/libs/smart_ptr/smart_ptr.htm
>
> The Asciidoc files and Jamfiles involved in these projects (and others
> - e.g. Boost.Mp11, Boost.Variant2, Boost.Assert, Boost.System are all
> Asciidoc too) should highlight how straightforward this would be if
> you choose to adopt it. The asciidoctor tool is also fairly easy to
> run for users to generate this documentation themselves, compared to
> Quickbook+Boostbook. I'm told it is simpler and easier to run than
> Sphinx too.
thank you mentioning this. I am interested in switching from Quickbook to Asciidoc. I am mostly ok with Quickbook, but it is bothering me very much that I am required to close my sections with [endsect]. That is machine-friendly and not human-friendly. I also like the style for the Asciidoc docs with the TOC on the left.
My main question: I generate my reference with doxygen in xml. The xml code is then post-processed using a Python script. The result is then integrated into my Quickbook docs(*) I quickly checked Jamfiles for the example libraries you mentioned, and none of those seem to have a doxygen-generated reference. How would I combine doxygen and Asciidoc?
Best regards,
Hans
(*) How much annoyed I am by the inability of doxygen to produce a proper reference for a template-heavy lib like Boost.Histogram is another story, but I really don't want to write the reference by hand either and keep it in sync with code changes manually.