man pages

[Vincent Danen]

* Panu Matilainen <pmatilai at laiskiainen.org> [2006-06-01 23:39:16 -0700]:

> >>> For me personally plain old ascii with a bit of formatting is by far the
> >>> preferred way to write documentation,
> > Frankly speaking, I don't see any need for anything beyond plain old
> > man-pages. People wanting to use html-manpages, always can resort to
> > man2html, but I never understood why people would want html-formated
> > man-pages ;)
> 
> Heh, me neither really :)

Well, the suggestion of asciidoc and other systems was on the assumption
that others would want the docs in other formats, but I don't really see
that as being important.  I mean, realistically speaking, if I need to
look at info on apt-get, I'll "man apt-get", not go to the website to
look at a manpage.

Frankly, I would be happier just making the docs in man format... it's
much easier.

Oh, and your FC4 vs FC5 experience is another reason I'm not keen on
asciidoc itself (actually, asciidoc is fine, it's the different xsl
stylesheets and processing that is causing the problems I think).

At any rate, I've managed to cludge it so I don't have to do any special
pre-processing of foreign symbols, and can work around the limitation
I'm currently seeing using Mandriva LE2005 to build it.  I can't make it
work properly in Annvix or Mandrake 2006, however, which is almos why I
would prefer to do this in a strict man format.

> > Real docs/manuals are a different issue.
> >
> >>> asciidoc just has the added bonus
> >>> it can be converted to pretty much anything through converting it to
> >>> docbook.
> > Hmm, I am not familiar with asciidoc. To me, it's an exotic tool, with
> > an unknown footprint, I'd rather not rely upon.
> 
> It's a new thing for me as well and I'm not quite convinced. It's nice 
> (for me) in many ways but...

It has it's limitations, based on what version of libxml, xsltproc, etc.
you're using.  And the stylesheets as well.

> >>> 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.
> > docbook would be fine with me, esp. as it seems to be what Debian seems
> > to be using, which would help keeping diffs to upstream low.
> 
> I don't really consider Debian as upstream anymore :) Perhaps more like a 
> sidestream. Their docs are full of debianisms to the point it's just 
> annoying to apt-rpm users, unless the docs started to be conditionally 
> built in #ifdef HAVE_RPM/#endif style and we started sending our doc 
> updates back to them. Does docbook even support "conditional compilation"?

Frankly, I would ignore debian as far as docs go.  I think apt-rpm has
suitably changed and merging docs back seems useless to me unless you
merge back the entire apt-rpm codebase as well, which I think is
probably unlikely.  So if you're not going to do one, why bother with
the other?

> > The question I can't answer is: Which tool to use to convert docbook
> > into "pre-built docs"?
> 
> 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.

-- 
{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/20060602/40801127/attachment-0003.pgp>