man pages

[Panu Matilainen]

On Sun, 2006-05-28 at 11:29 +0200, Dag Wieers wrote:
> On Sat, 27 May 2006, Vincent Danen wrote:
> 
> > * Panu Matilainen <pmatilai at laiskiainen.org> [2006-05-27 21:08:59 +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)

> > 
> > 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 :)

	- Panu -