Re: Recommendations for documentation authors

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2024-01-02 16:33:54

On 1/2/24 18:13, Andrzej Krzemienski wrote:
> 
> wt., 2 sty 2024 o 12:52Â Andrey Semashev via Boost <boost_at_[hidden]
> <mailto:boost_at_[hidden]>> napisał(a):
> 
>     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.
> 
> So, when you are recommending QuickBook, does this also imply
> BoostBook/DocBook, or are you treating them as separate tools?

QuickBook+Doxygen (which both produce BoostBook) is the combination I'm
using and recommending. This combination implies BoostBook usage in
background.

No, it doesn't mean one has to *learn* BoostBook to be able to use it.
In fact, I have never written in BoostBook through all the years I have
used this combination, aside from a few escapes in QuickBook templates.
Which may no longer be necessary with modern QuickBook. I'll note that
there was a time when people wrote docs in raw BoostBook, which is
probably why QuickBook appeared in the first place. Those times are long
passed now.

BoostBook *is* a separate tool, though, as you have to configure it in
the Jamfile. Most of the time the configuration can be copy-pasted from
one of the many libraries in Boost and then tweaked to your liking.