doc: Add support for section 3 man pages

Generate and install man pages (and their HTML versions) for library
reference documentation in section 3.

Change-Id: I500818097c6880e0412794661393351ab14461dc
Reviewed-on: http://gerrit.openafs.org/3898
Reviewed-by: Derrick Brashear <shadow@dementia.org>
Tested-by: Derrick Brashear <shadow@dementia.org>

diff --git a/doc/man-pages/.gitignore b/doc/man-pages/.gitignore
index 03bf4c9..f3811dd 100644 (file)
--- a/doc/man-pages/.gitignore
+++ b/doc/man-pages/.gitignore
@@ -5,5 +5,6 @@
 html
 install-man
 man1
+man3
 man5
 man8

diff --git a/doc/man-pages/Makefile.in b/doc/man-pages/Makefile.in
index fe4fd3a..b66dc04 100644 (file)
--- a/doc/man-pages/Makefile.in
+++ b/doc/man-pages/Makefile.in
@@ -6,7 +6,7 @@ include @TOP_OBJDIR@/src/config/Makefile.config
 all:
 
 maintclean:
-       rm -rf html man1 man5 man8
+       rm -rf html man1 man3 man5 man8
 
 html:
        perl generate-html
@@ -15,8 +15,9 @@ LINKEDPAGES = klog pagsh tokens
 
 dest:
        chmod +x install-man
-       mkdir -p $(DEST)/man/man1 $(DEST)/man/man5 $(DEST)/man/man8
-       set -e; for M in man1/*.1 man5/*.5 man8/*.8 ; do \
+       mkdir -p $(DEST)/man/man1 $(DEST)/man/man3 \
+                $(DEST)/man/man5 $(DEST)/man/man8
+       set -e; for M in man1/*.1 man3/*.3 man5/*.5 man8/*.8 ; do \
            ./install-man $$M $(DEST)/man/$$M ; \
        done
        set -e; for M in ${LINKEDPAGES}; do \
@@ -32,9 +33,9 @@ dest:
 
 install: $(MAN1) $(MAN8)
        chmod +x install-man
-       mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man5 \
-           $(DESTDIR)$(mandir)/man8
-       set -e; for M in man1/*.1 man5/*.5 man8/*.8 ; do \
+       mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man3 \
+           $(DESTDIR)$(mandir)/man5 $(DESTDIR)$(mandir)/man8
+       set -e; for M in man1/*.1 man3/*.3 man5/*.5 man8/*.8 ; do \
            ./install-man $$M $(DESTDIR)$(mandir)/$$M ; \
        done
        set -e; for M in ${LINKEDPAGES}; do \

diff --git a/doc/man-pages/NTMakefile b/doc/man-pages/NTMakefile
index 6d13f64..7c5b2e8 100644 (file)
--- a/doc/man-pages/NTMakefile
+++ b/doc/man-pages/NTMakefile
@@ -172,6 +172,7 @@ PODS = \
         pod1\vos_zap.pod               \
         pod1\xstat_cm_test.pod         \
         pod1\xstat_fs_test.pod         \
+        pod3\AFS.ukernel.pod           \
         pod5\afs.pod                   \
         pod5\afsmonitor.pod            \
         pod5\afszcm.cat.pod            \

diff --git a/doc/man-pages/README b/doc/man-pages/README
index 8394f97..1ca8eb6 100644 (file)
--- a/doc/man-pages/README
+++ b/doc/man-pages/README
@@ -157,8 +157,8 @@ Formatting Standards
 Man Page Sections
 
   The section of a man page is determined by which directory it's in.
-  pod1 will be section 1 man pages, pod5 will be section 5, and pod8 will
-  be section 8.
+  pod1 will be section 1 man pages, pod3 will be section 3, pod5 will be
+  section 5, and pod8 will be section 8.
 
   The breakdown between section 1 and section 8 is fuzzy and it's hard to
   get right.  The current layout balances the following goals:

diff --git a/doc/man-pages/check-pod b/doc/man-pages/check-pod
index 0afaf7b..0b79e38 100755 (executable)
--- a/doc/man-pages/check-pod
+++ b/doc/man-pages/check-pod
@@ -21,7 +21,7 @@ use Test::More;
 eval "use Test::Pod 1.00";
 
 plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
-my @poddirs = qw( pod1 pod5 pod8 );
+my @poddirs = qw( pod1 pod3 pod5 pod8 );
 
 my @list;
 for ( @ARGV ? @ARGV : @poddirs ) {

diff --git a/doc/man-pages/generate-html b/doc/man-pages/generate-html
index 13fdff5..031f834 100755 (executable)
--- a/doc/man-pages/generate-html
+++ b/doc/man-pages/generate-html
@@ -105,7 +105,7 @@ our %HEADINGS = (1 => 'User Commands',
 # description, returning that as an array.
 sub scan_names {
     my @index;
-    for my $dir (qw(pod1 pod5 pod8)) {
+    for my $dir (qw(pod1 pod3 pod5 pod8)) {
         my $section = $dir;
         $section =~ s/^pod//;
         opendir (D, $dir) or die "Cannot open $dir: $!\n";
@@ -122,6 +122,9 @@ sub scan_names {
                 warn "$dir/$file: cannot find NAME section, skipping\n";
             }
             $name =~ s/^(backup|bos|fs|fstrace|kas|pts|symlink|uss|vos)_/$1 /;
+           if ($section eq '3') {
+               $name =~ s/^AFS\./AFS::/;
+           }
             if ($section eq '5') {
                 $name =~ s/_/ /g;
             }
@@ -137,7 +140,7 @@ sub scan_names {
 unless (-d 'html') {
     mkdir ('html', 0755) or die "Cannot create html directory: $!\n";
 }
-for my $dir (qw(pod1 pod5 pod8)) {
+for my $dir (qw(pod1 pod3 pod5 pod8)) {
     my $section = $dir;
     $section =~ s/^pod//;
     mkdir ("html/$section", 0755) unless -d "html/$section";

diff --git a/doc/man-pages/generate-man b/doc/man-pages/generate-man
index 1ad0e32..726e0cb 100755 (executable)
--- a/doc/man-pages/generate-man
+++ b/doc/man-pages/generate-man
@@ -29,6 +29,7 @@ fi
 # Create the directories.  We generate each section into its own directory
 # to make installation rules easier.
 [ -d man1 ] || mkdir man1
+[ -d man3 ] || mkdir man3
 [ -d man5 ] || mkdir man5
 [ -d man8 ] || mkdir man8
 
@@ -44,6 +45,18 @@ if [ -n "$pod1" ] ; then
     done
     cd ..
 fi
+pod3=`ls pod3`
+if [ -n "$pod3" ] ; then
+    cd pod3
+    for f in *.pod ; do
+        pod2man -c 'AFS Library Reference' -r 'OpenAFS' -s 3 "$f" \
+            > ../man3/`echo "$f" | sed -e 's/\.pod$//' -e 's/^AFS\./AFS::/'`.3
+       # Perl module manpages are named AFS.foo instead of AFS::foo, since
+       # we cannot have colons in filenames on Windows. So here, we assume
+       # anything with "AFS." should be "AFS::" instead.
+    done
+    cd ..
+fi
 pod5=`ls pod5`
 if [ -n "$pod5" ] ; then
     cd pod5

diff --git a/src/WINNT/install/NSIS/OpenAFS.nsi b/src/WINNT/install/NSIS/OpenAFS.nsi
index 955c067..c7d8c4e 100644 (file)
--- a/src/WINNT/install/NSIS/OpenAFS.nsi
+++ b/src/WINNT/install/NSIS/OpenAFS.nsi
@@ -1037,6 +1037,9 @@ DoEnglish:
    CreateDirectory "$INSTDIR\Documentation\html\CmdRef\1"
    SetOutPath "$INSTDIR\Documentation\html\CmdRef\1"
    File "..\..\..\..\doc\man-pages\html\1\*"
+   CreateDirectory "$INSTDIR\Documentation\html\CmdRef\3"
+   SetOutPath "$INSTDIR\Documentation\html\CmdRef\3"
+   File "..\..\..\..\doc\man-pages\html\3\*"
    CreateDirectory "$INSTDIR\Documentation\html\CmdRef\5"
    SetOutPath "$INSTDIR\Documentation\html\CmdRef\5"
    File "..\..\..\..\doc\man-pages\html\5\*"
@@ -1696,6 +1699,7 @@ StartRemove:
   Delete "$INSTDIR\Documentation\html\*"
   Delete "$INSTDIR\Documentation\html\index_files\*"
   Delete "$INSTDIR\Documentation\html\CmdRef\1\*"
+  Delete "$INSTDIR\Documentation\html\CmdRef\3\*"
   Delete "$INSTDIR\Documentation\html\CmdRef\5\*"
   Delete "$INSTDIR\Documentation\html\CmdRef\8\*"
   Delete "$INSTDIR\Documentation\html\CmdRef\*"

diff --git a/src/WINNT/install/wix/files.wxi b/src/WINNT/install/wix/files.wxi
index d1eafda..8eba97d 100644 (file)
--- a/src/WINNT/install/wix/files.wxi
+++ b/src/WINNT/install/wix/files.wxi
@@ -510,6 +510,11 @@
                             <File Id="file_CmdRef_1_xstat_fs_test_html"  Name="xstat_fs.htm"  LongName="xstat_fs_test.html"  DiskId="1"  />
                             </Component>
                         </Directory> <!-- CmdRef_1 -->
+                        <Directory Id="dirCmdRef3_en_US" Name="3" src="$(var.DocDir)\man-pages\html\3\">
+                            <Component Id="cmp_Cmd_Ref_3_en_US" Guid="$(var.DocHtmlCmdRef3Guid)">
+                            <File Id="file_CmdRef_3_AFS_ukernel_html"  Name="AFS_uker.htm"  LongName="AFS.ukernel.html"  KeyPath="yes"  DiskId="1"  />
+                            </Component>
+                        </Directory> <!-- CmdRef_3 -->
                         <Directory Id="dirCmdRef5_en_US" Name="5" src="$(var.DocDir)\man-pages\html\5\">
                             <Component Id="cmp_Cmd_Ref_5_en_US" Guid="$(var.DocHtmlCmdRef5Guid)">
                             <File Id="file_CmdRef_5_afs_html"  Name="afs.htm"  LongName="afs.html"  KeyPath="yes"  DiskId="1"  />

diff --git a/src/WINNT/install/wix/language_config.wxi b/src/WINNT/install/wix/language_config.wxi
index de2cb9b..a0d417a 100644 (file)
--- a/src/WINNT/install/wix/language_config.wxi
+++ b/src/WINNT/install/wix/language_config.wxi
@@ -62,6 +62,7 @@
     <?define DocHtmlGuid="C9595172-72DF-4F30-8C43-C16583CFB8B1"?>
     <?define DocHtmlCmdRefGuid="94168F07-82F6-442A-BE10-21EF72CB741D"?>
     <?define DocHtmlCmdRef1Guid="440BC8BA-93ED-4202-9684-D893B8A3B2E3"?>
+    <?define DocHtmlCmdRef3Guid="71F8CA2E-32D8-11E0-ADD9-098FDFD72085"?>
     <?define DocHtmlCmdRef5Guid="034AF6E4-2295-4107-8D78-A49AB3BC74A8"?>
     <?define DocHtmlCmdRef8Guid="CCD33334-20E3-4b2d-AD14-097961BFF0F6"?>
     <?define DocHtmlInstallGuid="921E151E-9FD2-49A8-B297-0222E22ECAC7"?>