man pages

[Panu Matilainen]

On Thu, 2006-06-01 at 08:31 +0200, Ralf Corsepius wrote:
> On Tue, 2006-05-30 at 09:06 +0200, Ralf Corsepius wrote:
> > On Mon, 2006-05-29 at 19:44 +0300, Panu Matilainen wrote:
> > > On Mon, 2006-05-29 at 07:24 +0200, Ralf Corsepius wrote:
> > 
> > > The fr/es/pt_BR translations aren't built at all now but considering how
> > > totally out of date those are it's not much of a loss.
> > Having tried to add the fr translations, these prove to be broken.
> > 
> > Therefore, I'd propose to dump all of the translations.
> > 
> > >  We can add them
> > > back if somebody provides updates to them someday.
> > Did you have a look into apt-0.6.xx? They changed the source file format
> > from sgml to something else (I haven't check what kind of xml it is).

It's "xml docbook 4 format":
http://lists.debian.org/deity/2003/12/msg00061.html

I you want to compare here's an example:
http://laiskiainen.org/tmp/apt-get.8.xml
http://laiskiainen.org/tmp/apt-get.8.sgml

> > 
> > So, one of the next steps would be to decide on how to proceed with the
> > man-pages.
> > 
> > IMO, the only viable alternative would be to
> > a) completely decouple from Debian
> > or
> > b) converge to Debian apt-0.6.x
> > 
> > In case of a) another question would be to decide on if using manually
> > written man-pages or continuing to use generated ones.
> > I think using manually written, apt-rpm specific man-pages would be the
> > easiest approach.
> Ping? Any opinions, any decisions, any consensus?

Decisions no, some opinions yes: The xml docbook is a bit nicer perhaps
than the old sgml but I don't particularly like either. Manually written
man pages I can certainly live with, but they are limited in conversion
possibilities. However Dag's example of asciidoc made me fall in love :)
http://svn.rpmforge.net/svn/trunk/tools/dstat/dstat.1.txt

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. 

Dag (or others) - any idea if it's possible to generate asciidoc from
docbook with some tool? Otherwise it'd be quite a bit of effort to
rewrite all the docs from scratch (which might not be such a bad idea
anyway :) in asciidoc. The docbook sgml can be converted to docbook xml
more-or-less automatically I'd think, and in the "plain manpages" path,
well, we already have those manpages generated from docbook to start
from.

My personal preferences wrt ascii aside, what I'd to use is something
that people feel comfortable working with so the barrier to submitting
doc improvements and translations is reasonably low. Somehow I have this
feeling the current sgml docbook is just about the worst possible format
considering that... :)

	- Panu -