doc/man-pages/generate-html

   1 #!/usr/bin/perl -w
   2 package OpenAFS::HTML;
   3
   4 use strict;
   5 use vars qw(@ISA);
   6
   7 use Pod::Simple::Search;
   8 @ISA = qw(Pod::Simple::HTML);
   9
  10 # Add a link back to the index page to the top and bottom of each generated
  11 # page.
  12 #
  13 # The hideous approach we have to use is because, unless we create a
  14 # Pod::Simple::HTML object and then rebless it, the html_header_after_title
  15 # and html_footer subs are placed in the OpenAFS::HTML package.  That means we
  16 # can't override them in a subclass and still call the SUPER version since
  17 # we'll be overwriting the SUPER version, and there aren't other good
  18 # opportunities to change the default values that I can see.
  19 sub new {
  20     my $class = shift;
  21     my $self = Pod::Simple::HTML->new (@_);
  22     bless ($self, 'OpenAFS::HTML');
  23     my $link = '<p class="indexlink"><a href="../index.html">'
  24         . 'Back to Index</a></p>' . "\n";
  25     my $after = $self->html_header_after_title;
  26     $self->html_header_after_title ($after . $link);
  27     my $end = $self->html_footer;
  28     $self->html_footer ($link . $end);
  29     return $self;
  30 }
  31
  32 sub do_man_link {
  33     my ($self, $token) = @_;
  34     my $page = $token->attr ('to');
  35     my ($name, $section) = ($page =~ /^([^\(]+)\((\d+)\)$/);
  36     return unless $name;
  37     my @url = ('..', $section, $name);
  38     return join ('/', map { $self->pagepath_url_escape ($_) } @url)
  39         . $Pod::Simple::HTML::HTML_EXTENSION;
  40 }
  41
  42 # Underscore isn't allowed in man page names in Pod::Simple 3.04, so links
  43 # like L<fs_setacl(8)> show up as POD links.  Discover that case and dispatch
  44 # everything else to the standard do_pod_link implementation.
  45 sub do_pod_link {
  46     my ($self, $token) = @_;
  47     my $target = $token->attr ('to');
  48     if ($target && $target =~ /^([^\s\(]+)\((\d+)\)$/) {
  49         return $self->do_man_link ($token);
  50     } else {
  51         return $self->SUPER::do_pod_link ($token);
  52     }
  53 }
  54
  55 sub VERSION () { '1.1' }
  56
  57 $Pod::Simple::HTML::Tagmap{'item-bullet'} = '<li><p>';
  58 $Pod::Simple::HTML::Tagmap{'/item-bullet'} = '</p></li>';
  59 $Pod::Simple::HTML::Tagmap{'item-number'} = '<li><p>';
  60 $Pod::Simple::HTML::Tagmap{'/item-number'} = '</p></li>';
  61
  62 # This horrific hack is required because Pod::Simple::HTMLBatch has no way
  63 # of setting search options and we have to set laborious to true in order
  64 # to pick up man pages like krb.conf(5).
  65 package OpenAFS::Search;
  66
  67 use strict;
  68 use vars qw(@ISA);
  69
  70 use Pod::Simple::Search;
  71 @ISA = qw(Pod::Simple::HTML);
  72
  73 sub new {
  74     my $class = shift;
  75     my $object = Pod::Simple::Search->new;
  76     $object->laborious (1);
  77     return $object;
  78 }
  79
  80 package main;
  81
  82 use strict;
  83
  84 use File::Copy;
  85 use Pod::Simple::HTMLBatch;
  86
  87 # Override the search class to set laborious.
  88 $Pod::Simple::HTMLBatch::SEARCH_CLASS = 'OpenAFS::Search';
  89
  90 our $HEADER = <<'EOH';
  91 <html>
  92 <head>
  93   <title>OpenAFS Reference Manual</title>
  94   <link rel="stylesheet" title="style" type="text/css" href="style.css" media="all">
  95 </head>
  96 <body class='contentspage'>
  97 <h1>OpenAFS Reference Manual</h1>
  98 EOH
  99
 100 our %HEADINGS = (1 => 'User Commands',
 101                  5 => 'Configuration and Data Files',
 102                  8 => 'Administrator Commands');
 103
 104 # Scan all of the POD files and build a list of section, name, and short
 105 # description, returning that as an array.
 106 sub scan_names {
 107     my @index;
 108     for my $dir (qw(pod1 pod5 pod8)) {
 109         my $section = $dir;
 110         $section =~ s/^pod//;
 111         opendir (D, $dir) or die "Cannot open $dir: $!\n";
 112         for my $file (sort grep { !/^\./ && !/CVS/ } readdir D) {
 113             open (F, "$dir/$file") or die "Cannot open $dir/$file: $!\n";
 114             my ($name, $desc);
 115             local $_;
 116             while (<F>) {
 117                 last if /^=head1/ && !/^=head1\s+NAME\b/;
 118                 next unless /\s+-\s+/;
 119                 ($name, $desc) = split (/\s+-\s+/, $_, 2);
 120             }
 121             unless ($name) {
 122                 warn "$dir/$file: cannot find NAME section, skipping\n";
 123             }
 124             $name =~ s/^(backup|bos|fs|fstrace|kas|pts|symlink|uss|vos)_/$1 /;
 125             my $page = $file;
 126             $page =~ s/\.pod$//;
 127             push (@index, [ $section, $name, $page, $desc ]);
 128         }
 129         closedir D;
 130     }
 131     return @index;
 132 }
 133
 134 unless (-d 'html') {
 135     mkdir ('html', 0755) or die "Cannot create html directory: $!\n";
 136 }
 137 for my $dir (qw(pod1 pod5 pod8)) {
 138     my $section = $dir;
 139     $section =~ s/^pod//;
 140     mkdir ("html/$section", 0755) unless -d "html/$section";
 141
 142     my $conv = Pod::Simple::HTMLBatch->new;
 143     $conv->verbose (0);
 144     $conv->index (undef);
 145     $conv->contents_file (undef);
 146     $conv->add_css ('../style.css', 1);
 147     $conv->css_flurry (0);
 148     $conv->javascript_flurry (0);
 149     $conv->html_render_class ('OpenAFS::HTML');
 150     $conv->batch_convert ($dir, "html/$section");
 151 }
 152 copy ('style.css', 'html/style.css') or die "Cannot copy style.css: $!\n";
 153
 154 open (INDEX, '> html/index.html')
 155     or die "Cannot create html/index.html: $!\n";
 156 print INDEX $HEADER;
 157 print INDEX "<table>\n";
 158 my @index = scan_names;
 159 my $current;
 160 for my $entry (@index) {
 161     my ($section, $name, $page, $desc) = @$entry;
 162     for ($name, $desc) {
 163         s/&/&gt;/g;
 164         s/</&lt;/g;
 165         s/>/&gt;/g;
 166     }
 167     if (!$current || $section != $current) {
 168         print INDEX qq(<tr><td>&nbsp;</td></tr>\n);
 169         print INDEX qq(<tr class="heading"><th colspan="2">);
 170         print INDEX qq($HEADINGS{$section}</th></tr>\n);
 171         $current = $section;
 172     }
 173     print INDEX qq(<tr><td><a href="$section/$page.html">$name</a></td>);
 174     print INDEX qq(<td>$desc</td></tr>\n);
 175 }
 176 print INDEX "</table>\n</body>\n</html>\n";