man-page-fileserver-update-20080311
[openafs.git] / doc / xml / AdminReference / preface.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <preface id="Header_2">
3   <title>About This Manual</title>
4
5   <para>This chapter describes the purpose, organization, and conventions of this document.</para>
6
7   <sect1 id="HDRWQ1">
8     <title>Audience and Purpose</title>
9
10     <para>This reference manual details the syntax of each AFS<superscript><superscript>(R)</superscript></superscript> command and
11     is intended for the experienced AFS administrator, programmer, or user.</para>
12
13     <para>In general, this document does not explain when to use a command or its place in the sequence of commands that make up a
14     complete procedure. For that type of information, refer to the <emphasis>IBM AFS Administration Guide</emphasis>.</para>
15   </sect1>
16
17   <sect1 id="HDRWQ2">
18     <title>Organization</title>
19
20     <para>This document presents AFS files and commands in separate sections, with the files or commands in alphabetical
21     order.</para>
22
23     <para>The following sections of each reference page provide the indicated type of information:</para>
24
25     <itemizedlist>
26       <listitem>
27         <para><emphasis role="bold">Purpose</emphasis> briefly describes the command's function.</para>
28       </listitem>
29
30       <listitem>
31         <para><emphasis role="bold">Synopsis</emphasis> displays the complete syntax statement for a command, which specifies the
32         required order for all options, using the same notation as the AFS online help. If abbreviating the command name a nd option
33         names is acceptable, as it is for most commands, a second statement specifies the shortest acceptable abbreviation of each
34         name. If the command has an alias, it also appears in this section.</para>
35       </listitem>
36
37       <listitem>
38         <para><emphasis role="bold">Description</emphasis> describes the file or command's function in detail.</para>
39       </listitem>
40
41       <listitem>
42         <para><emphasis role="bold">Cautions</emphasis> describes restrictions, requirements, and potential complications in use of
43         the command. It appears only when necessary.</para>
44       </listitem>
45
46       <listitem>
47         <para><emphasis role="bold">Options</emphasis> describes the function and required form of each argument and flag.</para>
48       </listitem>
49
50       <listitem>
51         <para><emphasis role="bold">Output</emphasis> describes any output the command writes to the standard output stream. This
52         section does not appear if the command does not produce output or if the only output is a message confirming the command's
53         success.</para>
54       </listitem>
55
56       <listitem>
57         <para><emphasis role="bold">Examples</emphasis> provides one or more sample commands and resulting output.</para>
58       </listitem>
59
60       <listitem>
61         <para><emphasis role="bold">Privilege Required</emphasis> lists each privilege required to perform the command.</para>
62       </listitem>
63
64       <listitem>
65         <para><emphasis role="bold">Related Information</emphasis> lists related commands and files, if any.</para>
66       </listitem>
67     </itemizedlist>
68   </sect1>
69
70   <sect1 id="HDRWQ3">
71     <title>How to Use This Document</title>
72
73     <para>Refer to this document when you need detailed information about a specific command. For a description of all the steps in
74     a procedure, refer to the <emphasis>IBM AFS Administration Guide</emphasis>.</para>
75   </sect1>
76
77   <sect1 id="HDRWQ4">
78     <title>Related Documents</title>
79
80     <para>The following documents are included in the AFS documentation set.</para>
81
82     <para><emphasis>IBM AFS Administration Guide</emphasis></para>
83
84     <para>This guide describes the concepts and procedures that a system administrator must know to manage an AFS cell. It assumes
85     familiarity with UNIX, but requires no previous knowledge of AFS.</para>
86
87     <para>The first chapters of the <emphasis>IBM AFS Administration Guide</emphasis> present basic concepts and guidelines.
88     Understanding them is crucial to successful administration of an AFS cell. The remaining chapters in the guide provide
89     step-by-step instructions for specific administrative tasks, along with discussions of the concepts important to that particular
90     task.</para>
91
92     <para><emphasis>IBM AFS Quick Beginnings</emphasis></para>
93
94     <para>This guide provides instructions for installing AFS server and client machines. It is assumed that the installer is an
95     experienced UNIX<superscript><superscript>(R)</superscript></superscript> system administrator.</para>
96
97     <para>For predictable performance, machines must be installed and configured in accordance with the instructions in this
98     guide.</para>
99
100     <para><emphasis>IBM AFS Release Notes</emphasis></para>
101
102     <para>This document provides information specific to each release of AFS, such as a list of new features and commands, a list of
103     requirements and limitations, and instructions for upgrading server and client machines.</para>
104
105     <para><emphasis>IBM AFS User Guide</emphasis></para>
106
107     <para>This guide presents the basic concepts and procedures necessary for using AFS effectively. It assumes that the reader has
108     some experience with UNIX, but does not require familiarity with networking or AFS.</para>
109
110     <para>The guide explains how to perform basic functions, including authenticating, changing a password, protecting AFS data,
111     creating groups, and troubleshooting. It provides illustrative examples for each function and describes some of the differences
112     between the UNIX file system and AFS.</para>
113   </sect1>
114
115   <sect1 id="HDRTYPO_CONV">
116     <title>Typographical Conventions</title>
117
118     <para>This document uses the following typographical conventions:</para>
119
120     <itemizedlist>
121       <listitem>
122         <para>Command and option names appear in <emphasis role="bold">bold type</emphasis> in syntax definitions, examples, and
123         running text. Names of directories, files, machines, partitions, volumes, and users also appear in <emphasis
124         role="bold">bold type</emphasis>.</para>
125       </listitem>
126
127       <listitem>
128         <para>Variable information appears in <emphasis>italic type</emphasis>. This includes user-supplied information on command
129         lines and the parts of prompts that differ depending on who issues the command. New terms also appear in <emphasis>italic
130         type</emphasis>.</para>
131       </listitem>
132
133       <listitem>
134         <para>Examples of screen output and file contents appear in <computeroutput>monospace type</computeroutput>.</para>
135       </listitem>
136     </itemizedlist>
137
138     <para>In addition, the following symbols appear in command syntax definitions, both in the documentation and in AFS online help
139     statements. When issuing a command, do not type these symbols.</para>
140
141     <itemizedlist>
142       <listitem>
143         <para>Square brackets <emphasis role="bold">[ ]</emphasis> surround optional items.</para>
144       </listitem>
145
146       <listitem>
147         <para>Angle brackets <emphasis role="bold">&lt; &gt;</emphasis> surround user-supplied values in AFS commands.</para>
148       </listitem>
149
150       <listitem>
151         <para>A superscripted plus sign <emphasis role="bold">+</emphasis> follows an argument that accepts more than one
152         value.</para>
153       </listitem>
154
155       <listitem>
156         <para>The percent sign <computeroutput>%</computeroutput> represents the regular command shell prompt. Some operating
157         systems possibly use a different character for this prompt.</para>
158       </listitem>
159
160       <listitem>
161         <para>The number sign <computeroutput>#</computeroutput> represents the command shell prompt for the local superuser
162         <emphasis role="bold">root</emphasis>. Some operating systems possibly use a different character for this prompt.</para>
163       </listitem>
164
165       <listitem>
166         <para>The pipe symbol <emphasis role="bold">|</emphasis> in a command syntax statement separates mutually exclusive values
167         for an argument.</para>
168       </listitem>
169     </itemizedlist>
170   </sect1>
171 </preface>