man pages

[Dag Wieers]

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

Convert it using:

	%.html: %.txt
		asciidoc -b xhtml11 -d manpage $<

	%.xml: %.txt
		asciidoc -b docbook -d manpage $<

	%.1: %.1.xml
		xmlto man $<

Kind regards,
--   dag wieers,  dag at wieers.com,  http://dag.wieers.com/   --
[all I want is a warm bed and a kind word and unlimited power]