Docbook to Man pages

[Jordan Mantha]

On 8/13/06, Dan McGarry <it.psl at fsp.org.vu> wrote:
> Matthew East wrote:
> >
> > Or to ship an ubuntu-server-docs package with the HTML files. Are you
> > quite sure a "man page" is necessary, it sounds to me like more work
> > than it is worth. I'm confident we can prepare HTML which looks good in
> > a text based browser.
>
> For a server installation, I'd suggest that man pages are highly
> desirable. They are the de facto standard for usage documentation on the
>   console.

I don't think creating man pages out of the Server Guide is a good
idea. man pages are fine for small app docs but trying to read a whole
server guide via man would be less than ideal, IMO. HTML allows you to
jump around better and linking is nice. If we have any links to
onlince resources too HTML would be an advantage. Finding what you
want in a man page can be pretty difficult if it is very large.

> Personally, I often measure the value of a utility based on the quality
> of its man page. I accept that anecdote is not the singular form of
> 'data', but I know I'm not alone in this regard. 8^)

I agree that a good man page is invaluable but app docs are quite a
bit different than the Server Guide.

> Second, the difference in effort is, if I understand correctly, entirely
> in the creation of the XSL file. Once that exists, you have an avenue
> not only for this document, but for any other that could be usefully put
> into man format. I think the benefits far outweigh the costs, even of a
> simple compromise.

We already have HTML XSL files and experience. I think it would be
quite a bit easier to do HTML than man.

> My two vatu....

and my USD$0.02

-Jordan

-- 
"That's all very well in practice, but will it ever work in theory?" -- G. Hill
"A tidy laboratory means a lazy chemist." -- Jöns Jacob Berzelius