man-page-html-20060124
authorRuss Allbery <rra@stanford.edu>
Wed, 25 Jan 2006 05:59:38 +0000 (05:59 +0000)
committerRuss Allbery <rra@stanford.edu>
Wed, 25 Jan 2006 05:59:38 +0000 (05:59 +0000)
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
doc/man-pages/Makefile.in
doc/man-pages/README
doc/man-pages/generate-html [new file with mode: 0755]
doc/man-pages/pod1/afs.pod
doc/man-pages/style.css [new file with mode: 0644]

index 549f645..ededa50 100644 (file)
@@ -1,4 +1,5 @@
 Makefile
+html
 install-man
 man1
 man5
index d2ce5bb..888e5c5 100644 (file)
@@ -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
index 799e42e..b808f08 100644 (file)
@@ -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 (executable)
index 0000000..79d105e
--- /dev/null
@@ -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'} = '<li><p>';
+$Pod::Simple::HTML::Tagmap{'/item-bullet'} = '</p></li>';
+$Pod::Simple::HTML::Tagmap{'item-number'} = '<li><p>';
+$Pod::Simple::HTML::Tagmap{'/item-number'} = '</p></li>';
+
+package main;
+
+use strict;
+
+use File::Copy;
+use Pod::Simple::HTMLBatch;
+
+our $HEADER = <<'EOH';
+<html>
+<head>
+  <title>OpenAFS Reference Manual</title>
+  <link rel="stylesheet" title="style" type="text/css" href="style.css" media="all">
+</head>
+<body class='contentspage'>
+<h1>OpenAFS Reference Manual</h1>
+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 (<F>) {
+                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 "<table>\n";
+my @index = scan_names;
+my $current;
+for my $entry (@index) {
+    my ($section, $name, $page, $desc) = @$entry;
+    for ($name, $desc) {
+        s/&/&gt;/g;
+        s/</&lt;/g;
+        s/>/&gt;/g;
+    }
+    if (!$current || $section != $current) {
+        print INDEX qq(<tr><td>&nbsp;</td></tr>\n);
+        print INDEX qq(<tr class="heading"><th colspan="2">);
+        print INDEX qq($HEADINGS{$section}</th></tr>\n);
+        $current = $section;
+    }
+    print INDEX qq(<tr><td><a href="$section/$page.html">$name</a></td>);
+    print INDEX qq(<td>$desc</td></tr>\n);
+}
+print INDEX "</table>\n</body>\n</html>\n";
index 609f9d9..a380197 100644 (file)
@@ -504,8 +504,6 @@ privilege. See the reference page for each command.
 
 =head1 SEE ALSO
 
-=over 4
-
 L<afsd(8)>,
 L<afsmonitor(1)>,
 L<backup(8)>,
@@ -552,8 +550,6 @@ L<xfs_size_check(8)>,
 L<xstat_cm_test(8)>,
 L<xstat_fs_test(8)>
 
-=back
-
 =head1 COPYRIGHT
 
 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
diff --git a/doc/man-pages/style.css b/doc/man-pages/style.css
new file mode 100644 (file)
index 0000000..b156e14
--- /dev/null
@@ -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; }
+}