Scheduled Maintenance: We are aware of an issue with Google, AOL, and Yahoo services as email providers which are blocking new registrations. We are trying to fix the issue and we have several internal and external support tickets in process to resolve the issue. Please see: viewtopic.php?t=158230

 

 

 

HOWTO: Make manpages for scripts, the easy way

Share your HowTo, Documentation, Tips and Tricks. Not for support questions!.
Post Reply
Message
Author
tongro
Posts: 66
Joined: 2005-09-11 13:27
Location: Ireland

HOWTO: Make manpages for scripts, the easy way

#1 Post by tongro »

If you're like me, you have a big collection of scripts for all sorts of jobs, and scripts need to be documented. The handiest way to do that is to embed the documentation in the scripts, and if it can be done using a simple markup language that can be easily read by both humans and machines, even better. I find POD (Plain Old Documentation, http://perldoc.perl.org/perlpod.html ) perfect for that. POD is the native documentation markup for Perl, but it can just as easily be used for other languages, basically any language supporting multi-line comments or "here documents" (multi-line strings). I use it for both Perl and Bash scripts, and can easily convert it into manpages so that the documentation can be quickly consulted in a friendly way. Below is the manpage conversion script - note the embedded POD. I hope somebody here finds it useful.

Code: Select all

#!/bin/bash
:<<=cut

=head1 NAME

mkman - make and install a manpage from a file containing POD

=head1 SYNOPSIS

B<mkman> [I<section>] I<file>

=head1 DESCRIPTION

The input file should not bear the same name as another existing manpage in
the same section.

The section number defaults to 1, but if supplied should be in the range 1
to 9 (see "man man" for details).

Should be run with the appropriate permissions for writing to
/usr/local/share/man and its subdirectories.

=cut
###########################################################################

SECTION=1
PROGFILE="$1"
test -n "$2" && { SECTION="$1"; PROGFILE="$2"; }
test -z "$3" || { echo Too many arguments! >2; exit 1; }
test -f "$PROGFILE" || { echo File not found! >2; exit 1; }
grep -q '^[1-9]$' <<<"$SECTION" \
  || { echo Invalid section number! >2; exit 1; }
grep -q '^=cut\s*$' "$PROGFILE" \
  || { echo File does not contain a POD cut! >2; exit 1; }
MANDIR=/usr/local/share/man/man$SECTION
mkdir -p $MANDIR
MANFILE="$MANDIR/$(basename $PROGFILE).$SECTION"
pod2man \
  -c "$(realpath $PROGFILE)" -r "Generated by mkman" -s $SECTION \
  "$PROGFILE" "$MANFILE"
gzip -f "$MANFILE"
Hooked on Debian since 2005

Post Reply