Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-10-09 17:04:41

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

Jonathan has fixed the segfaults, we are now working on the complex
metaprogrammed constructs it gives up upon.

It gets far, far further than doxygen already. Outcome v2 assembles
itself via metaprogramming from slices of implementation depending on
the types you feed it, so it's just about the worst kind of class to
document because its inheritance diagram is completely unstable.

With doxygen you have no choice but to expose such internal
implementation detail. I believe with Standardese we may reach a point
where the final class as the end user sees it is presented, and nobody
needs to care or think about any inheritance implemented internally.

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

Maybe your eyes are younger than mine?

The font size is about right for my 13 inch MacBook. To be honest I've
not tried it yet on a desktop monitor. If it's too big, it can be told
otherwise i.e. non-linear font scaling according to DPI. Modern CSS is
great.

>
 This is a modest library - layout may not scale well? Nor do I like the
sans serif font, but
> it's fashionable ;-)

It doesn't feel modest. The tutorial we have in mind is very, very long.
Never ending almost. And even then I suspect people will complain about
lack of sufficient tutorial coverage of the available facilities. This
might be a small library of only a few thousand lines, but its use cases
are very many and non-obvious to the uninitiated, and thus will need
additional tutorial sections.

Thanks to Hugo, the entire site is skinnable and themeable. Look and
feel is completely customisable and switchable as per any Boost peer
review feedback. So if the peer review wants it to look exactly like
BoostBook, that can be delivered.

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

The syntax highlighting is done by Pygments. It's not awful.

Yes linking to original source should be easy to add. It's now on my todo.

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

Did the (much larger) search box in the top left not work for you?

Reference APIs aren't on there yet, and thus don't show up in the search
box yet. But back before Outcome blew up old Standardese, it was working
well, if you typed in some words associated with what you wanted it
provided a drop down shortlist of possible matches.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/