man-page-generation-20051220
authorRuss Allbery <rra@stanford.edu>
Wed, 21 Dec 2005 00:37:16 +0000 (00:37 +0000)
committerRuss Allbery <rra@stanford.edu>
Wed, 21 Dec 2005 00:37:16 +0000 (00:37 +0000)
Move man page generation out into a separate script that's just invoked
from regen.sh, so that someone can run that separate script later if they
wish.  Make that script more robust against problems such as empty podN
directories.  Diagnose a missing pod2man and warn about old versions of
Pod::Man.

Also, remove the old programs used to do the initial conversion from HTML.
Enough post-conversion editing was done that they're no longer necessary
except for historical curiosity, and for that purpose they can be pulled
out of CVS.

doc/man-pages/generate-file-map [deleted file]
doc/man-pages/generate-man [new file with mode: 0755]
doc/man-pages/generate-pod [deleted file]
regen.sh

diff --git a/doc/man-pages/generate-file-map b/doc/man-pages/generate-file-map
deleted file mode 100755 (executable)
index 8428c07..0000000
+++ /dev/null
@@ -1,38 +0,0 @@
-#!/usr/bin/perl
-#
-# From an AFS Administrative Reference HTML page, try to figure out what
-# command or file it corresponds to and output the appropriate generate-pod
-# command.  Intended to be run as follows:
-#
-#     generate-file-map *.htm > generate-pods.sh
-#
-# Each line of the output will be a generate-pod invocation, saving its output
-# to the appropriate POD file.
-
-my %except = map { $_ => 1 }
-    ('Table of Contents', 'Audience and Purpose', 'Organization',
-     'How to Use This Document', 'Related Documents',
-     'Typographical Conventions');
-
-for my $file (@ARGV) {
-    my $command;
-    open (IN, '<', $file) or die "$0: cannot open $file: $!\n";
-    while (<IN>) {
-        s/<I>//g;
-        s%</I>%%g;
-        if (/<H2><A [^>]+>([^<]+)/) {
-            $command = $1;
-            last;
-        }
-    }
-    if ($command) {
-        next if $except{$command};
-        next if $command =~ /\(AFS version\)/;
-        $command =~ s/,.*//;
-        $command =~ s/ and.*//;
-        $command =~ s/\s/_/g;
-        $command =~ s/([\(\)])/\\$1/g;
-        print "../../man-pages/generate-pod $file >"
-            ." ../../man-pages/pod/$command.pod\n";
-    }
-}
diff --git a/doc/man-pages/generate-man b/doc/man-pages/generate-man
new file mode 100755 (executable)
index 0000000..8e4fc4b
--- /dev/null
@@ -0,0 +1,60 @@
+#!/bin/sh
+#
+# Generate the OpenAFS man pages from POD source.  This script is normally
+# invoked by regen.sh but may be run at any time to rebuild all of the man
+# pages (with a newer version of pod2man than was used for the release, for
+# instance).
+
+# Exit on any error.
+set -e
+
+if [ ! -d pod1 ] ; then
+    echo 'generate-man must be run from the doc/man-pages directory' >&2
+    exit 1
+fi
+
+if ! pod2man pod1/afs.pod > /dev/null ; then
+    echo 'pod2man not found, skipping man page generation' >&2
+    exit 1
+fi
+if ! perl -e 'use Pod::Man 2.04' > /dev/null 2>&1 ; then
+    echo 'Pod::Man is older than the recommended version of 2.04 or later' >&2
+    echo 'Continuing with man page generation anyway' >&2
+fi
+
+# Create the directories.  We generate each section into its own directory
+# to make installation rules easier.
+[ -d man1 ] || mkdir man1
+[ -d man5 ] || mkdir man5
+[ -d man8 ] || mkdir man8
+
+# Generate each set of man pages.  For each, allow for the case of the
+# directory being empty.  In that case, for won't expand the wildcard, and
+# we want to avoid running pod2man with a wildcard as an argument.
+pod1=`ls pod1`
+if [ -n "$pod1" ] ; then
+    cd pod1
+    for f in *.pod ; do
+        pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 "$f" \
+            > ../man1/`echo "$f" | sed 's/\.pod$//'`.1
+    done
+    cd ..
+fi
+pod5=`ls pod5`
+if [ -n "$pod5" ] ; then
+    cd pod5
+    for f in *.pod ; do
+        pod2man -c 'AFS File Reference' -r 'OpenAFS' -s 5 "$f" \
+            > ../man5/`echo "$f" | sed 's/\.pod$//'`.5
+    done
+    cd ..
+fi
+pod8=`ls pod8`
+if [ -n "$pod8" ] ; then
+    cd pod8
+    for f in *.pod ; do
+        pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 "$f" \
+            > ../man8/`echo "$f" | sed 's/\.pod$//'`.8
+    done
+    cd ..
+fi
diff --git a/doc/man-pages/generate-pod b/doc/man-pages/generate-pod
deleted file mode 100755 (executable)
index 0a4f015..0000000
+++ /dev/null
@@ -1,186 +0,0 @@
-#!/usr/bin/perl -w
-#
-# Convert the HTML pages of the Administrator's Reference into POD man pages.
-# This script was written by Chas Williams and Russ Allbery, based on work by
-# Alf Wachsmann and Elizabeth Cassell.  It just does a first pass; it's
-# expected that the results will require further hand-editing.
-
-use strict;
-use HTML::Parser ();
-
-my @ignore_tags = qw(meta head comment html body);
-my @ignore_elements = qw(script style);
-
-my %INLINES = ('b'    => 'B<',
-               '/b'   => '>',
-               'i'    => 'I<',
-               '/i'   => '>',
-               'var'  => 'I<',
-               '/var' => '>',
-               'tt'   => 'C<',
-               '/tt'  => '>',
-               'a'    => 'L<',
-               '/a'   => '(1)>',
-               'sup'  => '',
-               '/sup' => '');
-
-my %CDATA = ('dd'     => 1,
-             'dt'     => 1,
-             'h2'     => 1,
-             'a'      => 1,
-             'li'     => 1,
-             'p'      => 1,
-             'pre'    => 1,
-             'strong' => 1);
-
-# Global state of the conversion.
-my $command = "";
-my $output = 0;
-my $emit = 0;
-my $pre = 0;
-my $buffer = "";
-my $inpara = 0;
-my $lasttag = "";
-my $open = "";
-my $cdata = "";
-my $result = "";
-
-# Output some data.  Accumulate this into $results so that we can do some
-# post-filtering at the end.
-sub output {
-    my ($format, @args) = @_;
-    $result .= sprintf($format, @args);
-}
-
-# Handle a single element.
-sub element {
-    if ($output) {
-        $buffer =~ s/^\s+\n/\n/m;
-        $buffer =~ s/\n+$/\n/g;
-
-        if ($lasttag eq "h2") {
-            $command = $buffer;
-            $command =~ s/^L<//;
-            $command =~ s/\(1\)>$//;
-        } elsif ($lasttag eq "strong") {
-            if ($buffer eq 'Related Information') {
-                $buffer = 'SEE ALSO';
-            } else {
-                $buffer = uc $buffer;
-            }
-            if ($buffer eq 'PURPOSE') {
-                output "=head1 NAME\n\n%s - ", $command;
-            } else {
-                output "=head1 %s\n\n", $buffer;
-            }
-        } elsif ($lasttag eq "h5") {
-            output "=head2 %s\n\n", $buffer;
-        } elsif ($lasttag eq "h6") {
-            output "=head3 %s\n\n", $buffer;
-        } elsif ($lasttag eq "p") {
-            $buffer =~ s/\n+$//g;
-            output "%s\n\n", $buffer if $buffer ne "";
-        } elsif ($lasttag eq "pre") {
-            $buffer =~ s/\n+$//;
-            output "%s\n\n", $buffer if $buffer ne "";
-        } elsif ($lasttag eq "ul" || $lasttag eq "dl") {
-            output "=over 4\n\n";
-        } elsif ($lasttag eq "li") {
-            output "=item *\n\n%s\n\n", $buffer;
-        } elsif ($lasttag eq "dt") {
-            output "=item %s\n\n", $buffer;
-        } elsif ($lasttag eq "dd") {
-            output "%s\n", $buffer;
-        } elsif ($lasttag eq "/ul" || $lasttag eq "/dl") {
-            output "=back\n\n";
-        } else {
-            if ($buffer ne "") {
-                printf ">>>%s:%s<<<", $lasttag, $buffer;
-            }
-        }
-    }
-    $buffer = "";
-}
-
-# Handle a single tag.
-sub tag {
-    my $self = shift;
-    local $_ = shift;
-    my $tag = shift;
-    my $attr = shift;
-
-    $output = 1 if ($tag eq "h2");
-    $output = 0 if ($tag eq "hr");
-
-    if (defined $INLINES{$tag}) {
-        if (defined $open && $open eq $tag) {
-            printf STDERR "duplicate tag <%s>\n", $tag;
-            return;
-        }
-        if ($tag =~ /^\//) {
-            undef $open;
-        } else {
-            $open = $tag;
-        }
-
-        &text(sprintf "%s", $INLINES{$tag});
-        return;
-    }
-
-    $cdata = 0;
-    $cdata = 1 if defined $CDATA{$tag};
-
-    &element;
-    $lasttag = $tag;
-}
-
-# Do text conversion, mostly undoing SGML escapes.
-sub text {
-    local $_ = shift;
-
-    if ($cdata) {
-        s/&amp;/&/g;
-        s/&nbsp;/ /g;
-        s/&gt;/>/g;
-        s/&lt;/</g;
-
-        s/\n$//g if defined $open;     # in inline seq, remove \n
-        s/L<(\S+) (\S+\(1\))>/L<${1}_${2}>/g;
-        $buffer = $buffer . $_;
-    }
-}
-
-my $file = shift @ARGV;
-
-my $p = HTML::Parser->new(api_version     => 3,
-                         start_h         => [\&tag, "self, text, tag, attr"],
-                         end_h           => [\&tag, "self, text, tag, attr"],
-                         process_h       => ["", ""],
-                         comment_h       => ["", ""],
-                         declaration_h   => ["", ""],
-                         default_h       => [\&text, "text"],
-
-                         ignore_tags     => \@ignore_tags,
-                         ignore_elements => \@ignore_elements,
-                         unbroken_text   => 1);
-
-$p->parse_file($file) || die "Can't open file: $!\n";
-
-# Fix up a few last things.
-$result =~ s/L<(\S+) (\S+\(1\))>/L<${1}_${2}>/g;
-$result =~ s/^(L<[^>]+>)\n\n(?=L<)/$1,\n/mg;
-$result =~ s/^(\s+.*)B<([^>]+)>/$1$2/mg;
-
-# Append a stock copyright statement.
-$result .= <<'EOC';
-=head1 COPYRIGHT
-
-IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-
-This documentation is covered by the IBM Public License Version 1.0.  It was
-converted from HTML to POD by software written by Chas Williams and Russ
-Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
-EOC
-
-# Output the results.
-print $result;
index f232c6c..bc05925 100755 (executable)
--- a/regen.sh
+++ b/regen.sh
@@ -14,21 +14,6 @@ autoheader
 # Rebuild the man pages, to not require those building from source to have
 # pod2man available.
 echo "Building man pages"
-if test -d doc ; then
-    mkdir -p doc/man-pages/man1 doc/man-pages/man5 doc/man-pages/man8
-    for f in doc/man-pages/pod1/*.pod ; do
-        pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 \
-            -n `basename "$f" | sed 's/\.pod$//'` "$f" \
-            > `echo "$f" | sed -e 's%pod1/%man1/%' -e 's/\.pod$/.1/'`
-    done
-    for f in doc/man-pages/pod5/*.pod ; do
-        pod2man -c 'AFS File Reference' -r 'OpenAFS' -s 5 \
-            -n `basename "$f" | sed 's/\.pod$//'` "$f" \
-            > `echo "$f" | sed -e 's%pod5/%man5/%' -e 's/\.pod$/.5/'`
-    done
-    for f in doc/man-pages/pod8/*.pod ; do
-        pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 \
-            -n `basename "$f" | sed 's/\.pod$//'` "$f" \
-            > `echo "$f" | sed -e 's%pod8/%man8/%' -e 's/\.pod$/.8/'`
-    done
+if test -d doc/man-pages ; then
+    (cd doc/man-pages && ./generate-man)
 fi