Index: openafs/doc/LICENSE diff -c openafs/doc/LICENSE:1.1.20.1 openafs/doc/LICENSE:1.1.20.2 *** openafs/doc/LICENSE:1.1.20.1 Sun Apr 3 15:37:59 2005 --- openafs/doc/LICENSE Mon Feb 27 15:18:33 2006 *************** *** 690,692 **** --- 690,694 ---- * 2550 Garcia Avenue * Mountain View, California 94043 */ + + src/afs/LINUX/osi_flush.s included code under IBM Public License with permission of the author, Paul MacKerras. Index: openafs/doc/man-pages/.cvsignore diff -c /dev/null openafs/doc/man-pages/.cvsignore:1.2.2.4 *** /dev/null Fri Apr 14 09:27:12 2006 --- openafs/doc/man-pages/.cvsignore Mon Jan 30 13:21:48 2006 *************** *** 0 **** --- 1,6 ---- + Makefile + html + install-man + man1 + man5 + man8 Index: openafs/doc/man-pages/Makefile.in diff -c /dev/null openafs/doc/man-pages/Makefile.in:1.1.2.7 *** /dev/null Fri Apr 14 09:27:13 2006 --- openafs/doc/man-pages/Makefile.in Mon Jan 30 13:21:48 2006 *************** *** 0 **** --- 1,39 ---- + # Makefile for AFS man pages + + srcdir=@srcdir@ + include @TOP_OBJDIR@/src/config/Makefile.config + + all: + + maintclean: + rm -rf html man1 man5 man8 + + html: + perl generate-html + + dest: + chmod +x install-man + mkdir -p $(DEST)/man/man1 $(DEST)/man/man5 $(DEST)/man/man8 + set -e; cd man1 && for M in *.1 ; do \ + ../install-man $$M $(DEST)/man/man1/$$M ; \ + done + set -e; cd man5 && for M in *.5 ; do \ + ../install-man $$M $(DEST)/man/man5/$$M ; \ + done + set -e; cd man8 && for M in *.8 ; do \ + ../install-man $$M $(DEST)/man/man8/$$M ; \ + done + + install: $(MAN1) $(MAN8) + chmod +x install-man + mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man5 \ + $(DESTDIR)$(mandir)/man8 + set -e; cd man1 && for M in *.1 ; do \ + ../install-man $$M $(DESTDIR)$(mandir)/man1/$$M ; \ + done + set -e; cd man5 && for M in *.5 ; do \ + ../install-man $$M $(DESTDIR)$(mandir)/man5/$$M ; \ + done + set -e; cd man8 && for M in *.8 ; do \ + ../install-man $$M $(DESTDIR)$(mandir)/man8/$$M ; \ + done Index: openafs/doc/man-pages/README diff -c /dev/null openafs/doc/man-pages/README:1.4.2.9 *** /dev/null Fri Apr 14 09:27:13 2006 --- openafs/doc/man-pages/README Thu Mar 23 00:51:23 2006 *************** *** 0 **** --- 1,299 ---- + OpenAFS Man Pages + + Overview + + This directory contains the POD source and (in releases) the generated + man pages for OpenAFS commands and files. The man pages are based on + the original IBM AFS Administration Reference manual, released with the + rest of AFS under the IBM Public License 1.0. They were converted from + HTML to POD, editing, and are currently maintained in POD. + + The man pages are very much a work in progress. The original source + material dated from IBM's public release of AFS, and many changes since + made in OpenAFS are not reflected in the man pages. Help and + contributions are actively solicited. Please see "How You Can Help" + below for more information. + + The long-term goal is for every command shipped with OpenAFS and every + configuration or data file written or read by OpenAFS to have its own + man page. Section one is used for commands that don't require special + privileges, section eight for commands for AFS administrators and local + system administrators, and section five for file formats and + configuration files, with the exception that command suites are kept + together (so, for instance, all fs commands are documented in section + one even though some of them are only usable by a local system + administrator). + + The OpenAFS man pages are discussed on the openafs-doc mailing list at + openafs.org. If you plan on contributing to the man page project, + please join that mailing list and send suggestions, patches, and + contributions there. The coordinator of the OpenAFS man page project is + Russ Allbery ; feel free to contact me directly with + questions (although using the mailing list is generally better and will + probably result in a faster response). + + POD and Man Page Generation + + The OpenAFS man pages are maintained in POD (Plain Old Documentation), + the documentation system originally developed for Perl. This is not an + uncontroversial choice, since POD isn't as rich and full-featured as + other possible alternatives such as Docbook RefEntry. On the other + hand, POD is very close to plain text, can be easier to edit and + maintain for those not familiar with the documentation format, and has + more mature tools for conversion to formatted man pages, an output + format that is particularly important on Unix/Linux. There are many + good arguments either way, and fundamentally the decision was made to + use POD because I prefer it and I'm volunteering to write and edit the + pages and maintain them going forward. + + To convert the POD source to formatted man pages, you need the pod2man + utility. This utility has come with Perl for many years, so if you have + Perl installed, you almost certainly have some version of it available. + For the best results, install Pod::Simple 3.03 or later and podlators + 2.00 or later from CPAN and use that pod2man, but the results from the + pod2man that comes with Perl 5.8 or later will be very good. If you are + using earlier versions of Perl, the output should be adequate and + readable but may contain some formatting glitches. + + Preformatted man pages will be included in distribution tarballs, but + those man pages may be generated with older versions of the conversion + utilities. To regenerate the man pages, run regen.sh at the top of the + 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), 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 + + Each command or configuration file should have a separate man page in a + separate POD file. Command suites (fs, pts, vos, etc.) should have an + overview man page that lists the available subcommands by category, + documents common options, and discusses the general use of the suite. + Then, each operation code in the suite should have a separate man page, + named after the command with the space between the command suite and the + operation code replaced with an underscore. + + All man pages must follow the standard layout for man page sections and + formatting. The best general reference is the pod2man man page, + although the sections used for OpenAFS man pages aren't quite the same + (see below). In particular, please use the following markup: + + * B<> for all commands, command/operation code pairs, and options. + * F<> for file names, directory names, partition names, or paths. + * > for user-provided arguments (note the surrounding <>). + * I<> for terms being defined or titles of works. + * C<> for command examples, ACL characters, and example arguments. + + Also see the afs(1) man page for general rules about how OpenAFS man + pages are formatted and for standard terminology to use when talking + about OpenAFS commands. + + Each man page should have the following sections: NAME, SYNOPSIS (for + commands only), DESCRIPTION, CAUTIONS, OPTIONS (for commands only), + OUTPUT (where appropriate), EXAMPLES, PRIVILEGE REQUIRED (for commands + only), SEE ALSO, and COPYRIGHT, generally in that order. Be sure to + include the IBM copyright in all man pages derived from the original IBM + documentation. If you wrote the man page yourself, please include your + own copyright and a statement that the man page is released under the + IBM Public License Version 1.0, or under some other license that is + sufficiently compatible that we can use your work. If you use another + license and that license isn't "public domain," you have to give the + full license text in the man page; please don't use a license so long + that this is annoying. + + The SYNOPSIS section should start with the full command name and the + full names of all options, and then have a second section showing the + most abbreviated form of the command name and its options. If the + command has aliases, it should have additional sections showing those. + Please be sure to follow all of the formatting requirements for + commands, flags, and options. Enclose optional arguments in [] and + choices in () separated by |. Command names and options are marked up + with B<> as mentioned above; all other literal text that should be + entered on the command line gets no markup. + + References to other OpenAFS man pages should be given as L. + Other man pages should be noted like df(1), without the L<> markup. + References to functions should be noted like function() with the + trailing parens. The POD converters know how to format these sorts of + references appropriately. References to other sections in the same page + should be given as L
. + + Command and output examples should be indented three spaces. Commands + entered by the user should be given on a line beginning with %. If the + command doesn't fit in 80 columns, put in a backslash at a logical break + point and continue the line with an additional four spaces of + indentation. Output examples may be wrapped with an additional four + spaces of indentation but probably shouldn't be; not wrapping makes the + man page look somewhat less readable, but is less confusing when + converted to other formats such as HTML. + + POD does not allow markup in verbatim paragraphs (which are indicated by + indenting the first line of the paragraph), so metasyntactic variables + in examples should be shown like with simple angle brackets + surrounding the variable. For consistency in formatting, references to + those variables should be formatted the same in following text. + + How You Can Help + + The OpenAFS man page project is just starting, and a lot of work remains + to be done. Any and all contributions are greatly appreciated. What + follows is a list of the ways that you can help in order of increasing + helpfulness. If you only have time to do something near the top of the + list, please do; every little bit helps. If you have more time and can + do something closer to the bottom of the list, that's even better and + your contribution can be included more rapidly. + + * Point out places OpenAFS behavior has changed since the documentation + was written, or point out missing documentation. Please check the + "Known Problems" list below to make sure that the item is not already + noted. + + * Point out formatting problems, typos, formatting inconsistency, and + other markup or language problems in the man pages. + + * Provide missing documentation in some form (text, HTML, whatever) + that can be incorporated into the man pages, or detailed explanations + of how the existing documentation needs to be changed to match what + the tools actually do. + + * Provide missing man pages in POD format suitable for immediate + inclusion in the documentation. Please try to follow the formatting + standards documented in the "Formatting Standards" section above, and + look at the existing man pages for examples. + + * Provide patches against the POD source that correct formatting + problems, typos, formatting inconsistencies, or other markup or + language problems with the man pages. + + * Provide patches against the POD source that add or correct the + documentation of commands or file formats for changes in OpenAFS. + + Please send contributions either to the openafs-doc list or as bugs + filed via the bug reporting instructions at . + If you do submit a bug, please send me a note at rra@stanford.edu with + the bug number so that I'm aware of it, as I don't always notice new + bugs. + + Known Problems + + The current man pages have the following known deficiencies. Please + don't just report the deficiency again, but any contributions towards + fixing it are greatly appreciated. + + * The following installed commands have no man pages: + + bos_util + copyauth + fs getcalleraccess + fs getcrypt + fs listaliases + fs newalias + fs rxstatpeer + fs rxstatproc + fs setcbaddr + fs setcrypt + kseal + pts interactive + pts quit + pts sleep + pts source + read_tape + restorevol + rmtsysd + vldb_convert + vos changeloc + vos clone + vos convertROtoRW + vos copy + vos shadow + vos size + vsys + + * The following configuration files have no man pages: + + CellAlias + + * klog.krb, pagsh.krb, and tokens.krb need to be listed as alternative + names in the NAME line of the non-.krb man pages, links should be + installed on man page installation, and the behavior of pagsh.krb + should be documented in the pagsh man page. + + * Some of the documentation in fs getserverprefs needs minor updates to + reflect what happens in the dynroot case. + + * fs sysname documentation needs to include the possibility of setting + multiple sysnames and the resulting behavior. + + * The afsd man page is horribly out of date. It doesn't explain + dynroot, many options are missing, and some of the options described + are no longer valid. It also still assumes that -settime is the + default and says that the system must be rebooted after shutdown, + which isn't the case at least on Linux. + + * bos listkeys and the KeyFile man page assume that you're using the + kaserver. + + * I'm fairly sure that the fileserver man page no longer documents all + of the fileserver options. + + * The package man page should probably mention the (pointless) package + apropos and package help commands, or they could be removed. There + used to be separate man pages for them, but that seemed rather + pointless. + + * There are lingering references to AFS Development or AFS Product + Support in descriptions of options that one should generally not + use. Also, all of the manual references refer to the "IBM" manual. + We should decide how to handle this terminology-wise. + + * The salvager actually creates a bunch of SalvageLog files and then + combines them, but the SalvageLog man page doesn't reflect this. + + * The CellServDB documentation hasn't been updated for -dynroot. + + * 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. + + * The references to the other OpenAFS manuals, such as the Quick Start + guide and the Admin Guide, should be links, probably to the documents + on openafs.org. + + * There's no mention of the Kerberos v5 support. At least, we need + some disclaimers under klog and friends talking about sites without + kaserver (and possibly without fakeka), and deprecation warnings + on the .krb varient commands. + + * We need a way to add links to other man pages (kinit most notably) + without creating dangling links in the HTML output. This probably + means that the HTML conversion script needs to generate at startup + a list of all valid man page link targets and not linkify the ones + that don't match a valid target. + + * Provide a way to substitute the correct paths into the HTML output + from Autoconf results. + + * Currently, the man pages are built by regen.sh, which is somewhat + annoying since it takes a long time. Figure out how better to do this + during the release process so that end users don't have to have + pod2man. + + * Review the sections used for all man pages against what directories + the commands are installed into. (In some cases, it may be better to + change the directory than the section of the man page.) + + 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. Index: openafs/doc/man-pages/generate-html diff -c /dev/null openafs/doc/man-pages/generate-html:1.1.4.3 *** /dev/null Fri Apr 14 09:27:13 2006 --- openafs/doc/man-pages/generate-html Tue Feb 28 18:48:45 2006 *************** *** 0 **** --- 1,132 ---- + #!/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; + } + + # Underscore isn't allowed in man page names in Pod::Simple 3.04, so links + # like L 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'} = '

  • '; + $Pod::Simple::HTML::Tagmap{'/item-bullet'} = '

    • '; + $Pod::Simple::HTML::Tagmap{'item-number'} = '

  • '; + $Pod::Simple::HTML::Tagmap{'/item-number'} = '

    • '; + + package main; + + use strict; + + use File::Copy; + use Pod::Simple::HTMLBatch; + + our $HEADER = <<'EOH'; + + + OpenAFS Reference Manual + + + +

    OpenAFS Reference Manual

    + 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 () { + 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 "\n"; + my @index = scan_names; + my $current; + for my $entry (@index) { + my ($section, $name, $page, $desc) = @$entry; + for ($name, $desc) { + s/&/>/g; + s//>/g; + } + if (!$current || $section != $current) { + print INDEX qq(\n); + print INDEX qq(\n); + $current = $section; + } + print INDEX qq(); + print INDEX qq(\n); + } + print INDEX "
     
    ); + print INDEX qq($HEADINGS{$section}
    $name$desc
    \n\n\n"; Index: openafs/doc/man-pages/generate-man diff -c /dev/null openafs/doc/man-pages/generate-man:1.1.2.3 *** /dev/null Fri Apr 14 09:27:13 2006 --- openafs/doc/man-pages/generate-man Wed Mar 8 15:20:18 2006 *************** *** 0 **** --- 1,64 ---- + #!/bin/sh + # + # Generate the OpenAFS man pages from POD source. This script is normally + # invoked by regen.sh but may be run at any time to rebuild all of the man + # pages (with a newer version of pod2man than was used for the release, for + # instance). + + # Exit on any error. + set -e + + if [ ! -d pod1 ] ; then + echo 'generate-man must be run from the doc/man-pages directory' >&2 + exit 1 + fi + + if pod2man pod1/afs.pod > /dev/null ; then + : + else + echo 'pod2man not found, skipping man page generation' >&2 + exit 1 + fi + if perl -e 'use Pod::Man 2.04' > /dev/null 2>&1 ; then + : + else + echo 'Pod::Man is older than the recommended version of 2.04 or later' >&2 + echo 'Continuing with man page generation anyway' >&2 + fi + + # Create the directories. We generate each section into its own directory + # to make installation rules easier. + [ -d man1 ] || mkdir man1 + [ -d man5 ] || mkdir man5 + [ -d man8 ] || mkdir man8 + + # Generate each set of man pages. For each, allow for the case of the + # directory being empty. In that case, for won't expand the wildcard, and + # we want to avoid running pod2man with a wildcard as an argument. + pod1=`ls pod1` + if [ -n "$pod1" ] ; then + cd pod1 + for f in *.pod ; do + pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 "$f" \ + > ../man1/`echo "$f" | sed 's/\.pod$//'`.1 + done + cd .. + fi + pod5=`ls pod5` + if [ -n "$pod5" ] ; then + cd pod5 + for f in *.pod ; do + pod2man -c 'AFS File Reference' -r 'OpenAFS' -s 5 "$f" \ + > ../man5/`echo "$f" | sed 's/\.pod$//'`.5 + done + cd .. + fi + pod8=`ls pod8` + if [ -n "$pod8" ] ; then + cd pod8 + for f in *.pod ; do + pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 "$f" \ + > ../man8/`echo "$f" | sed 's/\.pod$//'`.8 + done + cd .. + fi Index: openafs/doc/man-pages/install-man.in diff -c /dev/null openafs/doc/man-pages/install-man.in:1.1.2.2 *** /dev/null Fri Apr 14 09:27:13 2006 --- openafs/doc/man-pages/install-man.in Thu Jan 5 13:54:50 2006 *************** *** 0 **** --- 1,50 ---- + #!/bin/sh + # + # Install a man page, but fixing up paths as we go. All of the man pages + # are written to use the Transarc paths, and this script fixes those paths to + # be correct for the chosen configure options as the man pages are installed. + # Takes the source man page file and the destination path as arguments. + + set -e + + manpage="$1" + dest="$2" + + install=@TOP_OBJDIR@/src/pinstall/pinstall + + # We have to include all of the variables here since several of them refer to + # each other and this is the only way we get them all expanded. + prefix=@prefix@ + exec_prefix=@exec_prefix@ + bindir=@bindir@ + includedir=@includedir@ + libdir=@libdir@ + libexecdir=@libexecdir@ + localstatedir=@localstatedir@ + mandir=@mandir@ + sbindir=@sbindir@ + sysconfdir=@sysconfdir@ + afsbackupdir=@afsbackupdir@ + afsbosconfigdir=@afsbosconfigdir@ + afsconfdir=@afsconfdir@ + afsdbdir=@afsdbdir@ + afslocaldir=@afslocaldir@ + afslogsdir=@afslogsdir@ + afssrvbindir=@afssrvbindir@ + afskerneldir=@afskerneldir@ + afssrvlibexecdir=@afssrvlibexecdir@ + afssrvsbindir=@afssrvsbindir@ + viceetcdir=@viceetcdir@ + + # Substitute the paths into a local temporary file and then install it with + # $install. + sed -e "s%/usr/afs/local/BosConfig%${afsbosconfigdir}/BosConfig%g" \ + -e "s%/usr/afs/etc%${afsconfdir}%g" \ + -e "s%/usr/afs/backup%${afsbackupdir}%g" \ + -e "s%/usr/afs/bin%${afssrvlibexecdir}%g" \ + -e "s%/usr/afs/db%${afsdbdir}%g" \ + -e "s%/usr/afs/local%${afslocaldir}%g" \ + -e "s%/usr/afs/logs%${afslogsdir}%g" \ + -e "s%/usr/vice/etc%${viceetcdir}%g" "$manpage" > "$manpage".tmp + $install -c -f -m 0644 "$manpage".tmp "$dest" + rm "$manpage".tmp Index: openafs/doc/man-pages/style.css diff -c /dev/null openafs/doc/man-pages/style.css:1.1.4.4 *** /dev/null Fri Apr 14 09:27:13 2006 --- openafs/doc/man-pages/style.css Wed Mar 1 00:11:17 2006 *************** *** 0 **** --- 1,83 ---- + /* 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 { text-decoration: none; } + a:visited { text-decoration: none; } + a:active { text-decoration: none; } + a:hover { background: #fec; text-decoration: none; } + 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 } + + /* Special handling for the synopsis section to outdent the first line. */ + body.pod .synopsis { padding-left: 2em; text-indent: -2em; } + + body.contentspage { + color: #000; + background-color: #fff; + } + + body.contentspage h1 { + color: #000; + 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; } + } Index: openafs/doc/man-pages/pod1/afs.pod diff -c /dev/null openafs/doc/man-pages/pod1/afs.pod:1.3.2.6 *** /dev/null Fri Apr 14 09:27:13 2006 --- openafs/doc/man-pages/pod1/afs.pod Mon Feb 27 15:47:42 2006 *************** *** 0 **** --- 1,559 ---- + =head1 NAME + + afs - Introduction to AFS commands + + =head1 DESCRIPTION + + AFS provides many commands that enable users and system administrators to + use and customize its features. Many of the commands belong to the + following categories, called I. + + =over 4 + + =item backup + + Interface for configuring and operating the AFS Backup System. + + =item bos + + Interface to the Basic Overseer (BOS) Server for administering server + processes and configuration files. + + =item fs + + Interface for administering access control lists (ACLs), the Cache + Manager, and other miscellaneous file system functions. + + =item fstrace + + Interface for tracing Cache Manager operations when debugging problems. + + =item kas + + Interface to the Authentication Server for administering security and + authentication information. + + =item pts + + Interface to the Protection Server for administering AFS ID and group + membership information. + + =item uss + + Interface for automated administration of user accounts. + + =item vos + + Interface to the Volume Server and Volume Location (VL) Server for + administering volumes. + + =back + + In addition, there are several commands that do not belong to + suites. + + =head2 AFS Command Syntax + + AFS commands that belong to suites have the following structure: + + I I B<-switch> >[+] [B<-flag>] + + =head3 Command Names + + Together, the I and I make up the I. + + The I specifies the group of related commands to which the + command belongs, and indicates which command interpreter and server + process perform the command. AFS has several command suites, including + B, B, B, B, B, B and B. Some of + these suites have an interactive mode in which the issuer omits the + I portion of the command name. + + The I tells the command interpreter and server process + which action to perform. Most command suites include several operation + codes. The man pages for each command name describe each operation code in + detail, and the I describes how to use them + in the context of performing administrative tasks. + + Several AFS commands do not belong to a suite and so their names do not + have a I portion. Their structure is otherwise similar to + the commands in the suites. + + =head3 Options + + The term I