From: Russ Allbery Date: Thu, 27 May 2010 14:41:38 +0000 (-0500) Subject: Clean up the introduction to the Administration Guide X-Git-Tag: openafs-devel-1_5_75~222 X-Git-Url: http://git.openafs.org/?p=openafs.git;a=commitdiff_plain;h=a65d755e5e862b9077439c151dc238fe4ef62725 Clean up the introduction to the Administration Guide Provide a more useful abstract and remove the (outdated) specific list of supported platforms and the M.m version number placeholders. Update the list of associated documents to match their current titles, and provide a better description of the Reference Manual. Reformat the parent document and preface for easier maintenance in the future. Change-Id: I42ce78274ed7c4ca7a2f0b9c5ec2e6f7a786adb8 Reviewed-on: http://gerrit.openafs.org/2043 Reviewed-by: Derrick Brashear Reviewed-by: Russ Allbery Tested-by: Russ Allbery --- diff --git a/doc/xml/AdminGuide/auagd000.xml b/doc/xml/AdminGuide/auagd000.xml index 1a1faf6..92c1441 100644 --- a/doc/xml/AdminGuide/auagd000.xml +++ b/doc/xml/AdminGuide/auagd000.xml @@ -36,7 +36,7 @@ &version; - + 3.6 @@ -47,19 +47,13 @@ - This edition applies to: - OpenAFS for AIX, Version M.m - OpenAFS for Digital Unix, Version M.m - OpenAFS for HP-UX, Version M.m - OpenAFS for Linux, Version M.m - OpenAFS for SGI IRIX, Version M.m - OpenAFS for Solaris, Version M.m - - - and to all subsequent releases and modifications until otherwise - indicated in new editions.This softcopy version is based on the printed - edition of this book. Some formatting amendments have been made to make - this information more suitable for softcopy. + + This document describes the configuration and maintenance of + OpenAFS from an adminstrator's standpoint. It provides a + conceptual overview of OpenAFS for cell administrators, details on + OpenAFS configuration, and information about managing OpenAFS + servers and clients. + @@ -79,7 +73,7 @@ &chapter4; &chapter5; &chapter6; - &chapter7; + &chapter7; &chapter8; &chapter9; diff --git a/doc/xml/AdminGuide/auagd005.xml b/doc/xml/AdminGuide/auagd005.xml index 748a91b..e26bbfe 100644 --- a/doc/xml/AdminGuide/auagd005.xml +++ b/doc/xml/AdminGuide/auagd005.xml @@ -1,23 +1,31 @@ + About This Guide - This section describes the purpose, organization, and conventions of this document. + This section describes the purpose, organization, and conventions + of this document. Audience and Purpose - This guide describes the concepts and procedures that an AFS(R) system administrator needs to know. It assumes familiarity - with UNIX(R) administration, but no previous knowledge of AFS. + This guide describes the concepts and procedures that an AFS(R) + system administrator needs to know. It assumes familiarity with + UNIX(R) administration, but no previous knowledge of AFS. - This document describes AFS commands in the context of specific tasks. Thus, it does not describe all commands in detail. - Refer to the OpenAFS Administration Reference for detailed command descriptions. + This document describes AFS commands in the context of specific + tasks. Thus, it does not describe all commands in detail. Refer to + the OpenAFS Administration Reference for detailed command + descriptions. Document Organization - This document groups AFS administrative tasks into the following conceptual sections: + + This document groups AFS administrative tasks into the following + conceptual sections: + Concepts and Configuration Issues @@ -33,47 +41,60 @@ Managing Users and Groups - + + - The individual chapters in each section contain the following: + + The individual chapters in each section contain the following: + A chapter overview - A quick reference list of the tasks and commands described in the chapter + A quick reference list of the tasks and commands described + in the chapter - An introduction to concepts that pertain to all of the tasks described in the chapter + An introduction to concepts that pertain to all of the + tasks described in the chapter - A set of sections devoted to specific tasks. Each section begins with a discussion of concepts specific to that - task, followed by step-by-step instructions for performing the task. The instructions are as specific as has been judged - practical. If two related procedures differ from one another in important details, separate sets of instructions are - usually provided. + A set of sections devoted to specific tasks. Each section + begins with a discussion of concepts specific to that task, + followed by step-by-step instructions for performing the + task. The instructions are as specific as has been judged + practical. If two related procedures differ from one another in + important details, separate sets of instructions are usually + provided. - + + How to Use This Document - When you need to perform a specific administrative task, follow these steps: + When you need to perform a specific administrative task, follow + these steps: - Determine if the task concerns file server machines, client machines, or users and groups. Turn to the appropriate - section in this document and then to the appropriate chapter. + Determine if the task concerns file server machines, client + machines, or users and groups. Turn to the appropriate section in + this document and then to the appropriate chapter. - Read or review the general introductory material at the beginning of the chapter. + Read or review the general introductory material at the + beginning of the chapter. - Read or review the introductory material concerning the specific task you wish to perform. + Read or review the introductory material concerning the + specific task you wish to perform. @@ -81,68 +102,99 @@ - If necessary, refer to the OpenAFS Administration Reference for more detailed information about the commands. + If necessary, refer to the OpenAFS Administration Reference + for more detailed information about the commands. - + Related Documents - The following documents are also included in the AFS documentation set. - + The following documents are also included in the AFS + documentation set. - OpenAFS Administration Reference + OpenAFS Quick Start Guide - This reference manual details the syntax and effect of each AFS command. It is intended for the experienced AFS - administrator, programmer, or user. The OpenAFS Administration Reference lists AFS files and commands in alphabetical - order. The reference page for each command specifies its syntax, including the acceptable aliases and abbreviations. It - then describes the command's function, arguments, and output if any. Examples and a list of related commands are provided, - as are warnings where appropriate. - - This manual complements the OpenAFS Administration Guide: it does not include procedural information, but describes - commands in more detail than the OpenAFS Administration Guide. + + This guide provides instructions for installing AFS server and + client machines. It is assumed that the installer is an + experienced UNIX(R) system administrator. + + + + For predictable performance, machines must be installed and + configured in accordance with the instructions in this guide. + - OpenAFS Quick Beginnings + OpenAFS User Guide - This guide provides instructions for installing AFS server and client machines. It is assumed that the installer is - an experienced UNIX(R) system administrator. - - For predictable performance, machines must be installed and configured in accordance with the instructions in this - guide. + + This guide presents the basic concepts and procedures + necessary for using AFS effectively. It assumes that the + reader has some experience with UNIX, but does not require + familiarity with networking or AFS. + + + + The guide explains how to perform basic functions, including + authenticating, changing a password, protecting AFS data, + creating groups, and troubleshooting. It provides illustrative + examples for each function and describes some of the + differences between the UNIX file system and AFS. + - OpenAFS Release Notes + OpenAFS Reference Manual - This document provides information specific to each release of AFS, such as a list of new features and commands, a - list of requirements and limitations, and instructions for upgrading server and client machines. + + This reference manual details the syntax and effect of each + AFS command. It is intended for the experienced AFS + administrator, programmer, or user. It contains a reference + page for each command or file specifying its syntax, including + the acceptable aliases and abbreviations. It then describes + the command's function, arguments, and output if any. Examples + and a list of related commands are provided, as are warnings + where appropriate. + + + + This manual complements the OpenAFS Administration Guide: it + does not include procedural information, but describes + commands in more detail than the OpenAFS Administration Guide. + + + + The OpenAFS Reference Manual is provided in the form of + UNIX(R) manual pages and as HTML pages. + - OpenAFS User Guide + OpenAFS for Windows Release Notes - This guide presents the basic concepts and procedures necessary for using AFS effectively. It assumes that the - reader has some experience with UNIX, but does not require familiarity with networking or AFS. - - The guide explains how to perform basic functions, including authenticating, changing a password, protecting AFS - data, creating groups, and troubleshooting. It provides illustrative examples for each function and describes some of the - differences between the UNIX file system and AFS. + + This document provides a series of usage notes regarding the + OpenAFS for Windows client, supported platforms, contribution + information, debugging techniques, and a reference to + supported Windows registry values. + - + @@ -152,56 +204,78 @@ - Command and option names appear in bold type in syntax definitions, examples, and - running text. Names of directories, files, machines, partitions, volumes, and users also appear in bold type. + + Command and option names appear in bold + type in syntax definitions, examples, and running + text. Names of directories, files, machines, partitions, + volumes, and users also appear in bold + type. + - Variable information appears in italic type. This includes user-supplied information on command - lines and the parts of prompts that differ depending on who issues the command. New terms also appear in italic - type. + + Variable information appears in italic + type. This includes user-supplied information on + command lines and the parts of prompts that differ depending on + who issues the command. New terms also appear in + italic type. + - Examples of screen output and file contents appear in monospace type. + + Examples of screen output and file contents appear in + monospace type. + - + - In addition, the following symbols appear in command syntax definitions, both in the documentation and in AFS online help - statements. When issuing a command, do not type these symbols. - - Square brackets [ ] surround optional items. - + In addition, the following symbols appear in command syntax + definitions, both in the documentation and in AFS online help + statements. When issuing a command, do not type these + symbols. + + + Square brackets [ ] + surround optional items. + - - Angle brackets < > surround user-supplied values in AFS commands. - + + Angle brackets < > + surround user-supplied values in AFS commands. + - - A superscripted plus sign + follows an argument that accepts more than one - value. - + + A superscripted plus sign + + follows an argument that accepts more than one value. + - - The percent sign % represents the regular command shell prompt. Some operating systems possibly use a different - character for this prompt. - + + The percent sign % + represents the regular command shell prompt. Some operating + systems possibly use a different character for this prompt. + - - The number sign # represents the command shell prompt for the local superuser root. - Some operating systems possibly use a different character for this prompt. - + + The number sign # + represents the command shell prompt for the local superuser + root. Some operating systems + possibly use a different character for this prompt. + - - The pipe symbol | in a command syntax statement separates mutually exclusive values - for an argument. - - + + The pipe symbol | in a + command syntax statement separates mutually exclusive values for + an argument. + + + - For additional information on AFS commands, including a description of command string components, acceptable abbreviations - and aliases, and how to get online help for commands, see Appendix B, Using AFS - Commands. + For additional information on AFS commands, including a + description of command string components, acceptable abbreviations and + aliases, and how to get online help for commands, see Appendix B, Using AFS Commands.