Home › Tags › Linux

Manpages mit pod2man

Tue, 06/24/2008 — rdoering

Im Ubuntu Packaging Guide bin ich auf eine verblüffende Möglichkeit gestossen, recht einfach Manpages zu "zaubern", die mir so noch gar nicht bewusst war: POD - das "Plain Old Documentation Format" von perl. Zwar habe ich schon Perlskripte mit enthaltener Dokumentation im POD Format verfasst, bin aber bisher noch nicht auf die Idee gekommen, damit nur Dokumentation ohne Perlskript zu schreiben. Im oben angeführten Packagingguide findet sich folgendes Template für eine Manpage im POD-Format:

=head1 NAME
 
Command - Short one-line description.
 
=head1 SYNOPSIS
 
command [options...]
 
=head1 DESCRIPTION
 
Command is a foo that does bar.
 
=head1 OPTIONS
 
=over 8
 
=item B<--key=I<value>>
 
Uses the given value as key.
 
=item B<--moo>
 
Shows an easter egg (don't explain this in real man pages ;)).
 
=item B<--stupid-example>
 
Doesn't do anything.
 
=item B<--version>
 
Displays information about the currently installed version and exists.
 
=head1 BUGS
 
This command has absolutely no bugs, as I have written it. Also, as it has no bugs, there is no need for a bug tracker.
 
=head1 AUTHORS
 
B<command> was written by Joe Hacker <joe.hacker@example.com> and John Dough <guy1268@example.net>. This manual page was written by Cool Packager <myself@example.com>.
 
Both are released under the GNU General Public License, version 3 or later.
 
=cut

Einfach aber wirkungsvoll. Näheres zu den verwendbaren Formatierungsmöglichkeiten im Text findet man in der Manpage zu perlpod.

Aus der POD-Datei muss dann noch ein Manpage generiert werden. Tool der Wahl ist hier pod2man. Falls obiges Template in der Datei template.pod gespeichert ist, kann man mittels

pod2man --section=1 --center="Template for a manpage" --release=0.1 template.pod > template.1

daraus eine manpage für die Sektion 1 generieren.

Ohne diese manpage jetzt bereits in das entsprechende /usr/share/man kopieren zu müssen, kann man sich das Ergebnis über folgendes Kommando in einem Terminal ansehen:

nroff -mandoc template.1 | less

Wer das einmal macht, erhält für das Template folgendes Ergebnis:

TEMPLATE(1)                  Template fo a manpage                 TEMPLATE(1)
 
 
 
NAME
       Command - Short one-line description.
 
SYNOPSIS
       command [options...]
 
DESCRIPTION
       Command is a foo that does bar.
 
OPTIONS
       --key=value
               Uses the given value as key.
 
       --moo   Shows an easter egg (don't explain this in real man pages ;)).
 
       --stupid-example
               Doesn't do anything.
 
       --version
               Displays information about the currently installed version and
               exists.
 
BUGS
       This command has absolutely no bugs, as I have written it. Also, as it
       has no bugs, there is no need for a bug tracker.
 
AUTHORS
       command was written by Joe Hacker <joe.hacker@example.com> and John
       Dough <guy1268@example.net>. This manual page was written by Cool Pack-
       ager <myself@example.com>.
 
       Both are released under the GNU General Public License, version 3 or
       later.
 
 
 
0.1                               2008-06-24                       TEMPLATE(1)

Bei Betrachtung dieses Ergbenisses werden auf die benutzten Kommandozeilenparameter für pod2man verständlich:

  • --center="Template for a manpage": dieser Text erscheint in der Mitte der Kopfzeile.
  • --section=1: Die Manpage gehört zu Section 1
  • --release=0.1: Die Versionsnummer der Software. Diese erscheint in der Fusszeile der Manpage

Trackback URL for this post:

http://www.rdoering.net/trackback/17