man pages

[Vincent Danen]

* Panu Matilainen <pmatilai at laiskiainen.org> [2006-06-01 21:24:09 +0300]:

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

Personally, I would go for the asciidoc format, and I'll even take what
you started there and work on it, and the others, as time permits.  I do
have a week and a half off here, and because I'm taking advantage of
apt-rpm for Annvix now, I'd like to contribute something back (and my
stronger suit is documentation, rather than development).

So unless someone yells "hell no", I'll start on this.  I'll try to do
as much as I can with a bed-resting wife and four-year old daughter so I
can't promise a quick work, but I'll try to have at least some of this
done and ready to contribute back this weekend.

-- 
{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/6cd1a83f/attachment-0003.pgp>