Listing 1 kshdoc
# 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 ##
4 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.
|
