From: Michael Meffie Date: Wed, 2 Aug 2017 00:10:32 +0000 (-0400) Subject: doc: relocate notes from arch to txt X-Git-Tag: BP-openafs-stable-1_8_x~7 X-Git-Url: http://git.openafs.org/?p=openafs.git;a=commitdiff_plain;h=c6f5ebc4cf95b0f1d3acc7a0a8678ba0d4378243;hp=57d32c29146167ff54d3221ed761a5973776ae93 doc: relocate notes from arch to txt The doc/txt directory has become the de facto home for text-based technical notes. Relocate the contents of the doc/arch directory to doc/txt. Relocate doc/examples to doc/txt/examples. Update the doc/README file to be more current and remove old work in progress comments. Change-Id: Iaa53e77eb1f7019d22af8380fa147305ac79d055 Reviewed-on: https://gerrit.openafs.org/12675 Tested-by: BuildBot Reviewed-by: Benjamin Kaduk --- diff --git a/doc/README b/doc/README index c9fd64c..4988494 100644 --- a/doc/README +++ b/doc/README @@ -1,58 +1,22 @@ 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 documentation -to xml. however, the indexing information was lost during the initial pod -conversion. Someone we will need to try to get that back. +xml sources for manuals (converted from original IBM html source). +Note: The doc/xml/AdminRef uses doc/xml/AdminRef/pod2refentry to convert the +pod man pages to xml for printing. pod goes directly to html just fine. ** doc/pdf -old Transarc (and possibly pre-Transarc) protocol and API documentation for -which we have no other source +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 deficiencies -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. +Technical notes, Windows notes, and examples. -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. +** doc/doxygen +Configuration files for the doxygen tool to generate documentation from +the annotated sources. See the 'dox' Makefile target in the top level +Makefile. -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. diff --git a/doc/arch/README b/doc/txt/README similarity index 100% rename from doc/arch/README rename to doc/txt/README diff --git a/doc/arch/arch-overview.h b/doc/txt/arch-overview.h similarity index 100% rename from doc/arch/arch-overview.h rename to doc/txt/arch-overview.h diff --git a/doc/arch/dafs-fsa.dot b/doc/txt/dafs-fsa.dot similarity index 100% rename from doc/arch/dafs-fsa.dot rename to doc/txt/dafs-fsa.dot diff --git a/doc/arch/dafs-overview.txt b/doc/txt/dafs-overview.txt similarity index 100% rename from doc/arch/dafs-overview.txt rename to doc/txt/dafs-overview.txt diff --git a/doc/arch/dafs-vnode-fsa.dot b/doc/txt/dafs-vnode-fsa.dot similarity index 100% rename from doc/arch/dafs-vnode-fsa.dot rename to doc/txt/dafs-vnode-fsa.dot diff --git a/doc/examples/CellAlias b/doc/txt/examples/CellAlias similarity index 100% rename from doc/examples/CellAlias rename to doc/txt/examples/CellAlias diff --git a/doc/arch/fssync.txt b/doc/txt/fssync.txt similarity index 100% rename from doc/arch/fssync.txt rename to doc/txt/fssync.txt diff --git a/doc/txt/README.linux-nfstrans b/doc/txt/linux-nfstrans similarity index 100% rename from doc/txt/README.linux-nfstrans rename to doc/txt/linux-nfstrans