Re: [gpsd-dev] Improving the gpsd documentation

[Gary E. Miller]

Yo Sanjeev!

On Fri, 9 Nov 2018 02:20:21 +0800
Sanjeev Gupta <address@hidden> wrote:

> On Fri, Nov 9, 2018 at 1:45 AM Gary E. Miller <address@hidden> wrote:
> 
> > As a dev I slightly prefer XML.  XML has more tools to help the
> > developer.  Asciidoc is a bit eaaier to read, and modify, the raw
> > file, but is less flexible.
> >  
> 
> I think asciidoc, if used sparingly, is easier to read as plain text.

Yes, but it is not meant to be read.

> Reading Docbook markup is impossible, at least for me.

Easy for anyone familiar with HTML.

All that matters is that those that need to edit it can edit it.

> > The main hurdle would be getting someone to do all the work of
> > conversion.  You want to create the patches to make it happen?
> 
> Sure.  My English is miles better than my C or python :-)  Will start
> one at a time, like the Linux docs moving to Rest.

The problem with that is then gpsd has dependencies on two doc toolchains.

The doc toolchains are the hardest problem to get right over many
distributions.  It is a headache for gpsd, and a big headache for
Gentoo.

I'd rather find, or write, a conversion tool, so it can be done all
at once.

> While doing that, I have another suggestion: could we declutter the
> top directory, please?

Suggestions welcome.  Just remember, I do not look at it as clutter.  I
look at it as accumulated goodness.  A sign of gpsd success that the toy
closet is getting too full for its current organization.

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

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

pgp0TRRqvbctZ.pgp
Description: OpenPGP digital signature