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

[Gary E. Miller]

Yo Greg!

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

> "Gary E. Miller" <gem@rellim.com> writes:
> 
> >> >     xmlto is a simple shell script, but has not been touched in 5
> >> > years/    
> >> 
> >> not really.  the package in pkgsrc needs  
> >
> > I'm not sure what part you are commenting on?  Their commit history
> > clarly shows no commits in 5 years:
> >
> >     https://pagure.io/xmlto/commits?author=ovasik@redhat.com
> >  
> >>   Requires:
> >>   getopt-[0-9]*
> >>   docbook-xsl>=1.67.0nb1  
> >>   libxml2>=2.6.2
> >>   libxslt>=1.1.34nb4    
> >> 
> >> although none of that is problematic.  
> >
> > So why mention it?  What am I missing?
> >
> > Are you just referring to xmkto pulling in libxslt, which pulls in
> > that other stuff?  
> 
> In pkgsrc, the xmlto package  has the four things above as
> dependencies.  You said it was a "shell script" which would have no
> dependencies.

Uh, no, I did not.  Of course everything has dependencies.

> >> I think it is important to produce man pages in mandoc format.  
> >
> > I thought mandoc was an imput format, like .xml, in fact, it is
> > .xml. Unless you are talking about M$ .mdoc?  
> 
> I am talking about the nroff subset used in man page source markup.

Well, of course the man page builder has to build man pages.  But that
is like worrying about what assembler the C compiler uses.  We use gcc,
and AsciiDoc, to hide those details.  We have not written man pages in roff
for ages.


> Right now when I install the gpsd pkgsrc package I get things like
> 
>   /usr/pkg/man/man1/xgps.1
>   /usr/pkg/man/man1/xgpsspeed.1
>   /usr/pkg/man/man1/zerk.1
>   /usr/pkg/man/man3/libQgpsmm.3
>   /usr/pkg/man/man3/libgps.3
>   /usr/pkg/man/man3/libgpsmm.3
>   /usr/pkg/man/man5/gpsd_json.5
>   /usr/pkg/man/man8/gpsd.8
> 
> which when processed with "nroff -man", "nroff -mandoc" produce
> formatted man pages in the traditional UNIX style.  Or with
> mandoc(1), which
> 
>    HISTORY
>        The mandoc utility first appeared in OpenBSD 4.8.  The option
> -I appeared in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
> 
> is a program that interprets the "andoc" nroff style without actually
> implementing nroff.

And that changnes anything gpsd already does, or will do, how?

> > I see only the BSDs uses mandoc, and I thought BSD was happy with
> > the current nroff gpsd man pges?  
> >
> > What am I missing?  
> 
> yes, I am happy with the current pages.  You are missing that you are
> proposing some kind of rototill and therefore it is reasonable to
> explain that these traditional pages need to remain and not be broken
> or withdrawn.  That's all.

Uh, say what?  My two proposals are:

Allow AsciiDoc and Asciidoctor (done).

Convert .xml man pages and html to ..adoc man pages and html.

Absolutly nothing user visible.

> I think
> 
>   we need traditional man page sources (e.g gpsd.8) to be installed as
>   part of the build

Of course.  Has anyone suggested otherwise?

>   tools should have a reasonable dependency load.   python is fine,
>   fewer packages is better, ruby is not terrible, anything in haskell
> is out of the question because haskell has no portable
> implementations.

How did Haskell get in here?  Also, of course, we want to 68K assembler
code.

> so if you want to use assciidoc and still end up with gpsd.8 etc., I'm
> ok with that.

Good.  The plan is no user visible, or runtime, changes.  Just trying
to make it easy for developers.

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

pgpAlHx2HgQV8.pgp
Description: OpenPGP digital signature