man pages

[Vincent Danen]

* Vincent Danen <vdanen at annvix.org> [2006-06-01 15:45:46 -0600]:

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

Good lord... I'm getting about a bajillion xsl-related errors trying to
compile this thing with "a2x -f manpage apt-get.txt".  Did you have to
do anything special to get this thing running?


-- 
{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/070878df/attachment-0003.pgp>