From 21edc432dcbb8b14c0a40feb2ea5de1bc0ae81f6 Mon Sep 17 00:00:00 2001 From: Andrew Deason Date: Fri, 4 Feb 2011 16:23:30 -0600 Subject: [PATCH] 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 Tested-by: Derrick Brashear --- doc/man-pages/.gitignore | 1 + doc/man-pages/Makefile.in | 13 +++++++------ doc/man-pages/NTMakefile | 1 + doc/man-pages/README | 4 ++-- doc/man-pages/check-pod | 2 +- doc/man-pages/generate-html | 7 +++++-- doc/man-pages/generate-man | 13 +++++++++++++ src/WINNT/install/NSIS/OpenAFS.nsi | 4 ++++ src/WINNT/install/wix/files.wxi | 5 +++++ src/WINNT/install/wix/language_config.wxi | 1 + 10 files changed, 40 insertions(+), 11 deletions(-) diff --git a/doc/man-pages/.gitignore b/doc/man-pages/.gitignore index 03bf4c9..f3811dd 100644 --- 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 --- 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 --- 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 --- 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 --- 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 --- 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 --- 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 --- 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 --- a/src/WINNT/install/wix/files.wxi +++ b/src/WINNT/install/wix/files.wxi @@ -510,6 +510,11 @@ + + + + + diff --git a/src/WINNT/install/wix/language_config.wxi b/src/WINNT/install/wix/language_config.wxi index de2cb9b..a0d417a 100644 --- a/src/WINNT/install/wix/language_config.wxi +++ b/src/WINNT/install/wix/language_config.wxi @@ -62,6 +62,7 @@ + -- 1.9.4