[svnbook commit] r3157 - trunk/src/en/book

cmpilato noreply at red-bean.com
Fri Jun 20 22:42:37 CDT 2008


Author: cmpilato
Date: Fri Jun 20 22:42:37 2008
New Revision: 3157

Log:
* src/en/book/ch09-reference.xml
  Describe so-called global 'svn' options separately.  Fix the
  descriptions of --no-auth-cache to imply that creds are cached in
  the runtime configuration area, not the admistrative areas.  Tweak
  descriptions of --non-interactive, --username, and --password, too.
  Remove global options from individual subcommand listing.


Modified:
   trunk/src/en/book/ch09-reference.xml

Modified: trunk/src/en/book/ch09-reference.xml
==============================================================================
--- trunk/src/en/book/ch09-reference.xml	(original)
+++ trunk/src/en/book/ch09-reference.xml	Fri Jun 20 22:42:37 2008
@@ -42,13 +42,87 @@
       <title><command>svn</command> Options</title> 
       
       <para>While Subversion has different options for its
-        subcommands, all options are global—that is, each
-        option is guaranteed to mean the same thing regardless of
-        the subcommand you use it with.  For example,
-        <option>--verbose</option> (<option>-v</option>) always
-        means <quote>verbose output,</quote> regardless of the
+        subcommands, all options exist in a single
+        namespace—that is, each option is guaranteed to mean the
+        same thing regardless of the subcommand you use it with.  For
+        example, <option>--verbose</option> (<option>-v</option>)
+        always means <quote>verbose output,</quote> regardless of the
         subcommand you use it with.</para>
 
+      <para>The <command>svn</command> command-line client usually
+        exits quickly with an error if you pass it an option which
+        does not apply to the specified subcommand.  But as of
+        Subversion 1.5, several of the options which apply to
+        all—or nearly all—of the subcommands have been
+        deemed acceptable by all subcommands, even if they have no
+        effect upon some of them.  They appear grouped together in the
+        command-line client's usage messages as global options.  This
+        was done to assist folks who write scripts which wrap the
+        command-line client.  These global options are as
+        follows:</para>
+        
+      <variablelist>
+
+        <varlistentry>
+          <term><option>--config-dir</option>
+            <replaceable>DIR</replaceable></term>
+          <listitem>
+            <para>Instructs Subversion to read configuration
+              information from the specified directory instead of the
+              default location (<filename>.subversion</filename> in
+              the user's home directory).</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><option>--no-auth-cache</option></term>
+          <listitem>
+            <para>Prevents caching of authentication information
+              (e.g., username and password) in the Subversion
+              runtime configuration directories.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><option>--non-interactive</option></term>
+          <listitem>
+            <para>Disables all interactive prompting.  Some examples
+              of interactive prompting include requests for
+              authentication credentials and conflict resolution
+              decisions.  This is useful if you're running Subversion
+              inside of an automated script and it's more appropriate
+              to have Subversion fail than to prompt for more
+              information.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><option>--password</option>
+            <replaceable>PASSWD</replaceable></term>
+          <listitem>
+            <para>Specifies the password to use when authenticating
+              against a Subversion server.  If not provided, or if
+              incorrect, Subversion will prompt you for this
+              information as needed.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><option>--username</option>
+            <replaceable>NAME</replaceable></term>
+          <listitem>
+            <para>Specifies the username to use when authenticating
+              against a Subversion server.  If not provided, or if
+              incorrect, Subversion will prompt you for this
+              information as needed.</para>
+          </listitem>
+        </varlistentry>
+        
+      </variablelist>
+
+      <para>The rest of the options apply and are accepted by only a
+        subset of the subcommand.  They are as follows:</para>
+
       <variablelist>
         
         <varlistentry>
@@ -102,17 +176,6 @@
         </varlistentry>
 
         <varlistentry>
-          <term><option>--config-dir</option>
-            <replaceable>DIR</replaceable></term>
-          <listitem>
-            <para>Instructs Subversion to read configuration
-              information from the specified directory instead of the
-              default location (<filename>.subversion</filename> in
-              the user's home directory).</para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry>
           <term><option>--depth</option>
             <replaceable>ARG</replaceable></term>
           <listitem>
@@ -332,15 +395,6 @@
         </varlistentry>
       
         <varlistentry>
-          <term><option>--no-auth-cache</option></term>
-          <listitem>
-            <para>Prevents caching of authentication information
-              (e.g., username and password) in the Subversion
-              administrative directories.</para>
-          </listitem>
-        </varlistentry>
-      
-        <varlistentry>
           <term><option>--no-auto-props</option></term>
           <listitem>
             <para>Disables auto-props, overriding the
@@ -384,18 +438,6 @@
         </varlistentry>
 
         <varlistentry>
-          <term><option>--non-interactive</option></term>
-          <listitem>
-            <para>In the case of an authentication failure or
-              insufficient credentials, prevents prompting for
-              credentials (e.g., username or password).  This is useful
-              if you're running Subversion inside of an automated
-              script, and it's more appropriate to have Subversion fail
-              than to prompt for more information.</para>
-          </listitem>
-        </varlistentry>
-      
-        <varlistentry>
           <term><option>--non-recursive</option> (<option>-N</option>)</term>
           <listitem>
             <para><emphasis>Deprecated</emphasis>.  Stops a subcommand
@@ -435,17 +477,6 @@
         </varlistentry>
 
         <varlistentry>
-          <term><option>--password</option>
-            <replaceable>PASS</replaceable></term>
-          <listitem>
-            <para>Indicates that you are providing your password for
-              authentication on the command line—otherwise, if
-              it is needed, Subversion will prompt you for
-              it.</para>
-          </listitem>
-        </varlistentry>
-      
-        <varlistentry>
           <term><option>--quiet</option> (<option>-q</option>)</term>
           <listitem>
             <para>Requests that the client print only essential
@@ -464,9 +495,8 @@
         <varlistentry>
           <term><option>--recursive</option> (<option>-R</option>)</term>
           <listitem>
-            <para><emphasis>Deprecated</emphasis>.  Makes a subcommand
-              recurse into subdirectories.  Most subcommands recurse
-              by default.</para>
+            <para>Makes a subcommand recurse into subdirectories.
+              Most subcommands recurse by default.</para>
           </listitem>
         </varlistentry>
         
@@ -597,17 +627,6 @@
         </varlistentry>
         
         <varlistentry>
-          <term><option>--username</option>
-            <replaceable>NAME</replaceable></term>
-          <listitem>
-            <para>Indicates that you are providing your username for
-              authentication on the command line—otherwise, if
-              it is needed, Subversion will prompt you for
-              it.</para>
-          </listitem>
-        </varlistentry>
-        
-        <varlistentry>
           <term><option>--use-merge-history</option>
             (<option>-g</option>)</term>
           <listitem>
@@ -677,7 +696,10 @@
     <sect2 id="svn.ref.svn.c">
       <title><command>svn</command> Subcommands</title>
 
-      <para>Here are the various subcommands.</para>
+      <para>Here are the various subcommands.  For the sake of
+        brevity, we omit the global options (described in <xref
+        linkend="svn.ref.svn.sw" />) from the subcommand descriptions
+        which follow.</para>
 
       <refentry id="svn.ref.svn.c.add">
 
@@ -729,7 +751,6 @@
           <screen>
 --targets FILENAME
 --quiet (-q)
---config-dir DIR
 --no-ignore
 --auto-props
 --no-auto-props
@@ -841,11 +862,6 @@
 --extensions (-x) ARG
 --force
 --use-merge-history(-g)
---username ARG
---password ARG
---no-auth-cache
---non-interactive
---config-dir ARG
 </screen>
 
 <!--
@@ -975,11 +991,6 @@
 
           <screen>
 --revision (-r) REV
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -1066,7 +1077,6 @@
 --depth ARG
 --targets ARG
 --changelist ARG
---config-dir ARG
 </screen>
         </refsect1>
 
@@ -1162,12 +1172,7 @@
 --quiet (-q)
 --depth ARG
 --force
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --ignore-externals
---config-dir DIR
 </screen>
         </refsect1>
         
@@ -1318,7 +1323,6 @@
 
           <screen>
 --diff3-cmd CMD
---config-dir DIR
 </screen>
 
         </refsect1>
@@ -1416,12 +1420,7 @@
 --force-log
 --depth ARG
 --with-revprop ARG
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --encoding ENC
---config-dir DIR
 --changelist ARG
 --keep-changelist
 </screen>
@@ -1591,14 +1590,9 @@
 --quiet (-q)
 --parents
 --with-revprop ARG
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --force-log
 --editor-cmd EDITOR
 --encoding ENC
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -1757,13 +1751,8 @@
 --targets FILENAME
 --with-revprop ARG
 --keep-local
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --editor-cmd EDITOR
 --encoding ENC
---config-dir DIR
 </screen>
         </refsect1>
         
@@ -1996,11 +1985,6 @@
 --notice-ancestry
 --summarize
 --force
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 --changelist ARG
 --xml
 </screen>
@@ -2201,12 +2185,7 @@
 --revision (-r) REV
 --quiet (-q)
 --force
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --depth ARG
---config-dir DIR
 --native-eol EOL
 --ignore-externals
 </screen>
@@ -2307,7 +2286,6 @@
           <title>Options</title>
 
           <screen>
---config-dir DIR
 </screen>
         </refsect1>
       </refentry>
@@ -2368,14 +2346,9 @@
 --depth ARG
 --force
 --with-revprop ARG
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --force-log
 --editor-cmd EDITOR
 --encoding ENC
---config-dir DIR
 --auto-props
 --no-auto-props
 --ignore-externals
@@ -2506,11 +2479,6 @@
 --targets FILENAME
 --incremental
 --xml
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 --changelist ARG
 </screen>
         </refsect1>
@@ -2695,11 +2663,6 @@
 --depth ARG
 --incremental
 --xml
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -2814,11 +2777,6 @@
 --file (-F) FILE
 --force-log
 --encoding ENC
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -2940,11 +2898,6 @@
 --with-all-revprops
 --with-revprop ARG
 --xml
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -3281,11 +3234,6 @@
 --diff3-cmd CMD
 --extensions (-x) ARG
 --ignore-ancestry
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -3370,11 +3318,6 @@
 
           <screen>
 --revision (-r) REV
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -3453,14 +3396,9 @@
 --quiet (-q)
 --parents
 --with-revprop ARG
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --editor-cmd EDITOR
 --encoding ENC
 --force-log
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -3571,14 +3509,9 @@
 --force
 --parents
 --with-revprop ARG
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --editor-cmd EDITOR
 --encoding ENC
 --force-log
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -3670,11 +3603,6 @@
 --depth ARG
 --revision (-r) REV
 --revprop
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 --changelist ARG
 </screen>
         </refsect1>
@@ -3755,13 +3683,8 @@
 --file (-F) ARG
 --force-log
 --with-revprop ARG
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --encoding ENC
 --editor-cmd EDITOR
---config-dir DIR
 </screen>
         </refsect1>
 
@@ -3836,11 +3759,6 @@
 --revprop
 --strict
 --xml
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 --changelist ARG
 </screen>
         </refsect1>
@@ -3938,11 +3856,6 @@
 --quiet (-q)
 --revprop
 --xml
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 --changelist ARG
 </screen>
         </refsect1>
@@ -4055,13 +3968,8 @@
 --targets FILENAME
 --depth ARG
 --revprop
---username USER
---password PASS
---no-auth-cache
---non-interactive
 --encoding ENC
 --force
---config-dir DIR
 --changelist ARG
 </screen>
         </refsect1>
@@ -4238,7 +4146,6 @@
 --accept ARG
 --quiet (-q)
 --accept ARG
---config-dir DIR
 </screen>
         </refsect1>
         
@@ -4324,7 +4231,6 @@
 --depth ARG
 --accept ARG
 --quiet (-q)
---config-dir DIR
 </screen>
         </refsect1>
         
@@ -4413,7 +4319,6 @@
 --targets FILENAME
 --depth ARG
 --quiet (-q)
---config-dir DIR
 --changelist ARG
 </screen>
         </refsect1>
@@ -4818,11 +4723,6 @@
 --no-ignore
 --incremental
 --xml
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 --ignore-externals
 --changelist ARG
 </screen>
@@ -5017,11 +4917,6 @@
 --quiet (-q)
 --diff3-cmd CMD
 --relocate FROM TO
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 </screen>
         </refsect1>
         
@@ -5173,11 +5068,6 @@
 
           <screen>
 --targets FILENAME
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 --force
 </screen>
         </refsect1>
@@ -5348,11 +5238,6 @@
 --diff3-cmd CMD
 --editor-cmd ARG
 --accept ARG
---username USER
---password PASS
---no-auth-cache
---non-interactive
---config-dir DIR
 --ignore-externals
 --changelist
 </screen>
@@ -7706,7 +7591,7 @@
           <listitem>
             <para>Prevents caching of authentication information
               (e.g., username and password) in the Subversion
-              administrative directories.</para>
+              runtime configuration directories.</para>
           </listitem>
         </varlistentry>
 
@@ -7724,12 +7609,12 @@
 
         <varlistentry>
           <term><option>--password</option>
-            <replaceable>PASS</replaceable></term>
+            <replaceable>PASSWD</replaceable></term>
           <listitem>
-            <para>Indicates that you are providing your password for
-              authentication on the command line—otherwise, if
-              it is needed, Subversion will prompt you for
-              it.</para>
+            <para>Specifies the password to use when authenticating
+              against a Subversion server.  If not provided, or if
+              incorrect, Subversion will prompt you for this
+              information as needed.</para>
           </listitem>
         </varlistentry>
 
@@ -7737,10 +7622,10 @@
           <term><option>--username</option>
             <replaceable>NAME</replaceable></term>
           <listitem>
-            <para>Indicates that you are providing your username for
-              authentication on the command line—otherwise, if
-              it is needed, Subversion will prompt you for
-              it.</para>
+            <para>Specifies the username to use when authenticating
+              against a Subversion server.  If not provided, or if
+              incorrect, Subversion will prompt you for this
+              information as needed.</para>
           </listitem>
         </varlistentry>
 




More information about the svnbook-dev mailing list