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
--- /dev/null
+#!/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/&/>/g;
+ s/</</g;
+ s/>/>/g;
+ }
+ if (!$current || $section != $current) {
+ print INDEX qq(<tr><td> </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";
--- /dev/null
+/* 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; }
+}
git://git.openafs.org / openafs.git / commitdiff