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

[Greg Troxel]

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

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

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.

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

> Otherwise you have no preference on which is the one true doc format?

I think

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

  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.

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

signature.asc
Description: PGP signature