[svnbook] r3800 committed - * src/en/book/ch02-basic-usage.xml...
svnbook at googlecode.com
svnbook at googlecode.com
Thu Oct 14 21:17:19 CDT 2010
Revision: 3800
Author: cmpilato at gmail.com
Date: Thu Oct 14 19:16:22 2010
Log: * src/en/book/ch02-basic-usage.xml
(Help!): Rework this section a bit.
http://code.google.com/p/svnbook/source/detail?r=3800
Modified:
/trunk/src/en/book/ch02-basic-usage.xml
=======================================
--- /trunk/src/en/book/ch02-basic-usage.xml Thu Oct 14 14:58:06 2010
+++ /trunk/src/en/book/ch02-basic-usage.xml Thu Oct 14 19:16:22 2010
@@ -26,69 +26,102 @@
<sect1 id="svn.tour.help">
<title>Help!</title>
- <para>
- <indexterm>
- <primary>svn</primary>
- <secondary>subcommands</secondary>
- <tertiary>help</tertiary>
- </indexterm>
- Before reading on, here is the most important command you'll
- ever need when using Subversion: <command>svn help</command>.
- The Subversion command-line client is self-documenting—at
- any time, a quick <userinput>svn help
- <replaceable>subcommand</replaceable></userinput> will describe
- the syntax, options, and behavior of the subcommand.</para>
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>subcommands</secondary>
+ <tertiary>help</tertiary>
+ </indexterm>
+
+ <para>It goes without saying that this book exists to be a source
+ of information and assistance for Subversion users new and old.
+ Conveniently, though, the Subversion command-line is
+ self-documenting, alleviating the need to grab a book off the
+ shelf (wooden, virtual, or otherwise). The <command>svn
+ help</command> command is your gateway to that built-in
+ documentation:</para>
<screen>
-$ svn help import
-import: Commit an unversioned file or tree into the repository.
-usage: import [PATH] URL
-
- Recursively commit a copy of PATH to URL.
- If PATH is omitted '.' is assumed.
- Parent directories are created as necessary in the repository.
- If PATH is a directory, the contents of the directory are added
- directly under URL.
- Unversionable items such as device files and pipes are ignored
- if --force is specified.
-
-Valid options:
- -q [--quiet] : print nothing, or only summary information
- -N [--non-recursive] : obsolete; try --depth=files or
--depth=immediates
- --depth ARG : limit operation by depth ARG
('empty', 'files',
- 'immediates', or 'infinity')
+$ svn help
+Subversion command-line client, version 1.6.13.
+Type 'svn help <subcommand>' for help on a specific subcommand.
+Type 'svn --version' to see the program version and RA modules
+ or 'svn --version --quiet' to see just the version number.
+
+Most subcommands take file and/or directory arguments, recursing
+on the directories. If no arguments are supplied to such a
+command, it recurses on the current directory (inclusive) by default.
+
+Available subcommands:
+ add
+ blame (praise, annotate, ann)
+ cat
…
</screen>
- <sidebar>
- <title>Options and Switches and Flags, Oh My!</title>
-
- <para>
- <indexterm>
- <primary>svn</primary>
- <secondary>options</secondary>
- </indexterm>
- The Subversion command-line client has numerous command
- modifiers (which we call options), but there are two
- distinct kinds of options: short options are a single hyphen
- followed by a single letter, and long options consist of two
- hyphens followed by several letters and hyphens
- (e.g., <literal>-s</literal>
- and <literal>--this-is-a-long-option</literal>,
- respectively). Every option has at least one long format.
- Some, such as the <option>--changelist</option> option,
- feature an abbreviated long-format alias
- (<option>--cl</option>, in this case). Only certain
- options—generally the most-used ones—have an
- additional short format. To maintain clarity in this book,
- we usually 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). Use the form you're more
- comfortable with when executing your own Subversion
- commands.</para>
-
- </sidebar>
+ <para>As described in the previous output, you can ask for help on
+ a particular subcommand by running <command>svn help
+ <replaceable>SUBCOMMAND</replaceable></command>. Subversion
+ will respond with the full usage message for that subcommand,
+ including its syntax, options, and behavior:</para>
+
+ <screen>
+$ svn help help
+help (?, h): Describe the usage of this program or its subcommands.
+usage: help [SUBCOMMAND...]
+
+Global options:
+ --username ARG : specify a username ARG
+ --password ARG : specify a password ARG
+…
+</screen>
+
+ <sidebar>
+ <title>Options and Switches and Flags, Oh My!</title>
+
+ <indexterm>
+ <primary>svn</primary>
+ <secondary>options</secondary>
+ </indexterm>
+
+ <para>The Subversion command-line client has numerous command
+ modifiers. Some folks refer to such things
+ as <quote>switches</quote> or <quote>flags</quote>—in
+ this book, we'll call them <quote>options</quote>. You'll
+ find the options supported by a given <command>svn</command>
+ subcommand, plus a set of options which are globally supported
+ by all subcommands, listed near the bottom of the built-in
+ usage message for that subcommand.</para>
+
+ <para>Subversion's options have two distinct forms: short
+ options are a single hyphen followed by a single letter, and
+ long options consist of two hyphens followed by several
+ letters and hyphens (e.g., <literal>-s</literal>
+ and <literal>--this-is-a-long-option</literal>, respectively).
+ Every option has at least one long format. Some, such as
+ the <option>--changelist</option> option, feature an
+ abbreviated long-format alias (<option>--cl</option>, in this
+ case). Only certain options—generally the most-used
+ ones—have an additional short format. To maintain
+ clarity in this book, we usually 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). Use the form
+ you're more comfortable with when executing your own
+ Subversion commands.</para>
+
+ </sidebar>
+
+ <para>Many Unix-based distributions of Subversion include manual
+ pages of the sort that can be invoked using
+ the <command>man</command> program, but those tend to carry only
+ pointers to other sources of real help, such as the project's
+ website and to the website which hosts this book. Also, several
+ companies offer Subversion help and support, too, usually via a
+ mixture of web-based discussion forums and fee-based consulting.
+ And of course, the Internet holds a decade's worth of
+ Subversion-related discussions just begging to be located by
+ your favorite search engine. Subversion help is never too far
+ away.</para>
</sect1>
More information about the svnbook-dev
mailing list