I looked at doxygen. Doxygen’s mission is quite different - it generates
documentation from inline comments in the source code, and requires a
specific formatting style in the code. It does not generate “man pages” as
such. At the same time, we already had a corpus of documentation written
in asciidoc, and converting that to use asciidoctor was a more-or-less
trivial task, compared to switching to an entirely documentation system.
On Mon, May 16, 2016 at 11:30 AM, Michael Powell <mwpowellhtx@xxxxxxxxx>
wrote:
Why not doxygen? This has been around for eons and generates decent
HTML and even PDF apart from, or as a separate, "build" step.
On Mon, May 16, 2016 at 2:23 PM, Lionel Orry <lionel.orry@xxxxxxxxx>
wrote:
Hello,that
On Mon, May 16, 2016 at 10:43 AM, Dirkjan Ochtman <dirkjan@xxxxxxxxxx>
wrote:
On Mon, May 16, 2016 at 6:17 AM, Garrett D'Amore <garrett@xxxxxxxxxx>
wrote:
As always, please let us know (preferably by filing an issue) if
something
doesn’t work right or you have problems.
Thanks to you (and Jack) for pulling through and getting this done!
I've packaged this for Gentoo, so it will be available on a Portage
tree mirror near you soon. Two points of feedback:
- In the configuration using the CMake tools that we have available
from the package management system, I see libnanomsg.so.Unknown being
built. I might be doing something silly, but I think I'm following a
mostly standard CMake process. This is the result:
lrwxrwxrwx 1 root root 19 May 16 10:09 /usr/lib64/libnanomsg.so ->
libnanomsg.so.5.0.0
lrwxrwxrwx 1 root root 21 May 16 10:09
/usr/lib64/libnanomsg.so.5.0.0 -> libnanomsg.so.Unknown
-rwxr-xr-x 1 root root 282576 May 16 09:57
/usr/lib64/libnanomsg.so.Unknown
- I hesitated to give feedback before, but I'm kind of unhappy with
the move to asciidoctor for the docs. Personally I don't have
asciidoctor installed, and I don't know of any other projects using
it. Now, I looked at (the dependency situation for it on Gentoo.
Whereas nanomsg was already keyworded for a bunch of architectures
(amd64 arm mips ppc ppc64 s390 x86), asciidoctor is only available for
amd64 right now (in order to satisfy our QA tools, I've had to drop
nanomsg back to amd64-only too). This suggests that very few projects
in the Gentoo tree are using it. On top of that, on my server at
least, installing asciidoctor requires a whopping 11 dependencies to
be installed. I'm not sure if most distributions install Ruby by
default, but to me this would be a big barrier for actually installing
the docs. On the other side, asciidoc requires Python (which in my
experience is nearly always installed by default), libxslt and some
docbook XML stuff.
I can understand the concern, but why not providing an already-generated
html manual for releases tarballs ? This would make lot of sense to me
documentation is already prepared and ready to be viewed, before
compiling/installing the software.
Hope that helps,
Dirkjan
Best regards,
Lionel
