jimzah/openafs
1
0
Fork 0
mirror of https://git.openafs.org/openafs.git synced 2025-01-18 06:50:12 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Add include method for POD documentation

Browse Source 
Add a preprocessor for POD documentation that handles a custom
=include directive.  Demonstrate how to use the preprocessor by
factoring out all the standard PTS options into a separate POD
fragment and including that fragment in all the PTS commands that
take the standard options instead of including that documentation
in each separate file.

Change-Id: If5255efc6d3fc670b38a9898b3d7d3c60af04fcf
Reviewed-on: http://gerrit.openafs.org/2440
Reviewed-by: Derrick Brashear <shadow@dementia.org>
Tested-by: Derrick Brashear <shadow@dementia.org>
This commit is contained in:
Russ Allbery 2010-07-15 17:21:26 -07:00 committed by Derrick Brashear
parent 3e2c3c9a56
commit a792acdadc
23 changed files with 111 additions and 441 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/man-pages/check-pod
View File

@ -28,7 +28,7 @@ for ( @ARGV ? @ARGV : @poddirs ) {
if ( -f ) {
push @list, $_
} elsif ( -d ) {
push @list, all_pod_files( $_ )
push @list, grep { !m,fragments/, } all_pod_files( $_ )
}
}

44
doc/man-pages/merge-pod Executable file
View File

@ -0,0 +1,44 @@
#!/usr/bin/perl -w
#
# POD currently doesn't support any sort of =include directive. This
# processor works around that limitation. It takes a list of files ending in
# *.in as its argument and processes any POD directives of the form =include
# <file> in that file, generating a file with the *.in suffix removed. All
# paths are taken to be relative to the directory containing the file being
# processed.
#
# Currently, only single include nesting is supported. The included file is
# not processed for additional =include statements.
require 5.006;
use Cwd qw(getcwd);
use File::Basename qw(dirname basename);
my $start = getcwd;
for my $file (@ARGV) {
chdir $start or die "cannot chdir to $start: $!\n";
my $dir = dirname ($file);
my $out = $file;
unless ($out =~ s/\.in\z//) {
die "input file $file does not end in .in\n";
}
open (FILE, '<', $file) or die "cannot open $file: $!\n";
open (OUT, '>', $out) or die "cannot open $out: $!\n";
chdir $dir or die "cannot chdir to $dir: $!\n";
local $/ = '';
local $_;
while (<FILE>) {
if (/^=include\s+(\S+)/) {
open (INCLUDE, '<', $1) or die "cannot open $1: $!\n";
local $/;
print OUT <INCLUDE> or die "cannot read/write from $1: $!\n";
close INCLUDE or die "cannot read from $1: $!\n";
print OUT "\n" or die "cannot write to $out: $!\n";
} else {
print OUT $_ or die "cannot write to $out: $!\n";
}
}
close OUT or die "cannot write to $out: $!\n";
close FILE or die "cannot read from $file\n";
}

22
doc/man-pages/pod1/.gitignore vendored Normal file
View File

@ -0,0 +1,22 @@
# After changing this file, please run
# git ls-files -i --exclude-standard
# to check that you haven't inadvertently ignored any tracked files.
/pts_adduser.pod
/pts_chown.pod
/pts_creategroup.pod
/pts_createuser.pod
/pts_delete.pod
/pts_examine.pod
/pts_interactive.pod
/pts_listentries.pod
/pts_listmax.pod
/pts_listowned.pod
/pts_membership.pod
/pts_quit.pod
/pts_removeuser.pod
/pts_rename.pod
/pts_setfields.pod
/pts_setmax.pod
/pts_sleep.pod
/pts_source.pod

25
doc/man-pages/pod1/fragments/pts-common.pod Normal file
View File

@ -0,0 +1,25 @@
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the B<-cell>
or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.

28
doc/man-pages/pod1/pts_adduser.pod → doc/man-pages/pod1/pts_adduser.pod.in
View File

@ -50,33 +50,7 @@ Specifies the complete name (including the owner prefix if applicable) of
each group to which to add members. The group entry must already exist in
the Protection Database.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. The B<pts> command interpreter presents the
ticket to the Protection Server during mutual authentication. Do not combine
this flag with the B<-cell> or B<-noauth> options. For more details, see
L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_chown.pod → doc/man-pages/pod1/pts_chown.pod.in
View File

@ -52,31 +52,7 @@ Specifies the current name of the group to which to assign a new owner.
Names the user or group to become the group's owner.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the B<-cell>
or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_creategroup.pod → doc/man-pages/pod1/pts_creategroup.pod.in
View File

@ -144,31 +144,7 @@ there are more GIDs than groups, the excess GIDs are ignored. If any of
the GIDs is lower (more negative) than the current value of the C<max
group id> counter, the counter is reset to that value.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_createuser.pod → doc/man-pages/pod1/pts_createuser.pod.in
View File

@ -128,31 +128,7 @@ counter. If there are more UIDs than entries, the excess UIDs are
ignored. If any of the UIDs is greater than the current value of the C<max
user id> counter, the counter is reset to that value.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_delete.pod → doc/man-pages/pod1/pts_delete.pod.in
View File

@ -62,31 +62,7 @@ groups on the same command line, as well as names (IP addresses for
machines) and IDs. Precede the GID of each group with a hyphen to indicate
that it is negative.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_examine.pod → doc/man-pages/pod1/pts_examine.pod.in
View File

@ -42,36 +42,12 @@ acceptable to mix users, machines, and groups on the same command line, as
well as names (IP addresses for machines) and IDs. Precede the GID of each
group with a hyphen to indicate that it is negative.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-auth>
Run using the user's current authentication. This is the default unless
the B<-noauth> or B<-localauth> options are used.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

23
doc/man-pages/pod1/pts_interactive.pod → doc/man-pages/pod1/pts_interactive.pod.in
View File

@ -45,28 +45,7 @@ B<pts interactive> only takes the standard B<pts> options.
=over 4
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
This is useful for bulk operations where you would like to continue even
if one of many operations fails.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_listentries.pod → doc/man-pages/pod1/pts_listentries.pod.in
View File

@ -38,31 +38,7 @@ Displays user and machine entries.
Displays group entries.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_listmax.pod → doc/man-pages/pod1/pts_listmax.pod.in
View File

@ -35,31 +35,7 @@ can issue the B<pts setmax> command.
=over 4
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_listowned.pod → doc/man-pages/pod1/pts_listowned.pod.in
View File

@ -41,31 +41,7 @@ negative.
A value of 0 (zero) lists group entries for groups whose owners no longer
have entries in the Protection Database.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_membership.pod → doc/man-pages/pod1/pts_membership.pod.in
View File

@ -75,31 +75,7 @@ argument.
Group membership may be nested when B<ptserver> is compilied with the
SUPERGROUPS option enabled.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

21
doc/man-pages/pod1/pts_quit.pod → doc/man-pages/pod1/pts_quit.pod.in
View File

@ -35,26 +35,7 @@ B<pts> options:
=over 4
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_removeuser.pod → doc/man-pages/pod1/pts_removeuser.pod.in
View File

@ -47,31 +47,7 @@ wildcard-style) of each machine entry to remove.
Names each group from which to remove members.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_rename.pod → doc/man-pages/pod1/pts_rename.pod.in
View File

@ -60,31 +60,7 @@ Specifies the new full name for the entry. For regular groups, the owner
field (the part before the colon) of the new name must reflect the actual
ownership of the group.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_setfields.pod → doc/man-pages/pod1/pts_setfields.pod.in
View File

@ -195,31 +195,7 @@ Specifies the number of additional groups a user can create (it does not
matter how many he or she has created already). Do not include this
argument for a group or machine entry.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

26
doc/man-pages/pod1/pts_setmax.pod → doc/man-pages/pod1/pts_setmax.pod.in
View File

@ -46,31 +46,7 @@ createuser> command to create a user or machine entry and does not include
that command's B<-id> argument, the Protection Server assigns the group an
AFS UID one greater than this value.
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-help>
Prints the online help for this command. All other valid options are
ignored.
=include fragments/pts-common.pod
=back

21
doc/man-pages/pod1/pts_sleep.pod → doc/man-pages/pod1/pts_sleep.pod.in
View File

@ -38,26 +38,7 @@ B<pts> options:
=over 4
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=include fragments/pts-common.pod
=back

27
doc/man-pages/pod1/pts_source.pod → doc/man-pages/pod1/pts_source.pod.in
View File

@ -35,32 +35,7 @@ B<pts source> takes the following options:
=over 4
=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
L<pts(1)>.
=item B<-file> <I<file name>>
Specifies the filename from which to read commands.
=item B<-force>
Enables the command to continue executing as far as possible when errors
or other problems occur, rather than halting execution at the first error.
This is useful for bulk operations where you would like to continue even
if one of many operations fails.
=item B<-noauth>
Assigns the unprivileged identity anonymous to the issuer. For more
details, see L<pts(1)>.
=item B<-localauth>
Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. Do not combine this flag with the
B<-cell> or B<-noauth> options. For more details, see L<pts(1)>.
=include fragments/pts-common.pod
=back

1
regen.sh
View File

@ -45,6 +45,7 @@ else
# pod2man available.
if test -d doc/man-pages ; then
echo "Building man pages"
perl doc/man-pages/merge-pod doc/man-pages/pod1/*.in
(cd doc/man-pages && ./generate-man)
fi
fi