man pages

[Panu Matilainen]

On Thu, 2006-06-01 at 19:01 +0300, Panu Matilainen wrote:

> For me personally plain old ascii with a bit of formatting is by far the
> preferred way to write documentation, asciidoc just has the added bonus
> it can be converted to pretty much anything through converting it to
> docbook. So it kinda looks like best of both worlds to me: an extremely
> easy format to write docs in and yet can be converted to man pages,
> html, xml, docbook whatever. 

Hmm. To familiarize myself with asciidoc, I converted apt-get.8 manual
to it. It could certainly be improved in various ways, just a quick
experiment of asciidoc-firsttimer: 

The source: http://laiskiainen.org/tmp/asciidoc/apt-get.txt
Docbook version: http://laiskiainen.org/tmp/asciidoc/apt-get.xml
HTML manual: http://laiskiainen.org/tmp/asciidoc/apt-get.html
Trad manpage: http://laiskiainen.org/tmp/asciidoc/apt-get.8

Both the HTML and man pages look reasonably nice, but at least for a
beginner it took a fair amount of fiddling around to make it nicely
formatted and the source isn't *that* readable anymore (eg compared to
Dags dstat example where the source really looks like just an ascii
README without any special markup). Of course there might be cleaner
ways to do the things in apt-get.txt I just don't know them yet :)

	- Panu -