doc/README

   1 What's in the "doc" subdirectory
   2
   3 ** doc/html
   4 original ibm html doc, no longer used
   5
   6 ** doc/man-pages
   7 pod sources for man pages (converted from original ibm html source).
   8
   9 ** doc/xml
  10 xml sources for manuals (converted from original ibm html source).  there is
  11 some generated pdf/html content as well for the curious.
  12
  13 Note that doc/xml/AdminReference uses doc/xml/AdminReference/pod2refentry to
  14 convert the pod man pages to xml for printing.  pod goes directly to html
  15 just fine.
  16
  17 The reference guide is now built by converting the existing pod documention
  18 to xml.  however, the indexing information was lost during the initial pod
  19 conversion.  Someone we will need to try to get that back.
  20
  21 ** doc/pdf
  22 old Transarc (and possibly pre-Transarc) protocol and API documentation for
  23 which we have no other source
  24
  25 ** doc/txt
  26 doc/examples
  27 a few other miscellaneous files.
  28
  29
  30 From: Russ Allbery
  31
  32 The Administrative Reference has been converted into separate POD man pages
  33 for each command, since that's basically what it already was (just in HTML).
  34 Considerable work remains to update that POD documentation to reflect the
  35 current behavior of OpenAFS (for example, there's no documentation of
  36 dynroot, no mention of Kerberos v5, many fileserver options are
  37 undocumented, the afsd switch documentation is out of date, and so forth).
  38 I've collected as many of those deficiencies as I know of in
  39 doc/man-pages/README.  Any contributions to correct any of those deficiences
  40 are very welcome.  This is one easy place to start.
  41
  42 The other reference manuals (the Administrator's Guide, the Quick Start
  43 Guide, and the User's Guide) are more manual-like in their structure.  After
  44 some on-list discussion, we picked DocBook as the format to use going
  45 forward and the existing HTML files have been converted to DocBook with a
  46 script.  This means that the markup could use a lot of cleaning up and the
  47 content is even less updated than the man pages.
  48
  49 I did some *very* initial work on the Quick Start Guide, just to get the
  50 makefile working and to try some simple modifications.  Simon Wilkinson is
  51 currently working on making more extensive modifications.  If you want to
  52 work on the Quick Start Guide, please coordinate with him to avoid duplicate
  53 work.
  54
  55 The Administrator's Guide and User's Guide have not yet been touched.  Of
  56 those, the latter is probably in the best shape, in that the user commands
  57 and behavior haven't changed as much.  If you'd like to start working on one
  58 of those, that would also be great.