From 306e23e08ccba0f0b6e802c8a39fcc444555ae56 Mon Sep 17 00:00:00 2001 From: Jim Rees Date: Tue, 10 Apr 2007 20:52:30 +0000 Subject: [PATCH] doc-README-20070410 I didn't actually write this, just cribbed it from the openafs-info mailing list. --- doc/README | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 58 insertions(+), 0 deletions(-) create mode 100644 doc/README diff --git a/doc/README b/doc/README new file mode 100644 index 0000000..c2135c8 --- /dev/null +++ b/doc/README @@ -0,0 +1,58 @@ +What's in the "doc" subdirectory + +** doc/html +original ibm html doc, no longer used + +** doc/man-pages +pod sources for man pages (converted from original ibm html source). + +** doc/xml +xml sources for manuals (converted from original ibm html source). there is +some generated pdf/html content as well for the curious. + +Note that doc/xml/AdminReference uses doc/xml/AdminReference/pod2refentry to +convert the pod man pages to xml for printing. pod goes directly to html +just fine. + +The reference guide is now built by converting the existing pod documention +to xml. however, the indexing information was lost during the initial pod +conversion. Someone we will need to try to get that back. + +** doc/pdf +old Transarc (and possibly pre-Transarc) protocol and API documentation for +which we have no other source + +** doc/txt +doc/examples +a few other miscellaneous files. + + +From: Russ Allbery + +The Administrative Reference has been converted into separate POD man pages +for each command, since that's basically what it already was (just in HTML). +Considerable work remains to update that POD documentation to reflect the +current behavior of OpenAFS (for example, there's no documentation of +dynroot, no mention of Kerberos v5, many fileserver options are +undocumented, the afsd switch documentation is out of date, and so forth). +I've collected as many of those deficiencies as I know of in +doc/man-pages/README. Any contributions to correct any of those deficiences +are very welcome. This is one easy place to start. + +The other reference manuals (the Administrator's Guide, the Quick Start +Guide, and the User's Guide) are more manual-like in their structure. After +some on-list discussion, we picked DocBook as the format to use going +forward and the existing HTML files have been converted to DocBook with a +script. This means that the markup could use a lot of cleaning up and the +content is even less updated than the man pages. + +I did some *very* initial work on the Quick Start Guide, just to get the +makefile working and to try some simple modifications. Simon Wilkinson is +currently working on making more extensive modifications. If you want to +work on the Quick Start Guide, please coordinate with him to avoid duplicate +work. + +The Administrator's Guide and User's Guide have not yet been touched. Of +those, the latter is probably in the best shape, in that the user commands +and behavior haven't changed as much. If you'd like to start working on one +of those, that would also be great. -- 1.7.1