nit to pick: docbook

[Vincent Danen]

* Dag Wieers <dag at wieers.com> [2006-05-05 07:28:34 +0200]:

> > I have a nit... and I need to pick it.
> > 
> > Why oh why are manpages being provided in sgml format which requires me
> > to not only use but actually provide MB's of docbook and other sgml
> > related junk that the only other package I've seen require is the linux
> > kernel, and then only if you actually want the docs.
> > 
> > manpages shouldn't *have* to be compiled like that.  I think it's
> > impolite.  =)
> > 
> > Could I possibly convince you to provide the "compiled" manpages in the
> > tarball so I don't *have* to build and provide docbook (or,
> > alternatively, build them on another system that has docbook and add the
> > manpages in their own tarball as another source for my rpm)?
> > 
> > I don't know what other formats those manpages and docs are supposed to
> > be provided in (html, maybe?) but I think the manpages should be
> > "unencumbered" to those of us with slim systems.
> > 
> > My $0.02CAD.  Sorry to start making demands already... =)
> 
> I'm very fond of asciidoc, maybe that's an acceptable alternative ?
> 
> In essence it's a strict human-readable ascii format (that is acceptable 
> just as plain text) but can be converted nevertheless to manpages, 
> html-pages or PDF.

But what do you need to "compile" it?  Ie. with the sgml format, I need
docbook2man and the particular stylesheets to process it.  The third
machine I tossed the tarball on was capable of doing it, but after only
I installed a whole slew of stylesheets.

Right now I have an apt-rpm.tar.bz2 source in my apt srpm... =(  Because
I refuse to install something useless required by only one package to
*build* (nevermind use).  That adds bloat that I'm trying to reduce.

When those sgml files are updated, I really don't see how difficult it
would be to run docbook2man before you commit it or roll the tarball.
Everybody else does it.  Well, everybody else just has manpages... not
too many use docbook/sgml files to turn manpages into, well, manpages.
I just really dislike the "fluff" required to make a simple manpage.

I've never heard of asciidoc, so I don't know if it would be acceptable.
If it's going to add a lot of overhead just to do one operation, then
I'm better off going through the pain of running configure and make in
the doc directory on a Mandriva box, tar up the manpages and use them as
an external source.  A pain, yes, but it saves me dealing with packaging
a, for Annvix, pretty much useless set of packages.  They may not be
overly big, but it's the maintenance of them I'm more concerned with.

-- 
Annvix - Secure Linux Server: http://annvix.org/
"lynx -source http://linsec.ca/vdanen.asc | gpg --import"
{FEE30AD4 : 7F6C A60C 06C2 4811 FA1C  A2BC 2EBC 5E32 FEE3 0AD4}
Wasting time like it was free...
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 186 bytes
Desc: not available
URL: <http://lists.laiskiainen.org/pipermail/apt-rpm-laiskiainen.org/attachments/20060505/a4d71929/attachment-0003.pgp>