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

[Gary E. Miller]

Yo Greg!

On Thu, 14 Jan 2021 09:11:53 -0500
Greg Troxel <gdt@lexort.com> wrote:

> "Gary E. Miller" <gem@rellim.com> writes:
> 
> > 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.  
> 
> I would really prefer to have one.

Me too.

> WIth a choice we really need
> regression tests that check both, and a way to avoid people putting in
> markup that works with the flavor.

Even with one we need regression tests, that we do not have.  Care to
add some?

BTW, I found this comparision of AsciiDoc and AsciiDoctor:

https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/

So far it looks like either works.  Since gsd used AsciiDoc until recently
none of the new features have crept in.

> they are using and committing it,
> breaking the flavor they aren't using.

Which applies to everything gpsd.  I lost count of all the ways gpsdman
pages differ with different xsl.   We support various versions and
combinations of gcc, llvm, glibc, libc, python, etc. After those, this
is easy. 

> So if modern asciidoc is good
> enough, let's use it.

One problem with ASciiDoc, there is no modern AsciiDoc.  But it is good
enough to run on my RasPi's to make man pages.

Except right now the gpsd man pages are .xml

Does anyone have a good example of a man page in .adoc?

>  If it's not, let's use asciidoctor.

The problem with AsciiDoctor is the huge mass of Ruby that it pulls in.
A huge mass that mutates weekly.  When I removed it my RaspI's were
visibly relieved.

The change to support both was almost trivial.  Early in the cycle, lets
wait to see if it causes any problemss.

For now only the web site needs .adoc files, and only a few do that now.

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

pgpji_XZyp78R.pgp
Description: OpenPGP digital signature