On Tue, 18 Jul 2000, Jim Bernard wrote:

> On Mon, Jul 17, 2000 at 01:05:32PM -0700, Mike Cheponis wrote:
> > 
> > If the man pages were html, with links to deeper documentation levels (even 
> > automatically generated documentation), that would be better.

I have to (politely) disagree with Mike here. I think HTML's ability to
have links to other pages is a good thing and something we should
explore. However I think that html would be a horrid language to use to
actually maintain the page. It'd be kinda like using PostScript to
maintian the document. :-)

HTML is great at being a markup language - it tells a program how to
display a document. It's not great at retaining concepts. Look at the
existance of things like DocBook. Many folks have gone to not using HTML
in the raw, but using some sort of document language which can be turned
into html. Because HTML doesn't retain the concepts of what it's marking
up.

>   Of course, the (mdoc) man pages are trivially converted to html via, e.g.,
> 
>     nroff -mdoc2html /usr/share/man/man1/man.1
> 
> since /usr/share/tmac/tmac.doc2html has been in the tree for quite some time.
> It even has a macro for generating links (Lk), though it appears not to have
> been used in any of the NetBSD man pages, and it's not documented on the
> mdoc man page.

My, don't we all look smart, arguing about somethign Ross put into the
tree like 18 months ago, and which is in 1.4. :-)

I think this would be the best solution. Having man pages made with this
would keep our man pages in mdoc and yet give us ready html. And with the
Lk macro (which I haven't looked at), we could embed the links which HTML
is good for. :-)

All this would mean is: 1) adding links to existing man pages, and
2) generating make infrastructure to make html man pages.

Note: I'm not suggesting we ship them by default, just that we have
machinery to automatically build them if desired, both from source and
from installed raw man pages. When we get the base install packaged, then
we can put them into the base. :-)

Thoughts?

Take care,

Bill