doc/xml/AdminRef/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 OpenAFS 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>OpenAFS Administration Guide</emphasis>.</para>
  15   </sect1>
  16
  17   <sect1 id="HDRWQ2">
  18     <title>Organization</title>
  19
  20     <para>This document presents OpenAFS 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 OpenAFS 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>OpenAFS 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 OpenAFS documentation set.</para>
  81
  82     <para><emphasis>OpenAFS 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>OpenAFS 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>OpenAFS Quick Beginnings</emphasis></para>
  93
  94     <para>This guide provides instructions for installing OpenAFS 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>OpenAFS Release Notes</emphasis></para>
 101
 102     <para>This document provides information specific to each release of OpenAFS, 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>OpenAFS 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 OpenAFS 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 OpenAFS 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>