[OpenAFS-Doc] First cut of HTML reference manual

[Russ Allbery]

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-***@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.)

[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

Post by Russ Allbery
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.
<http://www.eyrie.org/~eagle/tmp/openafs/>
right now.
I'm sorry it took me so long to finish this part.
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.
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
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.)

[Russ Allbery]

Post by ted creedon
"AFS System Files" seems to be left out.

You should go look closer.

Post by ted creedon
It would be handy if navigation aids were included.

Yes. I'll figure something out there.

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

Yeah, this is semi-hard to fix but it's on my list of things to figure
out. It works right for man pages; now I just need to figure out the best
way of doing the same for HTML.

[Todd M. Lewis]

Post by Russ Allbery
I've just finished the first cut of an HTML conversion of the OpenAFS
reference manual that's now maintained in POD.

Yeah!

Post by Russ Allbery
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.

I looked for a while, but couldn't find the POD source to make a patch
against. So I made a patch against the html (sorry).

Attached is a patch for the 'up' documentation to include stuff about
the "-m" flag. "-m" has been there for several years, but the
"usage..." message from 'up' may or may not include reference to it
depending on how many parameters are passed in. (I've submitted a
separate bug/patch for up.c to openafs-bugs for that.)

Not that 'up' is the the most important utility in the suite, but it's
great that there's somewhere to document the new (3 year old)
functionality. Thanks for your efforts.

[Russ Allbery]

Post by Todd M. Lewis
I looked for a while, but couldn't find the POD source to make a patch
against. So I made a patch against the html (sorry).
Attached is a patch for the 'up' documentation to include stuff about
the "-m" flag. "-m" has been there for several years, but the
"usage..." message from 'up' may or may not include reference to it
depending on how many parameters are passed in. (I've submitted a
separate bug/patch for up.c to openafs-bugs for that.)
Not that 'up' is the the most important utility in the suite, but it's
great that there's somewhere to document the new (3 year old)
functionality. Thanks for your efforts.

Thanks! This has been committed. Sorry about the long delay; I lost
February for most productive work for a variety of reasons.

[Todd M. Lewis]

Post by Russ Allbery
I've just finished the first cut of an HTML conversion of the OpenAFS
reference manual that's now maintained in POD.

Yeah!

Post by Russ Allbery
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.

I looked for a while, but couldn't find the POD source to make a patch
against. So I made a patch against the html (sorry).

Attached is a patch for the 'up' documentation to include stuff about
the "-m" flag. "-m" has been there for several years, but the
"usage..." message from 'up' may or may not include reference to it
depending on how many parameters are passed in. (I've submitted a
separate bug/patch for up.c to openafs-bugs for that.)

Not that 'up' is the the most important utility in the suite, but it's
great that there's somewhere to document the new (3 year old)
functionality. Thanks for your efforts.

[chas williams - CONTRACTOR]

Post by Russ Allbery
looks wrong. Also, now that we have pages up in HTML, now is the time for

i converted the pod to docbook and generated a "printable" manual.
during the conversion i came across some minor problems (mostly with
links/references to the wrong sections). i have attached a patch to
fix these.

for the curious, the pdf and pod to docbook convertor (it is not a
general convertor--it only produces <refentry>'s) is available at:

ftp://ftp.cmf.nrl.navy.mil/pub/chas/openafs/AdminReference.tar.gz

[Russ Allbery]

Post by chas williams - CONTRACTOR
i converted the pod to docbook and generated a "printable" manual.
during the conversion i came across some minor problems (mostly with
links/references to the wrong sections). i have attached a patch to
fix these.

Thanks, this has been applied (by Derrick).

Post by chas williams - CONTRACTOR
for the curious, the pdf and pod to docbook convertor (it is not a
ftp://ftp.cmf.nrl.navy.mil/pub/chas/openafs/AdminReference.tar.gz

Thanks, grabbed a copy. I think it would be cool to include this program
or something like it in podlators at some point down the road.