Tutorial for writing man pages??

Tutorial for writing man pages??

Post by Andrew Muell » Sat, 11 Aug 2001 08:55:40



Does anyone have a *GOOD* tutorial/document on
writing man pages? I've gone through the man page
for me (section 5), but it's not telling me anything
I haven't gotten from vi-ing source files under
/usr/share/man/man1/

While man isn't xml, I'd like to "tidy-up" the man
pages I do write to make them look better.

-Andrew Mueller
http://synecdoche.net/~andy

 
 
 

Tutorial for writing man pages??

Post by Brian Reynol » Sat, 11 Aug 2001 10:23:35




>Does anyone have a *GOOD* tutorial/document on
>writing man pages? I've gone through the man page
>for me (section 5), but it's not telling me anything
>I haven't gotten from vi-ing source files under
>/usr/share/man/man1/

You should read the man page for man(5), not me(5).  The me macros are
used for writing papers. The man macros are used for manual pages.
The man(5) page includes all the macros used in a man page and has a
listing of the section layout of a man page with descriptions of each
section.  Note that if you look at a Berkeley derived system this
pages are in section 7.

Kernhigan and Pike's book "The UNIX Programming Environment" has a
chapter on using [tn]roff and includes an example man page for the hoc
calculator program that is used as an example through out the book.

--
Brian Reynolds                  | "Dee Dee!  Don't touch that button!"

http://www.panix.com/~reynolds  |    -- Dexter and Dee Dee
NAR# 54438                      |       "Dexter's Laboratory"

 
 
 

Tutorial for writing man pages??

Post by Floyd Davidso » Sat, 11 Aug 2001 10:57:28



>Does anyone have a *GOOD* tutorial/document on
>writing man pages? I've gone through the man page
>for me (section 5), but it's not telling me anything
>I haven't gotten from vi-ing source files under
>/usr/share/man/man1/

>While man isn't xml, I'd like to "tidy-up" the man
>pages I do write to make them look better.

I've never seen even a mediocre tutorial on writing man pages!
I certainly think that poking around in various man page sources
is a very useful way to find new tricks.

But it also depends on what you mean by "tidy-up" too.  

For example, I like to view man pages (that I'm writing) in
several different ways to make sure they are readable.  Running
man on it, using both an 80x24 terminal and with at least a
128x30 terminal is the most obvious comparison.  But I also like
to generate a PostScript printout and maybe an HPCL printout
too.  Then the trick of course is figuring out how to manipulate
the source code to get each to look the best possible without
making one or another turn out ugly.  Taking advantage of troff
capabilities which can make the PostScript printout very nice
can be tricky but well worth the effort.  Tables for example,
might require two entirely different set of code to format,
one for viewing with constant width fonts and one for viewing
with proportional fonts.

On the other hand, if "tidy-up" means how to organize (as
opposed to formating or typesetting)... I suppose once again
reading a lot of man pages (not the source code though) would be
helpful.

--
Floyd L. Davidson         <http://www.ptialaska.net/~floyd>

 
 
 

Tutorial for writing man pages??

Post by Jan Schauma » Sat, 11 Aug 2001 12:22:06



>  Does anyone have a *GOOD* tutorial/document on
>  writing man pages? I've gone through the man page
>  for me (section 5), but it's not telling me anything
>  I haven't gotten from vi-ing source files under
>  /usr/share/man/man1/

In general, the more you write them, the better you get (or at least so I
hope ;-)

Some helpful information:

man(7)
http://www.linuxdoc.org/HOWTO/mini/Man-Page.html
http://mvertes.free.fr/txt2man

As it so happens, I just started a new project called "The Missing Man
Pages Project", which aims to provide the programs which are lacking a
man-page with one.  You can check it out at
http://www.netmeister.org/misc/m2p2/index.html

If you know of any programs that are lacking a man-page, please report
them at http://www.netmeister.org/misc/m2p2/missing.html

-Jan

P.S.: fup2 cup, since not solaris specific

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

In the beginning the Universe was created.  This has made a lot
of people very angry and been widely regarded as a bad move.

 
 
 

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

To Anyone Interested:

        How does one take a standard "troff"ed (?) man page that comes
with a package off the net (ending in .1, .2, etc) and turn in into a
compressed, "cat"ted man page (ending in .1.Z, .2.Z, etc) that are
stored in the directory /usr/man/catN (N = 1,2,3,...) that can be read
by the standard man utility that comes with the SLS distribution?  I'm
sure that this is trivial to do, and is probably written down
SOMEWHERE, but I've got only so many hours a day I can spend reading
FAQs and HOWTOs.  Thanx in advance...
--

                                Dr. Richard Procassini
                                Methods Development Group
                                Mechanical Engineering Department
                                Lawrence Livermore National Laboratory
                                Mail Stop L-122
                                P.O. Box 808
                                Livermore, CA  94551

                                (510)424-4095


2. Internal compiler error

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

4. S3 Chip 864 - Slackware 3_0

5. How do I write man pages?

6. Disconnect monitor while on

7. HOWTO on Man Page Writing ?

8. Sting Comparisons How do i find if one string contains another

9. writing man pages with linuxdoc-sgml?

10. how to write man page?

11. How to write a man page for my program?

12. how to write man pages

13. Q: Writing Man Pages