[OpenAFS-Doc] First cut of HTML reference manual

[ted creedon]

"AFS System Files" seems to be left out.

It would be handy if navigation aids were included.

The SYNOPSYS format of a man page is more difficult to read than the 
equivalent IBM document.

I.e.
*kas setfields* *-name* </name of user/> [*-flags* </hex flag value or 
flag name expression/>] [*-expiration* </date of account expiration/>] 
[*-lifetime* </maximum ticket lifetime/>] [*-pwexpires* </number days 
password is valid ([0..254])/>] [*-reuse* </permit password reuse 
(yes/no)/>] [*-attempts* </maximum successive failed login tries 
([0..254])/>] [*-locktime* </failure penalty [hh:mm or minutes]/>] 
[*-admin_username* </admin principal to use for authentication/>] 
[*-password_for_admin* </admin password/>] [*-cell* </cell name/>] 
[*-servers* </explicit list of authentication servers/>+] [*-noauth*] 
[*-help*]

vs.
kas setfields -name <name of user>
              [-flags <hex flag value or flag name expression>]
              [-expiration <date of account expiration>]
              [-lifetime <maximum ticket lifetime>]
              [-pwexpires <number days password is valid ([0..254])>]
              [-reuse <permit password reuse (yes/no)>]
              [-attempts <maximum successive failed login tries ([0..254])>]
              [-locktime <failure penalty [hh:mm or minutes]>]
              [-admin_username <admin principal to use for authentication>]
              [-password_for_admin <admin password>]  [-cell <cell name>]
              [-servers <explicit list of authentication servers>+]
              [-noauth]  [-help]

tedc

Russ Allbery wrote:
>I've just finished the first cut of an HTML conversion of the OpenAFS
>reference manual that's now maintained in POD.  There are still a few
>rough edges (such as interpage navigation) to work out and the results
>look rather sparse style-wise, but the content should be fairly
>reasonable.
>
>I've committed the script that does the HTML conversion to the trunk, and
>will probably pull that into the release branch before 1.4.1 goes final.
>You can see the results at:
>
>    <http://www.eyrie.org/~eagle/tmp/openafs/>
>
>right now.
>
>I'm sorry it took me so long to finish this part.
>
>Please look this over and mail openafs-doc@openafs.org with anything that
>looks wrong.  Also, now that we have pages up in HTML, now is the time for
>people to look them over and find any problems.  Ideally, patches against
>the POD source are desired, but go ahead and send notes about any problems
>that you find so that at least we can accumulate a problem list to start
>working on.
>
>Below are the already known problems that you don't have to report.  Any
>help with fixing these would also be 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.
>
>   * 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.)
>
>