Re: ✘Doc files: .adoc, .html, .xml

[Eric S. Raymond]

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.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>