man-page-readme-20051209

Initial documentation for the man page project, including initial notes
on conversion, a start at a formatting guide, information on how to
contribute, and an initial issues list of things I happened to notice
while editing the section one pages.

doc/man-pages/README

@@ -0,0 +1,228 @@
+                            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 <rra@stanford.edu>; 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).  Evaluation of the best tool to use
+  for OpenAFS and exactly how to do the conversion to get the highest
+  quality results is still underway; when complete, details will be
+  included here.
+
+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.
+   * <I<>> 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<afs(1)>.
+  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<SECTION>.
+
+  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 <this> 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 <http://www.openafs.org/>.
+  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 section five and section eight man pages have not yet had an
+     initial editing pass and many of the section five man pages are
+     missing because the original reference page names didn't easily
+     convert to man page names.  This is currently being fixed.  Please do
+     not start working on the section five or section eight man pages yet
+     or bother reporting problems with them; they will be changing
+     significantly in the near future.
+
+   * The following commands have no man pages:
+
+       fs getcalleraccess
+       fs getcrypt
+       fs listaliases
+       fs newalias
+       fs rxstatpeer
+       fs rxstatproc
+       fs setcbaddr
+       fs setcrypt
+       pts interactive
+       pts quit
+       pts sleep
+       pts source
+       vos changeloc
+       vos clone
+       vos convertROtoRW
+       vos copy
+       vos shadow
+       vos size
+
+   * 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.
+
+  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.