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-10 09:12:14

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Niall Douglas via Boost
> Sent: 09 October 2017 18:05
> To: boost_at_[hidden]
> Cc: Niall Douglas
> Subject: Re: [boost] Asciidoc, an alternative for 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.
> 
> 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.

Brilliant!

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

No way!  (But I have a decent screen (24 in) to compensate).

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

Only modest in the number of functions.  Libraries that have hundreds of functions pose other problems.

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

As you fear ;-)
 
> 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?

Yes it did (but not API), but the dropdowns allow one to restrict the search nicely.  (If you have thousands of items, this becomes
very helpful).
 
> 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.

Looking very promising.

Paul

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