Thanks to all the folks who responded:
Thomas Anders, Anthony David, Sanjiv Bhatia, Vince Taluskie, Danny Johnson,
Karl Vogel, and kevin@joltin.com.
Oringinal Question:
I have been developing some programs, scripts etc. that I want to add to our
systems. To support those, I would like to create man pages, but without
having to do nroff/troff by hand. Anyone know of a generator/template that
would help ease the pain? :)
Responses:
Thomas Anders:
"help2man" produces manpages from reasonable GNU-style --help/--version
output
of the program itself. See
http://www.ozemail.com.au/~bod/
Karl Vogel:
I use the template below.
---------------------------------------------------------------------------
.\" $Id$
.\"
.\" Macros
.de Vb
.ft CW
.nf
.na
.in 0
.if \\$1 .ne \\$1
..
.de Ve
.in 2
.ft R
.fi
.ad
..
.\" End of Macros
.TH NAME SECTION "3 Jan 2000"
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.\" ----------------------------------------------------------------------
.SH NAME
progname \- program to do something
.\" denote multiple entry points on previous line; makewhatis will catch
them
.\" ----------------------------------------------------------------------
.SH SYNOPSIS
A short usage summary
.\" ----------------------------------------------------------------------
.SH "DESCRIPTION"
Long drawn out discussion of the program. It's a good idea
to break this up into subsections using the .SS macros, like
these:
.SS "A Sample Subsection"
Subsection 1.
.SS "Yet Another Sample Subsection"
Subsection 2.
.\" ----------------------------------------------------------------------
.SH OPTIONS
Some people make this separate from the description.
.\" ----------------------------------------------------------------------
.SH "RETURN VALUE"
.TP 25
Function returns with
If
.TP 25
0
Everything is OK.
.\" ----------------------------------------------------------------------
.SH ERRORS
.TP 25
Program exits with
If
.TP 25
0
Everything is OK.
.TP 25
1
Usage error.
.\" ----------------------------------------------------------------------
.SH EXAMPLES
Give some example uses of the program.
.PP
.Vb
\& These lines hold sample output or
\& a keyboard session.
.Ve
.PP
.\" ----------------------------------------------------------------------
.SH ENVIRONMENT
Environment variables this program might care about
.\" ----------------------------------------------------------------------
.SH FILES
All files used by the program. Typical usage is like this:
.PP
.TP 25
\fI/usr/man/man*/*.*\fR
Unformatted (nroff source) man pages
.\" ----------------------------------------------------------------------
.SH "SEE ALSO"
.\" Always quote multiple words for .SH
Other man pages to check out, like man(1), man(7), makewhatis(8), catman(8)
.\" ----------------------------------------------------------------------
.SH NOTES
Miscellaneous commentary
.\" ----------------------------------------------------------------------
.SH CAVEATS
Things to take special care with; sometimes called WARNINGS.
.\" ----------------------------------------------------------------------
.SH DIAGNOSTICS
All the possible error messages the program can print out, and
what they mean. Use the .TP format above.
.\" ----------------------------------------------------------------------
.SH BUGS
Things that are broken or just don't work quite right.
.\" ----------------------------------------------------------------------
.SH RESTRICTIONS
Bugs you don't plan to fix :-)
.\" ----------------------------------------------------------------------
.SH AUTHOR
Who wrote it (or AUTHORS if multiple), often in the form
.br
Your full name
.br
Your organization or mail address
.\" ----------------------------------------------------------------------
.SH HISTORY
Programs derived from other sources sometimes have this.
----------------------------------------------------------------------------
-------------------------------------------
Anthony David:
If you have Perl installed, have a look at man perlpod or perldoc perlpod.
kevin@joltin.com:
Grab one from /usr/man - it's what we did for our man pages.
Sanjiv Bhatia:
I have a utility to create man pages that can be created in HTML and seen
through a browser. I can give you the source code if you like.
Vince Taluskie:
Scripts in perl? use the Pod documentation format and your script can be
it's own man page...
Danny Johnson:
easy way is convert them to plain text and put them in the
"cat#" directories instead of the "man#" directories.
Again, Thanks for all the help
Bob
Bob Fulwiler
Network Architecture & Design / Network Computing Services
voice: 206.634.4933
email: robful@safeco.com
This archive was generated by hypermail 2.1.2 : Fri Sep 28 2001 - 23:14:01 CDT