HOWTO: Make manpages for scripts, the easy way

Share your own howto's etc. Not for support questions!

HOWTO: Make manpages for scripts, the easy way

Postby tongro » 2015-11-07 00:27

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
tongro
 
Posts: 66
Joined: 2005-09-11 13:27
Location: Ireland

Return to Docs, Howtos, Tips & Tricks

Who is online

Users browsing this forum: No registered users and 2 guests

fashionable