HOWTO on Man Page Writing ?

HOWTO on Man Page Writing ?

Post by Dale Penningto » Sat, 10 Nov 2001 02:04:55



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

 
 
 

HOWTO on Man Page Writing ?

Post by Rich Tee » Sat, 10 Nov 2001 02:18:48



> 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.

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

 
 
 

HOWTO on Man Page Writing ?

Post by Rudolf Polze » Sat, 10 Nov 2001 02:36:34



>  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.

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)

 
 
 

HOWTO on Man Page Writing ?

Post by Joe Halpi » Sat, 10 Nov 2001 02:44:47




> > 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.

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

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

 
 
 

HOWTO on Man Page Writing ?

Post by Shane McDanie » Sat, 10 Nov 2001 04:07:52



> 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

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

-shane

 
 
 

HOWTO on Man Page Writing ?

Post by Rich Tee » Sat, 10 Nov 2001 06:24:48



> There is another option of generating manpages: perldoc. It uses
> an easy description format, much easier to use than nroff.

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

 
 
 

HOWTO on Man Page Writing ?

Post by David Wilso » Sat, 10 Nov 2001 06:38:43


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.


> 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

--
-David Wilson
Princeton Satellite Systems
 
 
 

HOWTO on Man Page Writing ?

Post by Rudolf Polze » Sat, 10 Nov 2001 07:16:57




> > There is another option of generating manpages: perldoc. It uses
> > an easy description format, much easier to use than nroff.

>  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

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   &+-/  \== \\/

 
 
 

HOWTO on Man Page Writing ?

Post by Rich Tee » Sat, 10 Nov 2001 10:52:43



> This is B<bold> text

> easier to read and write than

> This is
> .B bold
> text

> because the paragraphing remains?

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

 
 
 

HOWTO on Man Page Writing ?

Post by Andrew Gabri » Sat, 10 Nov 2001 05:49:17




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

 
 
 

HOWTO on Man Page Writing ?

Post by Ralf Fasse » Sat, 10 Nov 2001 22:18:30



| 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'

 
 
 

HOWTO on Man Page Writing ?

Post by Victor Wagn » Tue, 13 Nov 2001 00:07:14



 : 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

 
 
 

HOWTO on Man Page Writing ?

Post by Jan Schauman » Tue, 13 Nov 2001 12:50:43



>  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.

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.

 
 
 

HOWTO on Man Page Writing ?

Post by George R. Gonzale » Thu, 15 Nov 2001 07:43:56




> >  My manager is real hot to have man pages on our internal library
functions,
> >  and I have never written a man page.

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?

 
 
 

HOWTO on Man Page Writing ?

Post by Phil Edwar » Wed, 14 Nov 2001 12:11:31



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

 
 
 

1. HOWTO-write man pages properly.

Could someone tell me the exact procedure people use to create a man page?
I am in the progress of finishing of a number of tools, and people have
requested man pages to be written for them, so I'd like one in the staff to
get going. I understand that nroff/troff is involved, but what are they
written in to start with? Some form of TeX or?

Any help greatly appreciated. Or just a pointer to more info on the web,
howto or whatever would be as well.

Forgive me if this is a FAQ.

--
If you see "NOSPAM" in my e-mail address    \\|// - ?
remove it when you reply by e-mail          (o o)
========================================oOOo=(_)=oOOo=============

 Electronics engineer            IRC: Ichimusai / #Linux #AmigaSWE
 Freelance programmer                 .oooO  
 Developing using Linux OS             (  )  Oooo.
========================================\ (==(   )================
                                         \_)  ) /
                                             (_/

2. How do I write to the terminal of another process at another terminal?

3. New Howto/mini-howto/man page/rfc/irc/book site

4. RedHat 5.0 at BestBuy

5. Standard man pages to "Catted" man pages!

6. Authentication Not Responding

7. How to format BSD man pages (groff man) using "classical" troff man?

8. kernel 2.3.8 oddity

9. :howto make man use 60 lines/page instead of 66?

10. MAN Pages Howto add them..please...

11. Linux Man Page mini-HOWTO (part 1/1)

12. howto print man pages

13. Linux Man Page mini-HOWTO (part 1/1)