BBS水木清华站∶精华区

发信人: reden (鱼～君子律己以利人), 信区: Linux
标  题: Creating man pages made easy
发信站: BBS 水木清华站 (Mon Oct  5 00:03:11 1998) WWW-POST

Creating man pages made easy!!!

Date: Sun, 16 Aug 1998 16:14:34 +1000
From: Steven K.H. Siew, [email protected]

Below is something I wrote to help laypeople create their own man pages
easily.

----------------------------------------------------------------------------
----

If you ever wrote a program using gcc in Linux, you may have come across this
problem. You have just finished your wonderful
little program which is of great use to you and you need a man page for it.

Of course, you have absolutely no idea how to write a man page. Don't you
need to know how to use troff? Or is it nroff to write
a man page? Luckily, there is a much easier way to write a man page.

Here I shall describe an easy and quick (and dirty) way of writing a man page
without learning troff or nroff. In order to do so,
you must have the Perl version 5.004 (or higher) installed on your Linux box.

There is a man page in the various Perl man pages on the creation of a man
page using the Perl util "pod2man". It is called
"perlpod.1". Below is a step by step guide to finding the man page and the
util.

ksiew> su
password:

#|/root>locate perlpod.1
/usr/man/man1/perlpod.1

#|/root>locate pod2man
/usr/bin/pod2man

Now, to write your own man pages, you must first read the perlpod.1 man page.
You can do this by "man perlpod". However, to
read the pod2man man page, you must first create it by using pod2man itself.

#|/root>pod2man /usr/bin/pod2man > pod2man.1
#|/root>ls -al pod2man.1
-rw-r--r--   1 root     root        13444 Aug 16 12:12 pod2man.1
#|/root>mv pod2man.1 /usr/man/man1/pod2man.1

Okay, now you can read the pod2man man page you have just created by using
the command "man pod2man". After reading it,
you can now create your own man pages. As an example, I shall describe a
simple man page for one of my own C programs
called "addline". I first create a textfile called "addline.pod" and then
turn it into a manpage using 'pod2man --center="Addline
program manpage" addline.pod > addline.1'.

Finally, I move the addline man page into its proper place using "mv
addline.1 /usr/man/man1/addline.1". There; creating your own
man page is simple, isn't it?

Below is a sample addline.pod file

=head1 NAME

addline - addline numbers to textfiles

=head1 SYNOPSIS

B<addline>
[ B<-c> ]
[ B<-v> ]
[ B<-3> ]
[ B<--colon> ]
I<inputfile>

=head1 DESCRIPTION

B<addline> inserts line numbers into textfiles. It was written to automate
the insertion of numbers into a data file of results from a neural network
program.

=head1 OPTIONS

=over 8

=item -c

Ignores comments lines. A comment line is any line that starts with a '#'.
This makes it easier to insert comments in the textfile without messing up
the line numbers.

=item -v

Displays the version number of the addline.

=item -3

Uses 3 digits for the line numbers even if the number requires less than 3
digits. For example, 013 instead of 13. The default is to use as few
digits for the line number as possible.

=item --colon

Separates the line number from the rest of the line with a ':' character.

=back

=head1 EXAMPLES

    addline textfile
    addline -c textfile
    addline -c --colon textfile

=head1 NOTES

Addline is written in C and compiled using gcc version 2.7.8. It uses the
standard C library and is designed to be fast and efficient.

=head1 RESTRICTIONS

Never ever use addline on a binary file.

=head1 BUGS

There are no bugs in addline, there are just some undocumented features.

=head1 AUTHORS

Original prototype by Steven Siew, but so massively hacked over by
his sister such that Steven Siew probably doesn't recognize it anymore.

--
    白马带著她一步步的回到中原。白马已经老了，只能慢慢的走，
但终是能回到中原的。江南有杨柳、桃花，有燕子、金鱼……
汉人中有的是英俊勇武的少年，倜傥潇洒的少年……但这个美
丽的姑娘就像古高昌国人那样固执:

    「那都是很好很好的，可是我偏不喜欢。」

※ 来源:·BBS 水木清华站 bbs.net.tsinghua.edu.cn·[FROM: 202.99.18.67]