Listing 1: kshdoc

# Listing 1:
# kshdoc  - ksh function for processing online documentation
# To autoload, place in directory pointed to by FPATH
 1  function kshdoc {
 2    typeset path file base tdir;
 3    typeset fdir                                                          ##
 3    typeset -u help
 5    typeset -u show                                                       ##
 6  
 7    eval help=y "$@"
 8   
 9    typeset -x PATH=${path:-$PATH}
10   
11    whence perldoc >/dev/null || {
12      [[ -x /usr/perl5/bin/perldoc ]] && PATH=$PATH:/usr/perl5/bin
13      whence perldoc >/dev/null || {
14        print "You need to have perldoc in your PATH."
15        return 1
16      }
17    }
18   
19    : ${file:=kshdoc}                                                     ##
20                                                                          ##
21    [[ -r $file ]] || {                                                   ##
22      whence $file >/dev/null && file=$(whence $file)                     ##
23      [[ -r $file ]] || {                                                 ##
24        for fdir in $(IFS=:; print $FPATH); do                            ##
25          [[ -r $fdir/$file ]] && { file="$fdir/$file"; break; }          ##
26        done                                                              ##
27        [[ -r $file ]] || {                                               ##
28          print "There is no POD to process. Use file=... option."        ##
29          return 2                                                        ##
30        }                                                                 ##
31      }                                                                   ##
32    }                                                                     ##
33                                                                          ##
35    [[ $show = "Y" ]] && help="N"                                         ##
36  
37    [[ $help = @(Y|PS|PDF) ]] && {
38      base=${file##*/}; base=${base%.@(ksh|sh|ss)}
39      tdir=/tmp/$base.$$.$RANDOM
40      mkdir $tdir && trap "rm -rf $tdir" EXIT
41      sed -n '/^## =/,${/^##/s/^## \{0,1\}//p;}' $file > $tdir/$base.pod
42      case $help in
43        Y)   perldoc $tdir/$base.pod;;
44        PS)  pod2man $tdir/$base.pod | groff -man > $base.ps;;
45        PDF) pod2man $tdir/$base.pod | groff -man | ps2pdf - $base.pdf;;
46      esac
47    }
48  
49    [[ $show = Y ]] && {                                                  ##
50      [[ -r $file ]] && sed -n "/^function kshdoc/,/^}/{/##$/d;p;}" $file ##
51    }                                                                     ##
52                                                                          ##
53    return 0
54  }
## =head1 NAME
##
## B<kshdoc> - ksh function for processing online documentation
##
## =head1 SYNOPSIS
##
## [FPATH=/path/to/kshdoc]
##
## B<kshdoc> I<help=y|ps|pdf>|I<show=y> [I<file=...>] [I<path=...>]
##
## =head1 DESCRIPTION
##
## Generally, large programs possess big documentation - with books, 
## technical papers, and separate MAN pages.  Examples include Solaris, 
## Oracle, Perl, ksh, etc.   However, the shell scripts that we write 
## every day to solve specific problems usually aren't that big, and  
## it's overhead to maintain separate documentation.  In addition, 
## shell programmers and administrators are notorious for not 
## providing documentation.  
##
## Perl programmers conveniently embed documentation in Perl scripts 
## using the POD format, plain old documentation.  The kshdoc function 
## uses the perldoc utility to print POD formatted documentation.  

