Very Computer

My manager is real hot to have man pages on our internal library functions,
and I have never written a man page. So is there a good basic HOWTO on Man
Page writing out there. We are using a variety of UNIX and UNIX-like boxes
here.

Thanks,

Dale Pennington

Just follow the examples is /usr/share/man.

--
Rich Teer

President,
Rite Online Inc.

Voice: +1 (250) 979-1638
URL: http://www.rite-online.net

Just looking at a manpage (after unzipping) was already said.

There is another option of generating manpages: perldoc. It uses
an easy description format, much easier to use than nroff.
Examples should be the pm files in /usr/lib/perl (most modules
contain their own manpage in the same file). The program pod2man
(see man pod2man) can make manpages of .pod files.

Here a small example:

,---
| =head1 NAME
|
| ByteLoader - load byte compiled perl code
|
| =head1 SYNOPSIS
|
|   use ByteLoader 0.04;
|   <byte code>
|
|   use ByteLoader 0.04;
|   <byte code>
|
| =head1 DESCRIPTION
|
| This module is used to load byte compiled perl code. It uses the source
| filter mechanism to read the byte code and insert it into the compiled
| code at the appropriate point.
|
| =head1 AUTHOR
|

|
| =head1 SEE ALSO
|
| perl(1).
`---

There are some escape codes:

E<gt> and E<lt> stand for the > and < character. B<text> makes the inner
text bold, I<text> italic. <> sequences can be nested, example:

B<E<gt>>

--
Your password must be at least 18770 characters and cannot repeat any of
your previous 30689 passwords. Please type a different password. Type a
password that meets these requirements in both text boxes. [M$]
(Fix: http://support.microsoft.com/support/kb/articles/q276/3/04.ASP)

Or try the query "how to write man pages" on google. Here are a couple
links that might be good (I didn't read them).

http://www.cs.hmc.edu/tech_docs/qref/writing_man_pages.html
http://www.fokus.gmd.de/linux/HOWTO/mini/Man-Page.html

Joe
--
Remember Flight 93

If you know perl, and even if you don't, do a  'man perlpod', and man
pod2man'

-shane

Looking at your example, I think "much easier than nroff" is an
exaggeration!  Different, yes, but since when is

=head1 NAME

much easier than

.SH NAME

--
Rich Teer

President,
Rite Online Inc.

Voice: +1 (250) 979-1638
URL: http://www.rite-online.net

Take a look at Doxygen (www.doxygen.org) for a nice way to automatically
generate the pages from comments in your c/c++/java source code. We've
recently begun using it here and it has made life much easier- one command
can generate HTML, PDF, manpage, etc output.

--
-David Wilson
Princeton Satellite Systems

This is equivalent. But isn't

This is B<bold> text

easier to read and write than

This is
.B bold
text

because the paragraphing remains?

--
#!/usr/bin/perl -- PAY, PAY, PAY!!!
printf "You owe me EUR %.2f\n",  !\  1   |  1  |   1
                                 | \ 1   |  1  |   1
                                 |  \1   &+-/  \== \\/

Not to me - but then I'm used to reading and writing
roff sources!

Also, "This is \fBbold\fP text" also does the job, avoiding
the paragraphs.  Of course, all my paragraphs start with
.LP, so it doesn't stick out to me.

--
Rich Teer

President,
Rite Online Inc.

Voice: +1 (250) 979-1638
URL: http://www.rite-online.net

Quote:>My manager is real hot to have man pages on our internal library functions,
>and I have never written a man page. So is there a good basic HOWTO on Man
>Page writing out there. We are using a variety of UNIX and UNIX-like boxes
>here.

Check the man page for the [ntg]roff [m]an macro package -- on Solaris,
man -s 5 man

--
Andrew Gabriel
Consultant Software Engineer

| So is there a good basic HOWTO on Man Page writing out there.

Others posted pointers for the HOWTO.

I have used c2man to generate manpages from C/C++ in the past and
found it ok.  I don't know whether it still is maintained, a starting
point might be http://packages.debian.org/unstable/devel/c2man.html

R'

 : My manager is real hot to have man pages on our internal library functions,
 : and I have never written a man page. So is there a good basic HOWTO on Man
 : Page writing out there. We are using a variety of UNIX and UNIX-like boxes
 : here.

There is a man page which describes a set of macros in troff man macro
package, which is conventional means of writing man page. It is
typically man(7) and can be viewed by man 7 man.

Use it both as guide and as example. Look into couple of other shorter
manual pages (like cat(1)). There is nothing complicated.

--
The most important design issue... is the fact that Linux is supposed to
be fun...
        -- Linus Torvalds at the First Dutch International Symposium on Linux

In addition to what others suggested, let me advertise a little
SGML-docbook-sources to man-page format.  So you can write a man-page
using docbook, which -- depending on your personal prefernce -- may or may
not be easier for you.

See http://mama.sourceforge.net

-Jan

--
Jan Schaumann <http://www.netmeister.org>

I know I don't deserve another chance, but this _is_ America,
and as an American, aren't I entitled to one?  --Sideshow Bob.

Well, there's a little something to be said for sticking with a "standard"
format, like man pages.

But a few folks find man pages to be generally abominable.

They're fine if you wrote the blessed program, and occasionally need
a reminder of what the -X option does.

But for most anyone else, they tend to be mighty cryptic.
For example, do a  "man sed"  and try to find just ONE example.
Is this a good example to follow?

Quote:> But a few folks find man pages to be generally abominable.

> They're fine if you wrote the blessed program, and occasionally need
> a reminder of what the -X option does.

> But for most anyone else, they tend to be mighty cryptic.
> For example, do a  "man sed"  and try to find just ONE example.
> Is this a good example to follow?

Extremely faulty reasoning.

If I disagree with the contents of a book, should I consider the concept
of paper books "abominable"?

The "man sed" on my system contains a number of examples.  (Perhaps you
forgot that man pages are specific to the system in question?)

Poorly-written documentation is independent of the media:  moving *
from man format to HTML doesn't make the docs any less cryptic, it only
makes it *with a different user interface.

Phil

--
If ye love wealth greater than liberty, the tranquility of servitude greater
than the animating contest for freedom, go home and leave us in peace.  We seek
not your counsel, nor your arms.  Crouch down and* the hand that feeds you;
and may posterity forget that ye were our countrymen.            - Samuel Adams