From: Russ Allbery Date: Fri, 9 Dec 2005 16:43:14 +0000 (+0000) Subject: man-page-readme-20051209 X-Git-Tag: openafs-devel-1_5_0~168 X-Git-Url: https://git.openafs.org/?p=openafs.git;a=commitdiff_plain;h=d60224477f13bbf6a16d9582040e38d539859518 man-page-readme-20051209 Initial documentation for the man page project, including initial notes on conversion, a start at a formatting guide, information on how to contribute, and an initial issues list of things I happened to notice while editing the section one pages. --- diff --git a/doc/man-pages/README b/doc/man-pages/README new file mode 100644 index 0000000..15074a9 --- /dev/null +++ b/doc/man-pages/README @@ -0,0 +1,228 @@ + OpenAFS Man Pages + +Overview + + This directory contains the POD source and (in releases) the generated + man pages for OpenAFS commands and files. The man pages are based on + the original IBM AFS Administration Reference manual, released with the + rest of AFS under the IBM Public License 1.0. They were converted from + HTML to POD, editing, and are currently maintained in POD. + + The man pages are very much a work in progress. The original source + material dated from IBM's public release of AFS, and many changes since + made in OpenAFS are not reflected in the man pages. Help and + contributions are actively solicited. Please see "How You Can Help" + below for more information. + + The long-term goal is for every command shipped with OpenAFS and every + configuration or data file written or read by OpenAFS to have its own + man page. Section one is used for commands that don't require special + privileges, section eight for commands for AFS administrators and local + system administrators, and section five for file formats and + configuration files, with the exception that command suites are kept + together (so, for instance, all fs commands are documented in section + one even though some of them are only usable by a local system + administrator). + + The OpenAFS man pages are discussed on the openafs-doc mailing list at + openafs.org. If you plan on contributing to the man page project, + please join that mailing list and send suggestions, patches, and + contributions there. The coordinator of the OpenAFS man page project is + Russ Allbery ; feel free to contact me directly with + questions (although using the mailing list is generally better and will + probably result in a faster response). + +POD and Man Page Generation + + The OpenAFS man pages are maintained in POD (Plain Old Documentation), + the documentation system originally developed for Perl. This is not an + uncontroversial choice, since POD isn't as rich and full-featured as + other possible alternatives such as Docbook RefEntry. On the other + hand, POD is very close to plain text, can be easier to edit and + maintain for those not familiar with the documentation format, and has + more mature tools for conversion to formatted man pages, an output + format that is particularly important on Unix/Linux. There are many + good arguments either way, and fundamentally the decision was made to + use POD because I prefer it and I'm volunteering to write and edit the + pages and maintain them going forward. + + To convert the POD source to formatted man pages, you need the pod2man + utility. This utility has come with Perl for many years, so if you have + Perl installed, you almost certainly have some version of it available. + For the best results, install Pod::Simple 3.03 or later and podlators + 2.00 or later from CPAN and use that pod2man, but the results from the + pod2man that comes with Perl 5.8 or later will be very good. If you are + using earlier versions of Perl, the output should be adequate and + readable but may contain some formatting glitches. + + Preformatted man pages will be included in distribution tarballs, but + those man pages may be generated with older versions of the conversion + utilities. To regenerate the man pages, run regen.sh at the top of the + OpenAFS source tree (this will also regenerate the Autoconf scripts). + + Conversion to HTML can be done via any of the POD to HTML converters + available (there are many of them). Evaluation of the best tool to use + for OpenAFS and exactly how to do the conversion to get the highest + quality results is still underway; when complete, details will be + included here. + +Formatting Standards + + Each command or configuration file should have a separate man page in a + separate POD file. Command suites (fs, pts, vos, etc.) should have an + overview man page that lists the available subcommands by category, + documents common options, and discusses the general use of the suite. + Then, each operation code in the suite should have a separate man page, + named after the command with the space between the command suite and the + operation code replaced with an underscore. + + All man pages must follow the standard layout for man page sections and + formatting. The best general reference is the pod2man man page, + although the sections used for OpenAFS man pages aren't quite the same + (see below). In particular, please use the following markup: + + * B<> for all commands, command/operation code pairs, and options. + * F<> for file names, directory names, partition names, or paths. + * > for user-provided arguments (note the surrounding <>). + * I<> for terms being defined or titles of works. + * C<> for command examples, ACL characters, and example arguments. + + Also see the afs(1) man page for general rules about how OpenAFS man + pages are formatted and for standard terminology to use when talking + about OpenAFS commands. + + Each man page should have the following sections: NAME, SYNOPSIS (for + commands only), DESCRIPTION, CAUTIONS, OPTIONS (for commands only), + OUTPUT (where appropriate), EXAMPLES, PRIVILEGE REQUIRED (for commands + only), SEE ALSO, and COPYRIGHT, generally in that order. Be sure to + include the IBM copyright in all man pages derived from the original IBM + documentation. If you wrote the man page yourself, please include your + own copyright and a statement that the man page is released under the + IBM Public License Version 1.0, or under some other license that is + sufficiently compatible that we can use your work. If you use another + license and that license isn't "public domain," you have to give the + full license text in the man page; please don't use a license so long + that this is annoying. + + The SYNOPSIS section should start with the full command name and the + full names of all options, and then have a second section showing the + most abbreviated form of the command name and its options. If the + command has aliases, it should have additional sections showing those. + Please be sure to follow all of the formatting requirements for + commands, flags, and options. Enclose optional arguments in [] and + choices in () separated by |. Command names and options are marked up + with B<> as mentioned above; all other literal text that should be + entered on the command line gets no markup. + + References to other OpenAFS man pages should be given as L. + Other man pages should be noted like df(1), without the L<> markup. + References to functions should be noted like function() with the + trailing parens. The POD converters know how to format these sorts of + references appropriately. References to other sections in the same page + should be given as L
. + + Command and output examples should be indented three spaces. Commands + entered by the user should be given on a line beginning with %. If the + command doesn't fit in 80 columns, put in a backslash at a logical break + point and continue the line with an additional four spaces of + indentation. Output examples may be wrapped with an additional four + spaces of indentation but probably shouldn't be; not wrapping makes the + man page look somewhat less readable, but is less confusing when + converted to other formats such as HTML. + + POD does not allow markup in verbatim paragraphs (which are indicated by + indenting the first line of the paragraph), so metasyntactic variables + in examples should be shown like with simple angle brackets + surrounding the variable. For consistency in formatting, references to + those variables should be formatted the same in following text. + +How You Can Help + + The OpenAFS man page project is just starting, and a lot of work remains + to be done. Any and all contributions are greatly appreciated. What + follows is a list of the ways that you can help in order of increasing + helpfulness. If you only have time to do something near the top of the + list, please do; every little bit helps. If you have more time and can + do something closer to the bottom of the list, that's even better and + your contribution can be included more rapidly. + + * Point out places OpenAFS behavior has changed since the documentation + was written, or point out missing documentation. Please check the + "Known Problems" list below to make sure that the item is not already + noted. + + * Point out formatting problems, typos, formatting inconsistency, and + other markup or language problems in the man pages. + + * Provide missing documentation in some form (text, HTML, whatever) + that can be incorporated into the man pages, or detailed explanations + of how the existing documentation needs to be changed to match what + the tools actually do. + + * Provide missing man pages in POD format suitable for immediate + inclusion in the documentation. Please try to follow the formatting + standards documented in the "Formatting Standards" section above, and + look at the existing man pages for examples. + + * Provide patches against the POD source that correct formatting + problems, typos, formatting inconsistencies, or other markup or + language problems with the man pages. + + * Provide patches against the POD source that add or correct the + documentation of commands or file formats for changes in OpenAFS. + + Please send contributions either to the openafs-doc list or as bugs + filed via the bug reporting instructions at . + If you do submit a bug, please send me a note at rra@stanford.edu with + the bug number so that I'm aware of it, as I don't always notice new + bugs. + +Known Problems + + The current man pages have the following known deficiencies. Please + don't just report the deficiency again, but any contributions towards + fixing it are greatly appreciated. + + * The section five and section eight man pages have not yet had an + initial editing pass and many of the section five man pages are + missing because the original reference page names didn't easily + convert to man page names. This is currently being fixed. Please do + not start working on the section five or section eight man pages yet + or bother reporting problems with them; they will be changing + significantly in the near future. + + * The following commands have no man pages: + + fs getcalleraccess + fs getcrypt + fs listaliases + fs newalias + fs rxstatpeer + fs rxstatproc + fs setcbaddr + fs setcrypt + pts interactive + pts quit + pts sleep + pts source + vos changeloc + vos clone + vos convertROtoRW + vos copy + vos shadow + vos size + + * klog.krb, pagsh.krb, and tokens.krb need to be listed as alternative + names in the NAME line of the non-.krb man pages, links should be + installed on man page installation, and the behavior of pagsh.krb + should be documented in the pagsh man page. + + * Some of the documentation in fs getserverprefs needs minor updates to + reflect what happens in the dynroot case. + + * fs sysname documentation needs to include the possibility of setting + multiple sysnames and the resulting behavior. + + If you notice other problems, please send them to the openafs-doc list + even if you don't have time to fix them. Someone else might, and we + want to track all of the issues.