Re: Recomended way of generating documentation

From: Richard Hodges (hodges.r_at_[hidden])
Date: 2020-01-01 12:03:27

Treading carefully here as I'm new to boost library maintenance...

> So that you can cross-reference the Doxygen reference with whatever other
documentation you have

http://www.doxygen.nl/manual/autolink.html suggests that links to external
URLs are recognised by doxygen. Presumably linking to the correct place
vis-a-vis release/developer builds can be controlled with a macro in a
generated Doxyfile?

> And it's Doxygen to XML, XML to Boostbook. Then of course Boostbook to
Docbook, and Docbook to HTML.

Other than the very pleasing boost documentation styling, is this seemingly
convoluted conversion route necessary? Is it not possible to configure a
Doxyfile to contain the correct styling?

I have no knowledge of the evolution of boost documentation and have no axe
to grind, but as a newcomer it seems to me that there is a lot of
'unnecessary' compication in the production of documentation. I appreaciate
that there's no real sense in revisting existing libraries, but for new
ones wouldn't it be prudent to choose the shortest possible path which
involves the least learning and maintenance?

On Wed, 1 Jan 2020 at 01:28, Mathias Gaunard via Boost <
boost_at_[hidden]> wrote:

> On Sun, 29 Dec 2019, 14:04 Alexander Grund via Boost, <
> boost_at_[hidden]>
> wrote:
>
> >
>
>   3.  What benefit is there going from Doxygen (over multiple conversions)
> > to boostbook? Can't I just go from Doxygen to HTML?
> >
>
> So that you can cross-reference the Doxygen reference with whatever other
> documentation you have, which requires the whole documentation to
> eventually be in a single format (which is Boostbook).
>
> And it's Doxygen to XML, XML to Boostbook.
> Then of course Boostbook to Docbook, and Docbook to HTML.
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

-- 
Richard Hodges
hodges.r_at_[hidden]
office: [phone]
home: [phone]
mobile: [phone]