Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2017-10-07 03:12:25

AMDG

On 10/06/2017 03:38 PM, Niall Douglas via Boost wrote:
> 
>>> * 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.
> 
> If we can get it working, it'll be a whole new age of "easy" for writing
> docs for complex C++ codebases,

  Er, I've always considered the hard part of documentation
to be the organization and content rather than specific tools.

> and moreover one which finally can parse
> the worst possible C++ metaprogramming without blinking because anything
> clang can parse can be documented.

  Just because the parser can handle it, doesn't mean that
it's a good idea.  For example, in documentation, I always
hide complex SFINAE, and instead provide an English description
of the conditions.  In general, I find the more complex the
metaprogramming is, the more tweaking is required to turn
the doxygen output into something sane.  This is rarely because
doxygen can't parse the code, but is rather because the raw
definitions in the source are not very human-friendly.

> 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.
> 

In Christ,
Steven Watanabe