Re: [boost] Generating Boost documentation with pandoc

Subject: Re: [boost] Generating Boost documentation with pandoc
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2017-01-17 11:53:41

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Vinícius dos Santos Oliveira
> Sent: 16 January 2017 08:40
> To: Boost
> Subject: Re: [boost] Generating Boost documentation with pandoc
> 
> 2017-01-08 13:07 GMT-03:00 Stefan Seefeld <stefan_at_[hidden]>:
> 
> > > Gonna use asciidoc to write my next documentation so I can still have
> > > DocBook (not sure why it's so important) and have free ePUB support.
> > > asciidoc or any other simple markup language that does the job.
> >
> > (I'm actually pondering to move the Boost.Python docs from QuickBook to
> > good old ReST, so I could manage all its documentation with the sphinx
> > tool (used by most projects in the Python community). It may lack some
> > features, but the fact that it is well-known by many people outweighs
> > that by far.
> > Boost still has a long way to go to get out of the NotInventedHere mood...

Boost is also about DoingItBetter ;-)

The complex Quickbook/Doxygen toolchain was devised to provide *better* C++ documents.

As has been observed, what works for one language doesn't necessarily work for others.

Some libraries are trivial in a documentation sense, others horrendously complicated and have hundreds of templates, functions, arguments, classes, macros and other variants.

C++ needs a toolchain that fully understands C++, including templates, meta-things... in all their complexity.  Doxygen-syntax or markup comments provide the only 'standard' way of starting to provide the human readable (and human written) within the C++ code.

There are also different requirements for users and for maintainers (and developers as they work).

None of the tools answers the "How do I FIND things problem" at all well.  Indexes and TOCs are part of the answer (provided people know that they exist and then look at them).

Few documentation examples *navigate* well, being thin on links (mainly because these are hard work for the author to create manually, as are useful indexes).

Good Old ReST meets some needs, especially the simple, but not all.

We still need to do Much Better!

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]