Commit | Line | Data |
---|---|---|
805e021f CE |
1 | OpenAFS Man Pages |
2 | ||
3 | Overview | |
4 | ||
5 | This directory contains the POD source and (in releases) the generated | |
6 | man pages for OpenAFS commands and files. The man pages are based on | |
7 | the original IBM AFS Administration Reference manual, released with the | |
8 | rest of AFS under the IBM Public License 1.0. They were converted from | |
9 | HTML to POD, editing, and are currently maintained in POD. | |
10 | ||
11 | The man pages are very much a work in progress. The original source | |
12 | material dated from IBM's public release of AFS, and many changes since | |
13 | made in OpenAFS are not reflected in the man pages. Help and | |
14 | contributions are actively solicited. Please see "How You Can Help" | |
15 | below for more information. | |
16 | ||
17 | The long-term goal is for every command shipped with OpenAFS and every | |
18 | configuration or data file written or read by OpenAFS to have its own | |
19 | man page. Section one is used for commands that don't require special | |
20 | privileges, section eight for commands for AFS administrators and local | |
21 | system administrators, and section five for file formats and | |
22 | configuration files, with the exception that command suites are kept | |
23 | together (so, for instance, all fs commands are documented in section | |
24 | one even though some of them are only usable by a local system | |
25 | administrator). | |
26 | ||
27 | The OpenAFS man pages are discussed on the openafs-doc mailing list at | |
28 | openafs.org. If you plan on contributing to the man page project, | |
29 | please join that mailing list and send suggestions, patches*, and | |
30 | contributions there. The coordinator of the OpenAFS man page project is | |
31 | Russ Allbery <rra@stanford.edu>; feel free to contact me directly with | |
32 | questions (although using the mailing list is generally better and will | |
33 | probably result in a faster response). | |
34 | ||
35 | * Although we still accept patch submissions to the list, it is | |
36 | greatly preferred that you make your submission through Git to | |
37 | the OpenAFS Gerrit instance (code review system). Information | |
38 | can be found at <http://wiki.openafs.org/GitDevelopers/> | |
39 | ||
40 | POD and Man Page Generation | |
41 | ||
42 | The OpenAFS man pages are maintained in POD (Plain Old Documentation), | |
43 | the documentation system originally developed for Perl. This is not an | |
44 | uncontroversial choice, since POD isn't as rich and full-featured as | |
45 | other possible alternatives such as Docbook RefEntry. On the other | |
46 | hand, POD is very close to plain text, can be easier to edit and | |
47 | maintain for those not familiar with the documentation format, and has | |
48 | more mature tools for conversion to formatted man pages, an output | |
49 | format that is particularly important on Unix/Linux. There are many | |
50 | good arguments either way, and fundamentally the decision was made to | |
51 | use POD because I prefer it and I'm volunteering to write and edit the | |
52 | pages and maintain them going forward. | |
53 | ||
54 | To convert the POD source to formatted man pages, you need the pod2man | |
55 | utility. This utility has come with Perl for many years, so if you have | |
56 | Perl installed, you almost certainly have some version of it available. | |
57 | For the best results, install Pod::Simple 3.03 or later and podlators | |
58 | 2.00 or later from CPAN and use that pod2man, but the results from the | |
59 | pod2man that comes with Perl 5.8 or later will be very good. If you are | |
60 | using earlier versions of Perl, the output should be adequate and | |
61 | readable but may contain some formatting glitches. | |
62 | ||
63 | Preformatted man pages will be included in distribution tarballs, but | |
64 | those man pages may be generated with older versions of the conversion | |
65 | utilities. To regenerate the man pages, run regen.sh at the top of the | |
66 | OpenAFS source tree (this will also regenerate the Autoconf scripts). | |
67 | ||
68 | Conversion to HTML can be done via any of the POD to HTML converters | |
69 | available (there are many of them), but for best results (particularly | |
70 | for crosslinks), use the generate-html script in this directory. You | |
71 | will need to have the Pod::Simple Perl module installed. If your Perl | |
72 | is not in /usr/bin, run generate-html explicitly with: | |
73 | ||
74 | perl generate-html | |
75 | ||
76 | It will generate HTML pages in the html subdirectory of this directory. | |
77 | ||
78 | Formatting Standards | |
79 | ||
80 | Each command or configuration file should have a separate man page in a | |
81 | separate POD file. Command suites (fs, pts, vos, etc.) should have an | |
82 | overview man page that lists the available subcommands by category, | |
83 | documents common options, and discusses the general use of the suite. | |
84 | Then, each operation code in the suite should have a separate man page, | |
85 | named after the command with the space between the command suite and the | |
86 | operation code replaced with an underscore. The NAME section of the | |
87 | operation man page must also use an underscore (fs_listacl, not fs | |
88 | listacl) for compatibility with some man programs. The SYNOPSIS section | |
89 | should, of course, use a space, since that's what the user must type. | |
90 | ||
91 | All man pages must follow the standard layout for man page sections and | |
92 | formatting. The best general reference is the pod2man man page, | |
93 | although the sections used for OpenAFS man pages aren't quite the same | |
94 | (see below). In particular, please use the following markup: | |
95 | ||
96 | * B<> for all commands, command/operation code pairs, and options. | |
97 | * F<> for file names, directory names, partition names, or paths. | |
98 | * <I<>> for user-provided arguments (note the surrounding <>). | |
99 | * I<> for terms being defined or titles of works. | |
100 | * C<> for command examples, ACL characters, and example arguments. | |
101 | * S<<<>>> for text with non-breaking spaces (usually in synopsis). | |
102 | ||
103 | Also see the afs(1) man page for general rules about how OpenAFS man | |
104 | pages are formatted and for standard terminology to use when talking | |
105 | about OpenAFS commands. | |
106 | ||
107 | Each man page should have the following sections: NAME, SYNOPSIS (for | |
108 | commands only), DESCRIPTION, CAUTIONS, OPTIONS (for commands only), | |
109 | OUTPUT (where appropriate), EXAMPLES, PRIVILEGE REQUIRED (for commands | |
110 | only), SEE ALSO, and COPYRIGHT, generally in that order. Be sure to | |
111 | include the IBM copyright in all man pages derived from the original IBM | |
112 | documentation. If you wrote the man page yourself, please include your | |
113 | own copyright and a statement that the man page is released under the | |
114 | IBM Public License Version 1.0, or under some other license that is | |
115 | sufficiently compatible that we can use your work. If you use another | |
116 | license and that license isn't "public domain" or one of the ones | |
117 | already listed in our LICENSE file, you have to give the full license | |
118 | text in the man page; please don't use a license so long that this is | |
119 | annoying. | |
120 | ||
121 | The SYNOPSIS section should start with the full command name and the | |
122 | full names of all options, and then have a second section showing the | |
123 | most abbreviated form of the command name and its options. If the | |
124 | command has aliases, it should have additional sections showing those. | |
125 | Please be sure to follow all of the formatting requirements for | |
126 | commands, flags, and options. Enclose optional arguments in [] and | |
127 | choices in () separated by |. Command names and options are marked up | |
128 | with B<> as mentioned above; all other literal text that should be | |
129 | entered on the command line gets no markup. | |
130 | ||
131 | References to other OpenAFS man pages should be given as L<afs(1)>. | |
132 | Other man pages should be noted like df(1), without the L<> markup. | |
133 | References to functions should be noted like function() with the | |
134 | trailing parens. The POD converters know how to format these sorts of | |
135 | references appropriately. References to other sections in the same page | |
136 | should be given as L<SECTION>. Man pages for all other AFS commands or | |
137 | file formats referenced in the page should be listed in the SYNOPSIS. | |
138 | List each reference on its own line for easier addition of other | |
139 | references later, but don't put blank lines between them. Don't forget | |
140 | the commas at the end of each line but the last. | |
141 | ||
142 | Command and output examples should be indented three spaces. Commands | |
143 | entered by the user should be given on a line beginning with %. If the | |
144 | command doesn't fit in 80 columns, put in a backslash at a logical break | |
145 | point and continue the line with an additional four spaces of | |
146 | indentation. Output examples may be wrapped with an additional four | |
147 | spaces of indentation but probably shouldn't be; not wrapping makes the | |
148 | man page look somewhat less readable, but is less confusing when | |
149 | converted to other formats such as HTML. | |
150 | ||
151 | POD does not allow markup in verbatim paragraphs (which are indicated by | |
152 | indenting the first line of the paragraph), so metasyntactic variables | |
153 | in examples should be shown like <this> with simple angle brackets | |
154 | surrounding the variable. For consistency in formatting, references to | |
155 | those variables should be formatted the same in following text. | |
156 | ||
157 | Man Page Sections | |
158 | ||
159 | The section of a man page is determined by which directory it's in. | |
160 | pod1 will be section 1 man pages, pod3 will be section 3, pod5 will be | |
161 | section 5, and pod8 will be section 8. | |
162 | ||
163 | The breakdown between section 1 and section 8 is fuzzy and it's hard to | |
164 | get right. The current layout balances the following goals: | |
165 | ||
166 | * In general, section 1 is used for commands that can be executed by any | |
167 | user and section 8 is used for commands that can only be meaningfully | |
168 | issued as root. If a command can be run with AFS privileged | |
169 | credentials but still as a regular user on the local system, the | |
170 | preference is for it to be in section 1, although some pages of that | |
171 | type are in section 8. | |
172 | ||
173 | * All the commands for a given suite should be kept together. So, for | |
174 | example, there are fs commands that can only be issued as root, but | |
175 | since most of the suite is available to any user, all of the fs | |
176 | commands are in section 1. | |
177 | ||
178 | * The sections of the man pages should roughly correspond to the | |
179 | installation paths of the binaries. Binaries installed in bin should | |
180 | have man pages in section 1 and binaries installed in sbin should have | |
181 | man pages in section 8. | |
182 | ||
183 | Section 5 should be used for all documentation of configuration files | |
184 | and file formats. | |
185 | ||
186 | How You Can Help | |
187 | ||
188 | A lot of work remains to be done on the OpenAFS man page project. Any | |
189 | and all contributions are greatly appreciated. What follows is a list | |
190 | of the ways that you can help in order of increasing helpfulness. If | |
191 | you only have time to do something near the top of the list, please do; | |
192 | every little bit helps. If you have more time and can do something | |
193 | closer to the bottom of the list, that's even better and your | |
194 | contribution can be included more rapidly. | |
195 | ||
196 | * Point out places OpenAFS behavior has changed since the documentation | |
197 | was written, or point out missing documentation. Please check the | |
198 | "Known Problems" list below to make sure that the item is not already | |
199 | noted. | |
200 | ||
201 | * Point out formatting problems, typos, formatting inconsistency, and | |
202 | other markup or language problems in the man pages. | |
203 | ||
204 | * Provide missing documentation in some form (text, HTML, whatever) | |
205 | that can be incorporated into the man pages, or detailed explanations | |
206 | of how the existing documentation needs to be changed to match what | |
207 | the tools actually do. | |
208 | ||
209 | * Provide missing man pages in POD format suitable for immediate | |
210 | inclusion in the documentation. Please try to follow the formatting | |
211 | standards documented in the "Formatting Standards" section above, and | |
212 | look at the existing man pages for examples. | |
213 | ||
214 | * Provide patches against the POD source that correct formatting | |
215 | problems, typos, formatting inconsistencies, or other markup or | |
216 | language problems with the man pages. | |
217 | ||
218 | * Provide patches against the POD source that add or correct the | |
219 | documentation of commands or file formats for changes in OpenAFS. | |
220 | ||
221 | Please submit contributions to Gerrit or send them either to the | |
222 | openafs-doc list or as bugs filed via the bug reporting instructions at | |
223 | <http://www.openafs.org/>. If you do submit a bug, please send me a | |
224 | note at rra@stanford.edu with the bug number so that I'm aware of it, as | |
225 | I don't always notice new bugs. | |
226 | ||
227 | You can test your new POD documentation by running the check-pod script | |
228 | in this directory with "prove check-pod". (And check other people's | |
229 | documentation and find any problems that have crept in.) You will need | |
230 | to have Test::Pod installed. | |
231 | ||
232 | Known Problems | |
233 | ||
234 | The current man pages have the following known deficiencies. Please | |
235 | don't just report the deficiency again, but any contributions towards | |
236 | fixing it are greatly appreciated. | |
237 | ||
238 | * We need a way to add links to other man pages (kinit most notably) | |
239 | without creating dangling links in the HTML output. This probably | |
240 | means that the HTML conversion script needs to generate at startup | |
241 | a list of all valid man page link targets and not linkify the ones | |
242 | that don't match a valid target. | |
243 | ||
244 | * Provide a way to substitute the correct paths into the HTML output | |
245 | from Autoconf results. | |
246 | ||
247 | * Review the sections used for all man pages against what directories | |
248 | the commands are installed into. (In some cases, it may be better to | |
249 | change the directory than the section of the man page.) | |
250 | ||
251 | * Consider using M4 or similar to operate on POD text before output. | |
252 | This would allow common options like vos -c,-noa,-l,-v,-e,-nor to be | |
253 | documented once and automatically included in all vos_ reference | |
254 | pages, much like the vos.c source includes those arguments as | |
255 | COMMONPARMS. | |
256 | ||
257 | * Check that suite intro pages mention all subcommands | |
258 | ||
259 | Changes needed to have vos suite commands completely up to date, | |
260 | including the 1.5 branch: | |
261 | ||
262 | * Document vos create -minquota which is available since 1.5.61 | |
263 | ||
264 | * Document vos restore -creation/-lastupdate and -nodelete | |
265 | ||
266 | Man section 8 suite commands: | |
267 | ||
268 | * Mention bos (un)blockscanner in bos.pod text, not just in See Also | |
269 | at the end | |
270 | ||
271 | * Update backup source to include option descriptions (for content, | |
272 | use existing manpage information "condensed" to half line of text) | |
273 | ||
274 | * Document backup deletedump -port/-groupid/-dbonly/-force/-noexecute | |
275 | ||
276 | * Document backup help -admin | |
277 | ||
278 | * Document backup volrestore -usedump. | |
279 | ||
280 | If you notice other problems, please send them to the openafs-doc list | |
281 | even if you don't have time to fix them. Someone else might, and we | |
282 | want to track all of the issues. |