man-page-vos-clone-20080626

[openafs.git] / doc / man-pages / README

diff --git a/doc/man-pages/README b/doc/man-pages/README
index e4ce810..7cc5c53 100644 (file)
--- a/doc/man-pages/README
+++ b/doc/man-pages/README
@@ -78,7 +78,10 @@ Formatting Standards
   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.
+  operation code replaced with an underscore.  The NAME section of the
+  operation man page must also use an underscore (fs_listacl, not fs
+  listacl) for compatibility with some man programs.  The SYNOPSIS section
+  should, of course, use a space, since that's what the user must type.
 
   All man pages must follow the standard layout for man page sections and
   formatting.  The best general reference is the pod2man man page,
@@ -185,6 +188,11 @@ How You Can Help
   the bug number so that I'm aware of it, as I don't always notice new
   bugs.
 
+  You can test your new POD documentation by running the check-pod script
+  in this directory with "prove check-pod".  (And check other people's
+  documentation and find any problems that have crept in.)  You will need
+  to have Test::Pod installed.
+
 Known Problems
 
   The current man pages have the following known deficiencies.  Please
@@ -193,30 +201,26 @@ Known Problems
 
    * The following installed commands have no man pages:
 
-       bos_util
+       compile_et.afs
        copyauth
-       flushall (Windows only)
-       fs getcalleraccess
+       fs cscpolicy
+       fs memdump
+       fs monitor
        fs rxstatpeer
        fs rxstatproc
        fs setcbaddr
-       kseal
-       pts interactive
-       pts quit
-       pts sleep
-       pts source
-       read_tape
+       klog.krb
+       krb.conf
+       pagsh.krb
        restorevol
        rmtsysd
+       tokens.krb
        vldb_convert
-       vos changeloc
-       vos clone
-       vos convertROtoRW
-       vos copy
-       vos shadow
-       vos size
+       vos setfields
        vsys
 
+   * Add -noresolve to the documentation of all the vos commands.
+
    * 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
@@ -225,14 +229,11 @@ Known Problems
    * 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.
-
    * 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.
+   * bos addkey should be marked deprecated in favor of using asetkey with
+     a keytab.
 
    * There are lingering references to AFS Development or AFS Product
      Support in descriptions of options that one should generally not