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

[fitz]

Author: fitz
Date: Sun Dec  2 22:19:00 2007
New Revision: 2895

Log:
Discuss our option notation and long vs short form options in a nice
sidebar in Chapter 2.

This fixes issue #53.

* src/en/book/ch02-basic-usage.xml: Option is not a failure.


Modified:
   trunk/src/en/book/ch02-basic-usage.xml

Modified: trunk/src/en/book/ch02-basic-usage.xml
==============================================================================
--- trunk/src/en/book/ch02-basic-usage.xml	(original)
+++ trunk/src/en/book/ch02-basic-usage.xml	Sun Dec  2 22:19:00 2007
@@ -49,6 +49,29 @@
   -N [--non-recursive]     : operate on single directory only
 …
 </screen>
+
+      <sidebar>
+        <title>Options and Switches and Flags, Oh My!</title>
+        
+        <para>The Subversion command line client has numerous command
+          modifiers (which we call options), but there are two
+          distinct kinds of options—<quote>short options</quote>
+          that are a single hyphen followed by a single letter, and
+          <quote>long options</quote> that consist of two hyphens
+          followed by a number of letters (eg <literal>-s</literal>
+          and <literal>--this-is-a-long-option</literal>
+          respectively).  Every option has a long format, but only
+          certain options have an additional short format (these are
+          typically options that are frequently used).  In order to
+          maintain clarity, we <emphasis>usually</emphasis> use the
+          long form in code examples, but when describing options, if
+          there's a short form, we'll provide the long form (to
+          improve clarity), and the short form (to make it easier to
+          remember).  You should use whichever one you're more
+          comfortable with, but don't try to use both.</para>
+        
+      </sidebar>
+
   </sect1>
 
   <!-- ================================================================= -->