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

[Gary E. Miller]

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.

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?

RGDS
GARY
---------------------------------------------------------------------------
Gary E. Miller Rellim 109 NW Wilmington Ave., Suite E, Bend, OR 97703
        gem@rellim.com  Tel:+1 541 382 8588

            Veritas liberabit vos. -- Quid est veritas?
    "If you can't measure it, you can't improve it." - Lord Kelvin

pgpLpSIPi9H9u.pgp
Description: OpenPGP digital signature