-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas via Boost Sent: 09 October 2017 18:05 To: boost@lists.boost.org 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 +44 (0) 1539 561830