From owner-freebsd-doc  Fri Nov 21 22:54:25 1997
Return-Path: <owner-freebsd-doc>
Received: (from root@localhost)
          by hub.freebsd.org (8.8.7/8.8.7) id WAA17764
          for doc-outgoing; Fri, 21 Nov 1997 22:54:25 -0800 (PST)
          (envelope-from owner-freebsd-doc)
Received: from coven.queeg.com (queeg.com [204.95.70.218])
          by hub.freebsd.org (8.8.7/8.8.7) with ESMTP id WAA17757;
          Fri, 21 Nov 1997 22:54:19 -0800 (PST)
          (envelope-from brion@coven.queeg.com)
Received: (from brion@localhost)
          by coven.queeg.com (8.8.5/8.8.4)
	  id WAA12553; Fri, 21 Nov 1997 22:54:06 -0800 (PST)
Date: Fri, 21 Nov 1997 22:54:06 -0800 (PST)
Message-Id: <199711220654.WAA12553@coven.queeg.com>
From: Brion Moss <brion@queeg.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
To: David Petrou <dpetrou@kinclaith.pdl.cs.cmu.edu>
Cc: freebsd-doc@freebsd.org, freebsd-questions@freebsd.org
Subject: Re:[Q] Making man pages...
In-Reply-To: <199711220417.UAA10771@hub.freebsd.org>
References: <199711220417.UAA10771@hub.freebsd.org>
X-Mailer: VM 6.22 under 19.15 XEmacs Lucid
Sender: owner-freebsd-doc@freebsd.org
X-Loop: FreeBSD.org
Precedence: bulk

Hi, David!  Long time no see...

There are two macro sets that people use to write man pages.  4.4BSD
and derivatives use the "doc" macro set.  The rest of the world uses
the "man" macro set.  When you read a man page under FreeBSD, it gets
processed by the "mandoc" macro package, which basically looks at the
file and passes it on to either "man" or "doc", depending on what kind
of file it looks like.

I'd suggest using the "man" macro set, because its more portable, but
I'm sure there are good reasons to prefer "doc".

In any case...you can get a description of the two macro languages by
reading the man pages for man(7) and mdoc(7).  There's a pretty good
(but brief) tutorial on writing man pages in the standard man format
at http://elc2.igpm.rwth-aachen.de/~albrecht/manpage.html.  There's
also a manpage-howto somewhere in the Linux documentation.  I
generally take an existing man page as a template and modify it; the
language is pretty simple and I usually only use a small subset of
it. 

	-Brion

David Petrou writes:
> I've recently written some software for FreeBSD and I would like to
> write some man pages for them.  How do people make manpages today?  Do
> they write in troff directly?  I know nothing of troff.  Are
> there tools that perhaps convert a subset of TeX to troff?
> 
> Do people generally take existing man pages and modify them to create
> new ones, or is there a blank template for new man pages?
> 
> I've checked the FAQ and Handbook and came up empty on this topic.
> 
> Thanks,
> David
> 
> P.S.: Please reply to dpetrou@cs.cmu.edu besides the list, as I'm not
> subscribed to these lists.