Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2017-10-09 16:08:59

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Niall Douglas via Boost
> Sent: 06 October 2017 22:38
> To: boost_at_[hidden]
> Cc: Niall Douglas
> Subject: Re: [boost] Asciidoc, an alternative for documentation
> 
> 
> >> * Does asciidoc allow to show code snips marked in an external source
> >> file? For example, to show example code snips in Quickbook using
> >> [import <file-name>] and then [abc], where //[abc ... //] are used as
> >> markers in file-name.
> >
> > This is the QuickBook feature I would miss. I've used that heavily to
> > ensure that the code embedded in the documentation is code that
> > actually builds and runs, without having to remember to (re-)paste
> > updates into the document source.
> 
> I too have been playing with radically different methods of generating
> documentation for Outcome v2, seeing as people panned the v1 Outcome
> documentation.
> 
> This is bleeding edge stuff i.e. it currently segfaults a lot, but it is
> getting there. It uses Hugo to compile the Markdown source files into
> HTML via a Travis per-commit job. Standardese may - once Jonathan fixes
> the bugs - generate the reference API docs in Markdown from doxygen
> marked up C++ source files using libclang.

I'm very pleased to see the use of Clang compiler.

Doxygen's author Dimitri van Heesch has performed miracles getting Doxygen to parse C++, but use of templates (Boost's especially)
has exceeded what is practicable without a real compiler.
As you observe, we need to be able to 'cut the crap' of endless unhelpful duplications to only show what is really useful for the
users.

Doxygen syntax mark-up is the key to any tool to process well. The quality of the in-code documentation is of paramount importance.
No tool can compensate for what is missing here.

I think we should judge *future* libraries by the quality of this - so that future tools like this can (re-)process it to produce
future documentation.

> If we can get it working, it'll be a whole new age of "easy" for writing
> docs for complex C++ codebases, and moreover one which finally can parse
> the worst possible C++ metaprogramming without blinking because anything
> clang can parse can be documented. You literally run just two build
> tools, both easily executed from Travis, and push the changes to
> gh-pages on Github. Changing documentation is as easy as modifying the
> Markdown source or the doxygen format comment section in the relevant
> header, git commit and git push. Hugo generates the syntax highlighting,
> the wiki linking, the search index and everything else. Oh, and it looks
> pretty, even on a mobile phone. You can swipe the tutorial left and
> right for example.
> 
> You can see our joint efforts so far for Outcome v2 at
> https://ned14.github.io/outcome/. You can thank Andrzej for the tutorial
> written so far, it's all him.

Looks pretty - though I don't want to read it on a phone or tablet and resent that the layout compromises size so that the font is
too big on a 'proper' desktop screen. This is a modest library - layout may not scale well? Nor do I like the sans serif font, but
it's fashionable ;-) And people are *very* sensitive to the C++ syntax coloring - it would be nice for readers to easily control
that too, as has been discussed before.  I presume snippets are using the actual C++ code, and can be referenced by hyperlinks? (As
using Quickbook at present).

I thought that a most interesting feature was the tiny search box on the Doxygen reference pages with a dropdown to separate
functions from macros etc.  This is the equivalent to *part* of a conventional index.  As often, the hard bit is getting people to
find it and use search fully.

This is one of the key items missing from much discussions of documentation needs so far -

"How to find what you are looking for - especially when you don't know what the author has called it!"

In using Boost.Math (the biggest Boost documentation by far), despite having written part of it, I still find difficult finding
things, even when I know it is there somewhere.  Asking a well-known search engine and searching the PDF version are a desperate
steps to which I descend  far too often :-(  

Paul

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