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.
+ 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
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
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
* 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.)
+
+ * 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.
+
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.
git://git.openafs.org / openafs.git / blobdiff