man pages

[Vincent Danen]

* Vincent Danen <vdanen at annvix.org> [2006-06-02 09:57:33 -0600]:

> > I don't at the moment have any strong preference either, I can live with 
> > any of the available choices. So, lets not rush any decision here, I'd 
> > like to hear more people's comments on this (good/bad experiences with 
> > the various tools etc).
> 
> Well, I've almost finished re-factoring the apt-get.8 manpage.  I'm
> using docbook to do it, but would rather just deal with regular man
> format (which is easy enough to convert to at this point using asciidoc
> then moving forward using a straight man format).
> 
> Honestly, I think having man/html/pdf/ps/etc. docs is a waste of time,
> and the overhead doesn't make much sense to me.  For something like apt,
> a man format is sufficient.

Ok, I've finished re-factoring the asciidoc source of apt-get(8) and it
looks much better than what you had on your site... =)  It actually
looks more like a manpage now, but it could be improved...
unfortunately, I don't think it can be improved with asciidoc.

What I would like to do is forget asciidoc and just do the manpage.
Hell, I even volunteer to finish the conversion/cleanup of the other
manpages and will maintain them.

For me, good manpages are an absolute must.  Annvix is a server OS and
as such doesn't have a GUI, and most admins probably won't be firing up
lynx to go to a website to view docs, so none of that is my concern (I
don't think there are any CLI pdf viewers either).  So for me, a good
manpage is priority #1, which is why I'm volunteering to do this.  I
absolutely cannot tell my users that apt-get is replacing urpmi and give
them crap/ugly/out-dated/wrong manpages to go with it.

asciidoc is nice enough, and it probably works wonders for html and
other types of text.. but for manpages, it's not "sophisticated" enough
(or the xsl stylesheets are severely lacking, or both).

Now that I have a good manpage format to start with, I'd like to take
that and modify it to make a "real" manpage out of it.  I've attached
the asciidoc source, the resulting manpage, and the script I had to use
to overcome the lack of bold I'm seeing here (which is another severe
drawback of asciidoc, AFAIC).

Compare it to what Paul initially had, and you'll see it looks quite a
bit better, but it's still not perfect.  I can make it perfect, but only
if we take a strict manpage-only approach, and those who want html docs
or other formats can use the manpage as a basis (using tools like
man2html, etc.).

-- 
{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: apt-get-8.tar.bz2
Type: application/octet-stream
Size: 8257 bytes
Desc: not available
URL: <http://lists.laiskiainen.org/pipermail/apt-rpm-laiskiainen.org/attachments/20060602/0b458362/attachment-0003.obj>
-------------- 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/20060602/0b458362/attachment-0003.pgp>