Subject: Re: what *roff macro set to use for writing documentation?
To: None <,>
From: Ross Harvey <>
List: tech-pkg
Date: 08/20/1999 17:29:37
> From: Lou Glassy <>
> dear all,
> I'd like to take the 'Package.txt' documentation for 
> the NetBSD package system, and transmogrify it into 
> a *roff document (which with other magic, could be 
> converted into TeX, HTML, etc)...
> Question:  what *roff macro package would you recommend
> to use for this sort of documentation?
> It looks like some of the docs under /usr/share/doc/psd
> use the me package.  Is this the recommended one to use
> for new documentation?

No, it should be done in -mdoc (see `man 7 mdoc', and `man 7 mdoc.samples')
for a variety of reasons.

    *	developer awareness -- bsd developers kind of need to know
	-mdoc, but they don't need to know the others. It's probably
	best not to expand the number of -m macros they have to learn
    *	lots of examples (most of the man pages)
    *	very nice looking output
    *	good driver directions (man 7 mdoc{,.samples})
    *	it's the only macro package we put effort into maintaining
    *	we have the -mdoc2html macros in-tree
    *	it's probably the most elaborate of all the packages, with the
	most features

But troff-ing Packages.txt is, in general, an excellent idea, and actually
I already did it, six months or a year ago. I'll see if I can find my work
and merge it with recent changes or just send it to you.

agc supported the conversion, although there was one complaint from a
developer who for some reason thought he would be unable to edit it for
content after markup insertion.

I believe I dealt with that by offering to edit in all his future mods.
This turns out to have been more clever than I thought: he has not
subsequently modified Packages.txt, in fact, not for over a year, even
though I never did convert it. :-) (Except privately, of course,  but no
one knew that.)