Curt Sampson says:
> On Fri, 21 Jan 2000, Matthew Orgass wrote:
> 
> > * I think it would be a good idea to convert the man pages to DocBook. 
> > SGML is *much* nicer to read then roff and can be additionally marked up
> > for more expressive medium.
> 
> I'm pretty much in agreement that troff has probably got to go if
> we're going to have folks who haven't been using Unix since 1980 doing
> signifcant work on the documentation. Heck, I used to do *everything*
> in troff, including personal letters, but even I can't stand it now.
...

I'm awfully fond of Perl's POD (plain old documentation) system for
writing documentation.  It is not a general purpose system for text
layout, but it generates plain old documentation just fine.  (Hey,
truth in advertising!)  Plus it's embeddable in Perl.  Since Perl
comes with pod2man (which generates nroff output suitable for display
with the man macros) and pod2html translators, as well as for TeX and
others, you can get pretty much whatever other format you might like
from it.

From the "perlpod" manpage:


         Note that I'm not at all claiming this to be sufficient
         for producing a book.  I'm just trying to make an
         idiot-proof common source for nroff, TeX, and other
         markup languages, as used for online documentation.
         Translators exist for pod2man  (that's for nroff(1) and
         troff(1)), pod2html, pod2latex, and pod2fm.

Embedding Pods in Perl Modules
     You can embed pod documentation in your Perl scripts.  Start
     your documentation with a =head1 command at the beg, and end
     it with an =cut command.  Perl will ignore the pod text.
     See any of the supplied library modules for examples.  If
	...

I think the core ideas in POD are good, and whatever markup NetBSD
docs get written in could take a lesson or two from the simplicity of
the POD system.  It's certainly fully capable of allowing for easy
authoring of typical man pages.

My humble two cents.

Regards,
James Wetterau