html-link-fixes-20060228

Make the mentions of subcommands in the fs command introduction links to
the relevant pages, and add to README a to-do note to do this for the rest
of the introductory pages.

Fix links to man pages that contain underscores by working around a bug
in Pod::Simple.

diff --git a/doc/man-pages/README b/doc/man-pages/README
index b808f08..2dd0c4a 100644 (file)
--- a/doc/man-pages/README
+++ b/doc/man-pages/README
@@ -266,6 +266,12 @@ Known Problems
    * The aklog man page isn't in POD.  (Neither is the mpp man page, but
      I don't think we care about it and it's not currently installed.)
 
+   * In the suite introduction pages (pts, vos, etc.), each of the
+     subcommands in the initial list should be a link to the relevant
+     page in the HTML output.  This has been done for the fs intro page
+     and the same transform needs to be applied to the other pages.  See
+     the fs intro page for the details.
+
   If you notice other problems, please send them to the openafs-doc list
   even if you don't have time to fix them.  Someone else might, and we
   want to track all of the issues.

diff --git a/doc/man-pages/generate-html b/doc/man-pages/generate-html
index 79d105e..e4ccd13 100755 (executable)
--- a/doc/man-pages/generate-html
+++ b/doc/man-pages/generate-html
@@ -9,7 +9,7 @@ use Pod::Simple::Search;
 
 sub do_man_link {
     my ($self, $token) = @_;
-    my $page = $token->attr('to');
+    my $page = $token->attr ('to');
     my ($name, $section) = ($page =~ /^([^\(]+)\((\d+)\)$/);
     return unless $name;
     my @url = ('..', $section, $name);
@@ -17,7 +17,20 @@ sub do_man_link {
         . $Pod::Simple::HTML::HTML_EXTENSION;
 }
 
-sub VERSION () { '1.0' }
+# Underscore isn't allowed in man page names in Pod::Simple 3.04, so links
+# like L<fs_setacl(8)> show up as POD links.  Discover that case and dispatch
+# everything else to the standard do_pod_link implementation.
+sub do_pod_link {
+    my ($self, $token) = @_;
+    my $target = $token->attr ('to');
+    if ($target && $target =~ /^([^\s\(]+)\((\d+)\)$/) {
+        return $self->do_man_link ($token);
+    } else {
+        return $self->SUPER::do_pod_link ($token);
+    }
+}
+
+sub VERSION () { '1.1' }
 
 $Pod::Simple::HTML::Tagmap{'item-bullet'} = '<li><p>';
 $Pod::Simple::HTML::Tagmap{'/item-bullet'} = '</p></li>';

diff --git a/doc/man-pages/pod1/fs.pod b/doc/man-pages/pod1/fs.pod
index 7b315ee..6c88f5e 100644 (file)
--- a/doc/man-pages/pod1/fs.pod
+++ b/doc/man-pages/pod1/fs.pod
@@ -16,46 +16,71 @@ There are several categories of commands in the B<fs> command suite:
 =item *
 
 Commands to set and report how the Cache Manager interacts with server
-machines: B<fs checkservers>, B<fs getcellstatus>, B<fs getserverprefs>,
-B<fs listcells>, B<fs newcell>, B<fs setcell>, B<fs setserverprefs>, B<fs
-sysname>, and B<fs wscell>.
+machines:
+L<B<fs checkservers>|fs_checkservers(1)>,
+L<B<fs getcellstatus>|fs_getcellstatus(1)>,
+L<B<fs getserverprefs>|fs_getserverprefs(1)>,
+L<B<fs listcells>|fs_listcells(1)>,
+L<B<fs newcell>|fs_newcell(1)>,
+L<B<fs setcell>|fs_setcell(1)>,
+L<B<fs setserverprefs>|fs_setserverprefs(1)>,
+L<B<fs sysname>|fs_sysname(1)>,
+and L<B<fs wscell>|fs_wscell(1)>.
 
 =item *
 
-Commands to administer access control lists (ACLs): B<fs cleanacl>, B<fs
-copyacl>, B<fs listacl>, and B<fs setacl>.
+Commands to administer access control lists (ACLs):
+L<B<fs cleanacl>|fs_cleanacl(1)>,
+L<B<fs copyacl>|fs_copyacl(1)>,
+L<B<fs listacl>|fs_listacl(1)>,
+and L<B<fs setacl>|fs_setacl(1)>.
 
 =item *
 
 Commands to administer server machines, volumes or partitions that house a
-given file or directory: B<fs diskfree>, B<fs examine>, B<fs listquota>,
-B<fs quota>, B<fs setquota>, B<fs setvol>, B<fs whereis>, and B<fs
-whichcell>.
+given file or directory:
+L<B<fs diskfree>|fs_diskfree(1)>,
+L<B<fs examine>|fs_examine(1)>,
+L<B<fs listquota>|fs_listquota(1)>,
+L<B<fs quota>|fs_quota(1)>,
+L<B<fs setquota>|fs_setquota(1)>,
+L<B<fs setvol>|fs_setvol(1)>,
+L<B<fs whereis>|fs_whereis(1)>,
+and L<B<fs whichcell>|fs_whichcell(1)>.
 
 =item *
 
 Commands to administer the local client cache and related information:
-B<fs checkvolumes>, B<fs flush>, B<fs flushvolume>, B<fs getcacheparms>,
-and B<fs setcachesize>.
+L<B<fs checkvolumes>|fs_checkvolumes(1)>,
+L<B<fs flush>|fs_flush(1)>,
+L<B<fs flushvolume>|fs_flushvolume(1)>,
+L<B<fs getcacheparms>|fs_getcacheparms(1)>,
+and L<B<fs setcachesize>|fs_setcachesize(1)>.
 
 =item *
 
-Commands to administer volume mount points: B<fs lsmount>, B<fs mkmount>,
-and B<fs rmmount>.
+Commands to administer volume mount points:
+L<B<fs lsmount>|fs_lsmount(1)>,
+L<B<fs mkmount>|fs_mkmount(1)>,
+and L<B<fs rmmount>|fs_rmmount(1)>.
 
 =item *
 
-Commands to control monitoring and tracing: B<fs debug>, and B<fs
-messages>.
+Commands to control monitoring and tracing:
+L<B<fs debug>|fs_debug(1)>,
+and L<B<fs messages>|fs_messages(1)>.
 
 =item *
 
 A command to administer the Cache Manager's interaction with other
-file systems: B<fs exportafs>.
+file systems:
+L<B<fs exportafs>|fs_exportafs(1)>.
 
 =item *
 
-Commands to obtain help: B<fs apropos> and B<fs help>.
+Commands to obtain help:
+L<B<fs apropos>|fs_apropos(1)>
+and L<B<fs help>|fs_help(1)>.
 
 =back