man pages

[Vincent Danen]

* Panu Matilainen <pmatilai at laiskiainen.org> [2006-05-28 14:47:25 +0300]:

> > > > Please use the sgml/xml documentation format. It's nice for creating
> > > > non-manpage documentation, but I certainly agree having to "compile" man
> > > > pages is silly. I wouldn't be against somebody submitting a patch to
> > > > make "make dist" build the documentation as well for inclusion in
> > > > distribution tarballs, hint hint :)
> > > 
> > > Yeah, but the problem with sgml/xml documentation is you need to have
> > > the appropriate dtd's and whatnot available... I could only do so by
> > > either a) adding about a half-dozen or so packages to Annvix (for use by
> > > a single package in *compiling*, nevermind day-to-day use), or b)
> > > compile them on a Mandriva system and make a separate tarball.
> > > 
> > > So forgive me if I'm not too keen on the xml/sgml idea.  =)
> 
> Re-read my comment, I wouldn't be opposed to having pre-compiled manual
> pages in the distribution tarballs, somebody just send me a patch to
> make the compilation happen automatically in "make dist". Then you
> wouldn't need the docbook-toolchain to build apt, only my systems would
> need them (which I don't mind)

That and whoever is working on them.  I've worked in docbook before for
the Mandriva manuals... ick.

(BTW, I'm going through some old-ish mails now so maybe a consensus has
been reached... I've been "out" most of the week since my wife had
surgery on Monday, so I'm trying to catch up a bit).

> > > What other formats do you want the manpages in other than txt and html?
> > > There are man2txt and man2html converters about that would be
> > > sufficient, no?  Or are you making pdf files with these?
> > 
> > Have you ever looked at asciidoc. I'm using asciidoc everywhere now, for 
> > manpages and normal documentation. asciidoc is just a strict formatting 
> > for ascii txt files so that they are still human readable as-is, are very 
> > easy to create (once you know the syntax) and you only need the asciidoc 
> > tool to convert to html or docbook. From the docbook output you can move 
> > to man-pages, PDF and others.
> > 
> > A simple example is at:
> > 
> > 	http://svn.rpmforge.net/svn/trunk/tools/dstat/dstat.1.txt
> 
> Hum, that looks very nice indeed. I'm in no way love with the docbook
> stuff, it's cumbersome to write which raises the bar on updating
> documentation quite significantly, whereas the above .. Thanks Dag for
> the pointer, I'll seriously consider switching to that for my own
> projects :)

I looked briefly at asciidoc as well, and I think it's fantastic.  I'd
really prefer to use something simple like that.

-- 
{FEE30AD4 : 7F6C A60C 06C2 4811 FA1C  A2BC 2EBC 5E32 FEE3 0AD4}
mysql> SELECT * FROM users WHERE clue > 0;
Empty set (0.00sec)

Annvix - Secure Linux Server: http://annvix.org/
-------------- 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/20060601/af9f0f33/attachment-0003.pgp>