[OpenAFS] Documentation - again

[ted creedon]

Suffice it to say I can always make pdf's from html's so the source format
(Latex, docbook) is not too relevant to a pdf specific deliverable.

In terms of direction I think we need:

1. An Operation and Maintenance Manual - The semantics of AFS are only
covered in Campbell's book which is out of print. A new book is needed.
In particular:
A. Large and small installation examples need to be added.
B. Jeff Alberry's perl administration tools need to be included.
C. Ken Hornstein's Kerberos 5 conversion needs slight updating and inclusion
D. The existing kaserver (KRB 4) needs to be depreciated and replaced with
KRB 5.
E. Building AFS from sources needs to be added, including appropriate KRB5
material.

2. The syntax which is well covered in the IBM docs needs updating.

3. It is a requirement that the style follow the IBM "Typographical
Conventions" in the front of each manual. The conventions do not specify
what is to be hyperlinked or indexed.

4. The Latex version has some hyperlinking but it is not as extensive as the
IBM htm's. The Latex version does not support indexing although it could
with yet more perl scripting. 

Note: The IBM indexing is 2 or 3 levels deep, i.e. subject, sub-subject,
subsub-subject. This needs a project in itself to implement.

I recommend getting the textual part of any additions & improvements done
first, we need content ASAP.

If we wait for the perfect embodiment of the sources in Latex or DocBook,
nothing will ever get done.

tedc



-----Original Message-----
From: openafs-info-admin@openafs.org [mailto:openafs-info-admin@openafs.org]
On Behalf Of Jeffrey Altman
Sent: Monday, July 18, 2005 8:19 PM
To: Michael Norwick
Cc: OpenAFS-Info
Subject: Re: [OpenAFS] Documentation - again

Michael:

The documentation project is being run by Esther <mizmoose@gmail.com>.
There is a mailing list dedicated to the effort.  You can subscribe and view
the archives at:

	https://lists.openafs.org/mailman/listinfo/openafs-doc

There is a cvs tree with the IBM sources.   Currently the focus is on
determining which of the various source formats will support all of the
desired outputs while still providing a significant ease of use.   Once
the sources to the documents are brought current it must be possible for the
developers to make changes easily.  Otherwise, the documentation simply will
not get updated in a timely manner.

If you can contribute to the evaluation, that would be quite helpful.

Jeffrey Altman


Michael Norwick wrote:

> Well,
> 
> No word yet on what if anything needs to be done for AFS documentation. 
> I am willing to give DocBook a whirl if it is deemed needed or 
> acceptable by the group.  I am trying to trash
> FC4 test 3 on a server right now but I could begin as soon as I get 
> this thing back up under Debian stable, have access to the docs, and a 
> sense of direction i.e. 'a clue'.
> I've considered the depth and breadth of the IBM/Transarc docs but we 
> have to start somewhere.  Or, maybe I don't have to eat the whole 
> elephant in one sitting.  Let me know what you want, or, I could just 
> go and play with the
> NFSv4 people.
> 
> Good Day,
> Michael
> _______________________________________________
> OpenAFS-info mailing list
> OpenAFS-info@openafs.org
> https://lists.openafs.org/mailman/listinfo/openafs-info