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
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.
#!/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"