Hello everyone, I'm sending this to openafs-devel as well as openafs-doc since I'm not sure if everyone who's interested is on openafs-doc. Further messages on this subject will go only to openafs-doc, so those of you who want to see the discussion should join that mailing list.
I've committed to the trunk the initial conversion of the AFS Administration Reference to POD, and have completed a hand edit of all of the section one man pages to clean up various formatting issues and inconsistencies. (For all the vaunted benefits of professional documentation writers, and indeed the documentation is wonderfully complete, the existing HTML pages are rather inconsistent about formatting and markup.) This editing pass for formatting and markup took me about a day for the section one man pages, so I expect there are two days of editing left to be done. My goal is to get that work done by the 16th. The POD source is converted to formatted man pages as part of running regen.sh so that consumers of release tarballs won't have to have pod2man available to get man pages. The quality of the conversion should be adequate for any version of Perl released in the past five years, but for best results you want to use pod2man that comes with Perl 5.8 or later, or alternately install Pod::Simple 3.03 (or later) and podlators 2.00 (or later) from CPAN before running regen.sh. The section one man pages should now be in reasonable shape and are ready for general review. I'll be sending out the README in a moment which explains known issues and how to contribute. For right now, if you want to review the man pages, you need to check out the OpenAFS trunk from CVS; this will change in the future (see below). Please do not bother looking at the section five and section eight man pages yet. What's in CVS is an initial starting point after an automated conversion and needs significant cleanup work to be even adequate. I'm currently working on this and will send out another message when it's done. The breakdown of man pages between sections is somewhat arbitrary, particularly since I wanted to keep command suites together. Yes, vos is in section one and bos is in section eight and this doesn't necessarily make a tremendous amount of sense. If someone comes up with a clear guideline for what should go where, I'm all ears; in the meantime, this seemed vaguely reasonable, and we can always move commands later. Unfortunately, where OpenAFS itself installs commands (bin or etc or root.server) also needs to be reviewed and isn't a particularly great guide. The current next steps are: * Finish the editing on section five and section eight. * Evaluate the available HTML converters and find the one that does the best job. Develop a recipe for good HTML conversion and publish it. * Publish an HTML copy of all of the man pages for easier public review. * Invite public review of all of the man pages. * Ongoing: Respond to the results of public review, committing contributions and trying to fix problems. If you're comfortable with CVS and reviewing man pages, please feel free to check out the current trunk, run regen.sh to generate the man pages, and start looking at the section one man pages and sending patches, corrections, additional documentation, or problem reports to openafs-doc. Please be aware that I'm going to finish the first editing pass on all the man pages before responding to any review results on the section one man pages, but I will be keeping all of those messages and promise that I'll get to them. If you'd rather review HTML pages, please wait for now. As mentioned above, that's coming. If you're annoyed by POD and really want to edit Docbook, please help with the Docbook conversion of the *other* reference manuals, which need just as much attention, if not more, than the man pages do. Currently, this work is only on the trunk, but provided that I make the progress I expect to, it's targetted for 1.4.2. I'm keeping track of the trunk deltas and plan on pulling them all up to the stable branch as soon as I've finished the first comprehensive editing pass and I'm confident that the results won't be too embarassing. -- Russ Allbery ([EMAIL PROTECTED]) <http://www.eyrie.org/~eagle/> _______________________________________________ OpenAFS-devel mailing list [email protected] https://lists.openafs.org/mailman/listinfo/openafs-devel
