mirror of
https://git.openafs.org/openafs.git
synced 2025-01-18 06:50:12 +00:00
man-page-generation-20051220
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.
This commit is contained in:
Russ Allbery
parent
2de17470f0
commit
0b21e24d0a
@ -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";
|
||||
}
|
||||
}
|
||||
60
doc/man-pages/generate-man
Executable file
60
doc/man-pages/generate-man
Executable file
@ -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
|
||||
@ -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/&/&/g;
|
||||
s/ / /g;
|
||||
s/>/>/g;
|
||||
s/</</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;
|
||||
19
regen.sh
19
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user