Re: man page

[martin@internet-treff.uni-koeln.de (Martin Bialasinski)]

>> "PF" == Philipp Frauenfelder <pfrauenf@niederglatt.lugs.ch> writes:

PF> I've got a package that has no man page. I've some spare time 
PF> and would like to write it. The question is now: how should I do 
PF> that? What tools do you recommend? Where should I start reading 
PF> about these tools?

First of all, I would contact the upstream author and tell him about
your intentions. He modt likely will include the page upstream.

I recomend creating a .pod document (Perl documentation format = plain 
old documentation) and convert it to a manpage with pod2man. See
perldoc perlpod for more info about it.

Here is a example from one of my packages:

=head1 NAME

update-xlogmaster - create a configurationfile for xlogmaster

=head1 SYNOPSIS

B<update-xlogmaster [-v]>

=head1 DESCRIPTION

Xlogmaster can monitor logfiles and other info. When a sysadmin 
installs a package containing a logfile, he would have to add a 
entry for this logfile to xlogmaster manually.
[...]
head1 OPTIONS

=over 4

=item -v

Verbose output, show warnings.

=back

=head1 FILES

=over 4

Entry files: 
(Earlier listed directories override those listed later.)

Entry files should be named after the logfile they
provide an entry for.

=over 4

=item F</etc/xlogmaster/entries/*>

Entry files created by the sysadmin to override the provided
files and entries created by the sysadmin.

=item F</usr/lib/xlogmaster/entries/*>

Entry files provided by other debian packages.
[...]

Then I use the following to convert the .pod file:

        pod2man --section=1 --release="`date +'%d %b %Y'`"\
         --center="Debian/GNU" --date=' '\
        debian/update-xlogmaster.pod > debian/update-xlogmaster.1

Ciao,
	Martin