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

[Gary E. Miller]

Yo Eric!

On Wed, 13 Jan 2021 20:17:51 -0500
"Eric S. Raymond" <esr@thyrsus.com> wrote:

> 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.

Works for me.

> > 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.

Gentoo needs Python at its core.  But does not install Ruby, in my case,
until I install AsciiDoctor.  The Ruby version mess is even worse than
Python's.

>  If your'ere concerned about
> minimum dependencies I'd go with base asciidoc; beware, however, that
> it's written in Pyton 2

Gentoo asciidoc works with Python 3.6, 3.7, 3.8 and 3.8.

> and not very actively maintained.

Last update: 13 Dec 2020.  So not too bad.

> Functionally, asciidoctor is a more forward-looking choice 0 it has a
> large and active devteam.

I just did a very quick test and, at last for the gpsd .adoc, AsciiDoc
and AsciiDoctor both seem to work the same.  Any feature you know to
avoid for cross-compatibility?

Getting scons to do both will only be a few lines of code.  I could prefer
AsciiDoctor and fall back to AsciiDoc.  That way nothing would break, and
I can get Ruby off my RasPi's.

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

pgpShD0D3jjji.pgp
Description: OpenPGP digital signature