man pages

[Panu Matilainen]

On Fri, 2 Jun 2006, Ralf Corsepius wrote:

> On Thu, 2006-06-01 at 21:24 +0300, Panu Matilainen wrote:
>> 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,
> 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 :)

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

>>> 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"?

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

 	- Panu -