Gary E. Miller <gem@rellim.com>:
> Yo All!
>
> Currently gpsd documentation uses: .html, .xml (converted to html and man
> pages), and .adoc (converted to html and man pages). Luckily no nroff.
>
> Supporting 3 tool chains is more effort than supporting 1.
>
> Obviously converting all the doc to one style will take a long time, but
> is there a direction we should move to?
>
> Do people prefer xml or AsciiDoc markup? Or maybe something else like
> reStructuredText (reST). Sphinx and Docutils support reST.
Having grappled with all of these a lot, I like asciidoc/asciidoctor.
I used to be a fan of XML DocBook, and it's still best for some kinfds
of book production where you need very prcise control, but I've moved
all my new work to asciidoc.
> The choices have non-obvious consequences.
>
> AsciiDoc pulls in Python
> AsciiDoctor pulls in Ruby
> Sphinx pulls in Python, and has a ton of add-ins.
> xmlto is a simple shell script, but has not been touched in 5 years/
> xsltproc is C, but has not seen much work since 2017
>
> Keeping Ruby up to date for AsciiDoctor has been a pain, so I lean towards
> going back to AsciiDoc.
>
> Thoughts anyone?
Python is preintalled everywhere anyone is likely to build documents
these days, and Ruby hardly less so. If your'ere concerned about
minimum dependencies I'd go with base asciidoc; beware, however, that it's
written in Pyton 2 and not very actively maintained. Functionally,
asciidoctor is a more forward-looking choice 0 it has a large and
active devteam.
Asciidoc started supporting Python 3 with version 8.6.10*. There are also
two forks Asciidoc3 and Asciidoc-py3. Both have similar command-line
arguments and run natively on Python3. Asciidoctor is faster but has
not quite so similar arguments and requires Ruby. NTPsec has support for
all four. It will not move directly to SCons, and I do not anticipate
porting it.
The right question is what kind of output file do you want (HTML,
manpage). and which input formats you will put up with. I am not
fond of XML.
* Or it might've been 8.6.9, I'd have to look it up.