man-page-misc-improvements-20051221
[openafs.git] / doc / man-pages / README
index 15074a9..799e42e 100644 (file)
@@ -183,16 +183,10 @@ Known Problems
   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:
+   * The following installed commands have no man pages:
 
+       bos_util
+       copyauth
        fs getcalleraccess
        fs getcrypt
        fs listaliases
@@ -201,16 +195,26 @@ Known Problems
        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
@@ -223,6 +227,41 @@ Known Problems
    * 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.
+
+   * All of the paths in the man pages are the Transarc paths.  I'm not
+     sure how best to deal with the possibility of installing OpenAFS in
+     multiple different paths, but it would be good to at least
+     acknowledge the issue.
+
+   * 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.)
+
   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.