From 6eb9f473add1426b52861574c841b1fdfd80367b Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Wed, 25 Jan 2006 05:59:38 +0000 Subject: [PATCH] man-page-html-20060124 Initial cut at an HTML conversion of the POD reference pages. Requires Pod::Simple be installed (version 3.0 or later, probably). Also fix a POD formatting bug in the afs(1) man page noticed while testing HTML output. --- doc/man-pages/.cvsignore | 1 + doc/man-pages/Makefile.in | 5 +- doc/man-pages/README | 12 +++-- doc/man-pages/generate-html | 119 ++++++++++++++++++++++++++++++++++++++++++++ doc/man-pages/pod1/afs.pod | 4 -- doc/man-pages/style.css | 79 +++++++++++++++++++++++++++++ 6 files changed, 211 insertions(+), 9 deletions(-) create mode 100755 doc/man-pages/generate-html create mode 100644 doc/man-pages/style.css diff --git a/doc/man-pages/.cvsignore b/doc/man-pages/.cvsignore index 549f645..ededa50 100644 --- a/doc/man-pages/.cvsignore +++ b/doc/man-pages/.cvsignore @@ -1,4 +1,5 @@ Makefile +html install-man man1 man5 diff --git a/doc/man-pages/Makefile.in b/doc/man-pages/Makefile.in index d2ce5bb..888e5c5 100644 --- a/doc/man-pages/Makefile.in +++ b/doc/man-pages/Makefile.in @@ -6,7 +6,10 @@ include @TOP_OBJDIR@/src/config/Makefile.config all: maintclean: - rm -rf man1 man5 man8 + rm -rf html man1 man5 man8 + +html: + perl generate-html dest: chmod +x install-man diff --git a/doc/man-pages/README b/doc/man-pages/README index 799e42e..b808f08 100644 --- a/doc/man-pages/README +++ b/doc/man-pages/README @@ -61,10 +61,14 @@ POD and Man Page Generation OpenAFS source tree (this will also regenerate the Autoconf scripts). Conversion to HTML can be done via any of the POD to HTML converters - available (there are many of them). Evaluation of the best tool to use - for OpenAFS and exactly how to do the conversion to get the highest - quality results is still underway; when complete, details will be - included here. + available (there are many of them), but for best results (particularly + for crosslinks), use the generate-html script in this directory. You + will need to have the Pod::Simple Perl module installed. If your Perl + is not in /usr/bin, run generate-html explicitly with: + + perl generate-html + + It will generate HTML pages in the html subdirectory of this directory. Formatting Standards diff --git a/doc/man-pages/generate-html b/doc/man-pages/generate-html new file mode 100755 index 0000000..79d105e --- /dev/null +++ b/doc/man-pages/generate-html @@ -0,0 +1,119 @@ +#!/usr/bin/perl -w +package OpenAFS::HTML; + +use strict; +use vars qw(@ISA); + +use Pod::Simple::Search; +@ISA = qw(Pod::Simple::HTML); + +sub do_man_link { + my ($self, $token) = @_; + my $page = $token->attr('to'); + my ($name, $section) = ($page =~ /^([^$]+)\((\d+)$$/); + return unless $name; + my @url = ('..', $section, $name); + return join ('/', map { $self->pagepath_url_escape ($_) } @url) + . $Pod::Simple::HTML::HTML_EXTENSION; +} + +sub VERSION () { '1.0' } + +$Pod::Simple::HTML::Tagmap{'item-bullet'} = '

'; +$Pod::Simple::HTML::Tagmap{'/item-bullet'} = '

'; +$Pod::Simple::HTML::Tagmap{'item-number'} = '

'; +$Pod::Simple::HTML::Tagmap{'/item-number'} = '

'; + +package main; + +use strict; + +use File::Copy; +use Pod::Simple::HTMLBatch; + +our $HEADER = <<'EOH'; + + + OpenAFS Reference Manual + + + +

OpenAFS Reference Manual

+EOH + +our %HEADINGS = (1 => 'User Commands', + 5 => 'Configuration and Data Files', + 8 => 'Administrator Commands'); + +# Scan all of the POD files and build a list of section, name, and short +# description, returning that as an array. +sub scan_names { + my @index; + for my $dir (qw(pod1 pod5 pod8)) { + my $section = $dir; + $section =~ s/^pod//; + opendir (D, $dir) or die "Cannot open $dir: $!\n"; + for my $file (sort grep { !/^\./ && !/CVS/ } readdir D) { + open (F, "$dir/$file") or die "Cannot open $dir/$file: $!\n"; + my ($name, $desc); + local $_; + while () { + last if /^=head1/ && !/^=head1\s+NAME\b/; + next unless /\s+-\s+/; + ($name, $desc) = split (/\s+-\s+/, $_, 2); + } + unless ($name) { + warn "$dir/$file: cannot find NAME section, skipping\n"; + } + my $page = $file; + $page =~ s/\.pod$//; + push (@index, [ $section, $name, $page, $desc ]); + } + closedir D; + } + return @index; +} + +unless (-d 'html') { + mkdir ('html', 0755) or die "Cannot create html directory: $!\n"; +} +for my $dir (qw(pod1 pod5 pod8)) { + my $section = $dir; + $section =~ s/^pod//; + mkdir ("html/$section", 0755) unless -d "html/$section"; + + my $conv = Pod::Simple::HTMLBatch->new; + $conv->verbose (0); + $conv->index (undef); + $conv->contents_file (undef); + $conv->add_css ('../style.css', 1); + $conv->css_flurry (0); + $conv->javascript_flurry (0); + $conv->html_render_class ('OpenAFS::HTML'); + $conv->batch_convert ($dir, "html/$section"); +} +copy ('style.css', 'html/style.css') or die "Cannot copy style.css: $!\n"; + +open (INDEX, '> html/index.html') + or die "Cannot create html/index.html: $!\n"; +print INDEX $HEADER; +print INDEX "\n"; +my @index = scan_names; +my $current; +for my $entry (@index) { + my ($section, $name, $page, $desc) = @$entry; + for ($name, $desc) { + s/&/>/g; + s//>/g; + } + if (!$current || $section != $current) { + print INDEX qq(\n); + print INDEX qq(\n); + $current = $section; + } + print INDEX qq(); + print INDEX qq(\n); +} +print INDEX "

); + print INDEX qq($HEADINGS{$section}

$name	$desc

\n\n\n"; diff --git a/doc/man-pages/pod1/afs.pod b/doc/man-pages/pod1/afs.pod index 609f9d9..a380197 100644 --- a/doc/man-pages/pod1/afs.pod +++ b/doc/man-pages/pod1/afs.pod @@ -504,8 +504,6 @@ privilege. See the reference page for each command. =head1 SEE ALSO -=over 4 - L, L, L, @@ -552,8 +550,6 @@ L, L, L -=back - =head1 COPYRIGHT IBM Corporation 2000. All Rights Reserved. diff --git a/doc/man-pages/style.css b/doc/man-pages/style.css new file mode 100644 index 0000000..b156e14 --- /dev/null +++ b/doc/man-pages/style.css @@ -0,0 +1,79 @@ +/* Style sheet for OpenAFS Reference documentation. */ +/* For accessibility reasons, never specify text sizes in px/pt/pc/in/cm/mm */ + +@media all { .hide { display: none; } } + +@media print { + .noprint, div.indexgroup, .backlinktop, .backlinkbottom { display: none } + + * { + border-color: black !important; + color: black !important; + background-color: transparent !important; + background-image: none !important; + } +} + +@media screen, tty, tv, projection { + .noscreen { display: none; } + + a:link { color: #7070ff; text-decoration: underline; } + a:visited { color: #e030ff; text-decoration: underline; } + a:active { color: #800000; text-decoration: underline; } + body.contentspage a { text-decoration: none; } + a.u { color: #000 !important; text-decoration: none; } + + body.pod { + margin: 0 5px; + color: #000; + background-color: #fff; + } + + body.pod h1 { font-size: large } + body.pod h2 { font-size: large } + + body.pod dt { + font-size: 105%; /* just a wee bit more than normal */ + } + + /* Indent the body text and lower headings. */ + body.pod p { margin-left: 2em } + body.pod dl { margin-left: 2em } + body.pod ol { margin-left: 2em } + body.pod ul { margin-left: 2em } + body.pod dl p { margin-left: 0 } + body.pod ol p { margin-left: 0 } + body.pod ul p { margin-left: 0 } + body.pod pre { margin-left: 2em } + body.pod dl pre { margin-left: 0 } + body.pod ol pre { margin-left: 0 } + body.pod ul pre { margin-left: 0 } + body.pod h2 { margin-left: 0.5em } + body.pod h3 { margin-left: 1em } + body.pod h4 { margin-left: 1em } + + body.contentspage { + color: #000; + background-color: #fff; + } + + body.contentspage h1 { + color: #22f; + margin-left: 1em; + margin-right: 1em; + text-indent: -.9em; + font-family: Tahoma, Verdana, Helvetica, Arial, sans-serif; + font-weight: normal; + border-top: medium solid #000; + border-bottom: medium solid #000; + text-align: center; + } + + body.contentspage th { + font-weight: bold; + font-size: large; + text-align: left; + } + + body.contentspage td { padding: 0 0.5em; } +} -- 1.9.4