status of the Kerberos documentation project

[Zhanna Tsitkova]

Hello,
This is to update you on  the current state of the Kerberos  
documentation effort and to hear your feedback.

Briefly, the goal of the project is to create a full scale "one-stop- 
shopping" Kerberos documentation that would be easy to support and  
contribute to, and that would have the benefits of  cross-referencing  
and  feedback management.

The first step of the project was creating Doxygen style API  
documentation.  Please, see the current Doxygen output at http://web.mit.edu/afs/athena/user/t/s/tsitkova/www/v10/trunk/out/html/krb5_8hin.html 
    As of now almost all of 300+ API functions (see krb5.hin) are  
documented with the emphasis on the description of parameters and  
functionality.  Some of the API functions have usage examples  -  
generally we want all of the API to have them.  Also, many comments  
were added to the public structures/datatypes/defines.

We propose using Sphinx documentation generator to put together in an  
organized manner the documentation for users, administrators  and  
developers. (See http://web.mit.edu/tsitkova/www/build1/index.html .  
Please, note that all the documents are in DRAFT status.) Sphinx takes  
restructuredText (ReST) as source format which has benefits of both a  
smooth learning curve and general simplicity. For example, see http://web.mit.edu/tsitkova/www/build1/krb_admins/conf_files/kdc_conf.html 
  and its source accessible from "Show Source" tab on the right or  
just http://web.mit.edu/tsitkova/www/build1/_sources/krb_admins/conf_files/kdc_conf.txt 
.

As you know, the current Kerberos V5 Administrator's/ User's/ 
Installation guides are in texinfo format. The task of accurate  
housekeeping of texinfo is very hard.  This makes the texinfo  
documentation a logical starting point for translating existing  
documentation into Sphinx format.

The section  "For application developers" http://web.mit.edu/tsitkova/www/build1/krb_appldev/index.html 
  is, obviously, intended for application writers. It has a complete  
reference to the Kerberos API using an experimental bridge to convert  
Doxygen output into Sphinx format. ( See, for example, http://web.mit.edu/tsitkova/www/build1/krb_appldev/refs/api/krb5_build_principal.html 
   ). The "Topics in TODO list"  was compiled based on the short  
survey of the developers and is the subject for revision, extension  
and your kind contributions.   Two topics from this list were "The  
difference between Heimdal and MIT API" and "Principal manipulation  
and parsing" and we've started some coverage on the subjects. Also,  
one can consider these two examples as another demonstration of  
flexibility of Sphinx in the sense of grouping and cross-referencing.

The content of the "For administrators" section is a combination of  
whatever we have in the current "Kerberos V5 System Administrator's  
Guide" (in progress) and various topics on the subjects of   
troubleshooting, etc. Under "Advance topics"  there is also a "TODO"  
list.

Finally, the "For users" section is currently compiled based on  
Kerberos V5 UNIX User's Guide. The document is a re-write in ReST  
format. It is the first step in the direction of the user  
documentation update.

The purpose of this project is not only to collect the Kerberos  
related documents in one place, but also keep them up-to-date,  
complete  and errorless. That is the reason why we plan to  support  
"Feedback" system in one way or another. Currently, almost every page  
has at its bottom link to the email  ( krb5-bugs at mit.edu with pre- 
constructed subject line ) where the feedback on the particular  
document should be sent.

Again, as it was stated before, the documentation will be built  
incrementally.  We will see what works and what doesn't and will  
correct our course as we go.


We plan to store documentation source files under /doc directory.

Thanks,
Zhanna


Zhanna Tsitkova
tsitkova at mit.edu