Bill Studenmund <wrstuden@zembu.com> writes:

        I think SGML  (DocBook DTD when we  speak about programming or system
        documentation) would be the best choice: ability to get in the output
        almost any reasonable format (plain text, TeX, html, xml, PostScript,
        PDF or what you really want) is a big win. I see only two dark sides:

        * converting between SGML   and requested format  is relatively  slow
          especially on the old or slow technique (but we could have at least
          preformatted  text manuals and  use   them instead of  direct  SGML
          processing).  Even more,  PostScript and PDF  require TeX installed
          somewhere.

        * SGML processor should imported into system source tree and requires
          maintaining. At least sometimes.

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