man pages

[Dag Wieers]

On Sun, 28 May 2006, Panu Matilainen wrote:

> On Sun, 2006-05-28 at 11:29 +0200, Dag Wieers wrote:
> > On Sat, 27 May 2006, Vincent Danen wrote:
> > 
> > > What other formats do you want the manpages in other than txt and html?
> > > There are man2txt and man2html converters about that would be
> > > sufficient, no?  Or are you making pdf files with these?
> > 
> > Have you ever looked at asciidoc. I'm using asciidoc everywhere now, for 
> > manpages and normal documentation. asciidoc is just a strict formatting 
> > for ascii txt files so that they are still human readable as-is, are very 
> > easy to create (once you know the syntax) and you only need the asciidoc 
> > tool to convert to html or docbook. From the docbook output you can move 
> > to man-pages, PDF and others.
> > 
> > A simple example is at:
> > 
> > 	http://svn.rpmforge.net/svn/trunk/tools/dstat/dstat.1.txt
> 
> Hum, that looks very nice indeed. I'm in no way love with the docbook
> stuff, it's cumbersome to write which raises the bar on updating
> documentation quite significantly, whereas the above .. Thanks Dag for
> the pointer, I'll seriously consider switching to that for my own
> projects :)

I forgot to mention however, that asciidoc requires python 2.3 or newer, 
which is not available on older distributions (like EL3). Which to me is 
the only drawback.

But then again, like you mentioned, the files only need to be generated 
when doing 'make dist' so asciidoc is only a requirement for developers, 
not for packagers or users.

Kind regards,
--   dag wieers,  dag at wieers.com,  http://dag.wieers.com/   --
[all I want is a warm bed and a kind word and unlimited power]