[SvnBook] #65: [PATCH] Hanchrow review [ch9]

SvnBook noreply at red-bean.com
Fri Aug 10 21:09:39 CDT 2007


#65: [PATCH] Hanchrow review [ch9]
-------------------------+--------------------------------------------------
 Reporter:  cmpilato     |       Owner:  nobody
     Type:  enhancement  |      Status:  new   
 Priority:  normal       |   Milestone:  1.5   
Component:  content      |     Version:        
 Keywords:               |  
-------------------------+--------------------------------------------------
 From: Eric Hanchrow <offby1 at blarg.net>

 {{{
 Index: ch09-reference.xml
 ===================================================================
 --- ch09-reference.xml  (revision 2737)
 +++ ch09-reference.xml  (working copy)
 @@ -32,10 +32,12 @@
  </screen>

      <para>You can find many more examples of how to use most client
 -      commands in <xref linkend="svn.tour"/> and commands for managing
 +      commands in <xref linkend="svn.tour"/>, and commands for managing
        properties in <xref linkend="svn.advanced.props"/>.</para>

      <!-- ===============================================================
 -->
 +    <!-- I suspect that sometimes we call them "switches", and
 +    sometimes "options".  We should be consistent. -->
      <sect2 id="svn.ref.svn.sw">
        <title><command>svn</command> Switches</title>

 @@ -47,6 +49,13 @@
          means <quote>verbose output</quote>, regardless of the
          subcommand you use it with.</para>

 +      <!-- I think at least some of these switches - like "limit" -
 +      apply to just one subcommand.  Shouldn't they therefore be
 +      listed with those commands, instead of here?  If not, then
 +      perhaps we should say above "When two or more subcommands both
 +      take a given switch, the switch will always have the same
 +      meaning in each subcommand."-->
 +
        <variablelist>

          <varlistentry>
 @@ -75,7 +84,7 @@
            <listitem>
              <para>Specifies an external program to use to show
                differences between files.  When <command>svn
 -              diff</command> is invoked, it uses Subversion's internal
 +              diff</command> is invoked without this option, it uses
 Subversion's internal
                diff engine, which provides unified diffs by default.
                If you want to use an external diff program, use
                <option>--diff-cmd</option>.  You can pass switches to
 @@ -116,6 +125,11 @@
            <term><option>--encoding</option>
 <replaceable>ENC</replaceable></term>
            <listitem>
              <para>Tells Subversion that your commit message is encoded
 +              <!-- can we be sure that our reader knows what a
 +              "charset" is?  I suspect the only valid "charsets" are
 +              those output by "locale -a" on *nix (and I have no idea
 +              what's valid on Windows).  We should at least link to
 +              something relevant in svn.advanced.l10n -->
                in the charset provided.  The default is your operating
                system's native locale, and you should specify the
                encoding if your commit message is in any other
 @@ -128,13 +142,15 @@
            <replaceable>ARGS</replaceable></term>
            <listitem>
              <para>Specifies an argument or arguments that Subversion
 -              should pass to an external diff command when providing
 -              differences between files.  If you wish to pass multiple
 +              should pass to an external diff command.  This option is
 +              valid only when used with the <command>svn
 +              diff</command> or <command>svn merge</command> commands,
 +              with the
 +              <option>--diff-cmd</option> switch.
 +              If you wish to pass multiple
                arguments, you must enclose all of them in quotes (for
                example, <command>svn diff --diff-cmd /usr/bin/diff -x
 -              "-b -E"</command>).  This switch can
 -              <emphasis>only</emphasis> be used if you also pass the
 -              <option>--diff-cmd</option> switch.</para>
 +              "-b -E"</command>).</para>
            </listitem>
          </varlistentry>

 @@ -143,8 +159,11 @@
              <replaceable>FILENAME</replaceable>
            </term>
            <listitem>
 -            <para>Uses the contents of the file passed as an argument
 -              to this switch for the specified subcommand.</para>
 +            <para>Uses the contents of the named file for the specified
 subcommand.  Note that
 +              different subcommands do different things with this
 +              content—for example, <command>svn commit</command>
 +              uses the content as a commit log, whereas <command>svn
 +              propset</command> uses it as a property value.</para>
            </listitem>
          </varlistentry>

 @@ -246,6 +265,8 @@
          <varlistentry>
            <term><option>--new</option>
 <replaceable>ARG</replaceable></term>
            <listitem>
 +            <!-- mention the subcommand this goes with; this sentence
 +            just seems weird all by itself.  Ditto for -old -->
              <para>Uses <replaceable>ARG</replaceable> as the newer
                target.</para>
            </listitem>
 @@ -327,6 +348,12 @@
          </varlistentry>

          <varlistentry>
 +          <!-- I have this vague feeling that certain subcommands
 +          don't work properly with -N, but can't remember what, and
 +          can't find any relevant items in the issue tracker.  Someone
 +          who's more in touch than I should determine if we need to
 +          include a caveat, here, describing those problems ... if
 +          they exist at all ... -->
            <term><option>--non-recursive</option>
 (<option>-N</option>)</term>
            <listitem>
              <para>Stops a subcommand from recursing into
 @@ -354,6 +381,9 @@
          </varlistentry>

          <varlistentry>
 +          <!-- is it worth noting that it's possible, at least in
 +          theory, for Bad People to read your command line (e.g., by
 +          running "ps")? -->
            <term><option>--password</option>
              <replaceable>PASS</replaceable></term>
            <listitem>
 @@ -398,6 +428,8 @@
            <term><option>--revision</option> (<option>-r</option>)
              <replaceable>REV</replaceable>
            </term>
 +          <!-- do we precisely describe the date format the -r
 +          accepts?  If so, link to it here -->
            <listitem>
              <para>Indicates that you're going to supply a revision (or
                range of revisions) for a particular operation.  You can
 @@ -461,10 +493,14 @@
              <para>Causes Subversion to use strict semantics, a notion
                which is rather vague unless talking about specific
                subcommands.</para>
 +            <!-- indeed it is vague.  Why not list the actual
 +              subcommands here? -->
            </listitem>
          </varlistentry>

          <varlistentry>
 +          <!-- this switch seems rather similar to -F.  Can we
 +          explain how they're different? -->
            <term><option>--targets</option>
              <replaceable>FILENAME</replaceable></term>
            <listitem>
 @@ -524,7 +560,11 @@
      <!-- ===============================================================
 -->
      <sect2 id="svn.ref.svn.c">
        <title><command>svn</command> Subcommands</title>
 -
 +      <!-- the HTML output for this section ends here; it looks
 +      funny.  Maybe we should include a boilerplate sentence like the
 +      one I've inserted, or some sort of magical "hey, docbook: please
 +      don't put a page-break here" command: -->
 +      Here are the various subcommands:
        <refentry id="svn.ref.svn.c.add">

          <indexterm>
 @@ -545,8 +585,8 @@
          <refsect1>
            <title>Description</title>

 -          <para>Add files, directories, or symbolic links to your
 -            working copy and schedule them for addition to the
 +          <para>Schedule files, directories, or symbolic links in your
 +            working copy for addition to the
              repository.  They will be uploaded and added to the
              repository on your next commit.  If you add something and
              change your mind before committing, you can unschedule the
 @@ -616,7 +656,10 @@
              will skip over any directories that are already under
              version control.  Sometimes, however, you may want to add
              every unversioned object in your working copy, including
 -            those hiding deeper down.  Passing the
 +            those hiding deeper down.
 +            <!-- is it worth giving an example of a time when we'd
 +            want to do this?  I can't think of any reason offhand. -->
 +                                       Passing the
              <option>--force</option> option makes <command>svn
              add</command> recurse into versioned directories:</para>

 @@ -698,6 +741,10 @@
       5      harry You should read this.
  </screen>

 +          <!-- perhaps note that, even if a given line was last
 +          "touched" by bob at r123, that doesn't necessarily mean the
 +          bug in that line is his fault - he may have just stripped
 +          trailing whitespace or something. -->
          </refsect1>
        </refentry>

 @@ -861,7 +908,7 @@
  mine
  </screen>

 -          <para>Check out 2 different directories into two separate
 +          <para>Check out two different directories into two separate
              working copies:</para>

            <screen>
 @@ -876,7 +923,7 @@
  quiz  test
  </screen>

 -          <para>Check out 2 different directories into two separate
 +          <para>Check out two different directories into two separate
              working copies, but place both into a directory called
              <filename>working-copies</filename>:</para>

 @@ -893,11 +940,11 @@
  </screen>

            <para>If you interrupt a checkout (or something else
 -            interrupts your checkout like loss of connectivity, etc.),
 +            interrupts your checkout, like loss of connectivity, etc.),
              you can restart it either by issuing the
              identical checkout command again, or by updating the
              incomplete working copy:</para>
 -
 +          <!-- isn't it common to need to run 'svn cleanup' in this case?
 -->
            <screen>
  $ svn checkout file:///tmp/repos/test test
  A  test/a
 @@ -948,6 +995,10 @@
              run this command to remove stale locks and get your working
 copy
              into a usable state again.</para>

 +          <!-- this would be a good place to discuss the issue that I
 +          raised in
 +
 http://subversion.tigris.org/servlets/ReadMsg?list=dev&msgNo=124919
 +          -->
            <para>If, for some reason, an <command>svn update</command>
              fails due to a problem running an external diff program
              (e.g. user input or network failure), pass the
 @@ -1029,9 +1080,12 @@
              <literal>editor-cmd</literal> section in <xref
              linkend="svn.advanced.confarea.opts.config"/>.</para>

 -          <para><command>svn commit</command> will send found lock
 -            tokens and release locks on all
 -            <replaceable>PATHS</replaceable> committed (recursively)
 +          <!-- this is ambiguous.  Does -no-unlock control both the
 +          _releasing_ of lock tokens and the _sending_ of lock tokens,
 +          or just the releasing? -->
 +          <para><command>svn commit</command> will send any lock
 +            tokens that it finds, and will release locks on all
 +            <replaceable>PATHS</replaceable> committed (recursively),
              unless <option>--no-unlock</option> is passed.</para>

            <tip>
 @@ -1187,6 +1241,7 @@
                <varlistentry>
                  <term>URL -> WC</term>
                  <listitem>
 +                  <!-- is it correct to say "check out" here? -->
                    <para>Check out URL into WC, and schedule it for
                      addition.</para>
                  </listitem>
 @@ -1356,7 +1411,7 @@

          <refsect1>
            <title>Changes</title>
 -          <para>Working copy if operating on files, Repository if
 +          <para>Working copy if operating on files, repository if
              operating on URLs</para>
          </refsect1>

 @@ -1389,6 +1444,7 @@
            <title>Examples</title>

            <para>Using <command>svn</command> to delete a file from
 +            <!-- well ... it deletes it _from your wc_ immediately. -->
              your working copy merely schedules it to be
              deleted.  When you commit, the file is deleted in the
              repository.</para>
 @@ -1438,7 +1494,8 @@

          <refnamediv>
            <refname>svn diff</refname>
 -          <refpurpose>Display the differences between two
 paths.</refpurpose>
 +          <refpurpose>Display the differences between two paths, or
 +          two revisions of one path.</refpurpose>
          </refnamediv>
          <refsect1>
            <title>Synopsis</title>
 @@ -1453,6 +1510,11 @@
              different ways you can use <command>svn diff</command>
              are:</para>

 +          <!-- I realize this criticism isn't constructive, but:
 +          reading the paragraph made my eyes glaze over.  It's so much
 +          detailed information compressed into a small space.  Perhaps
 +          the relevant examples could be interspersed with the prose,
 +          rather than saved up for the end of the section? -->
            <para><command>svn diff [-r N[:M]] [--old OLD-TGT] [--new
              NEW-TGT] [PATH...]</command> displays the differences
              between <replaceable>OLD-TGT</replaceable> and
 @@ -1915,29 +1977,33 @@
          <refsect1>
            <title>Examples</title>

 -          <para>This imports the local directory
 <filename>myproj</filename> into the
 -            root of your repository:</para>
 +          <para>This imports the local directory
 <filename>myproj</filename>
 +            into <filename>trunk/misc</filename> in your repository.
 +            The
 +            directory <filename>trunk/misc</filename> need not exist
 before
 +            you import into it—<command>svn import</command> will
 +            recursively create directories for you.</para>

            <screen>
 -$ svn import -m "New import" myproj http://svn.red-bean.com/repos/test
 +$ svn import -m "New import" myproj http://svn.red-
 bean.com/repos/trunk/misc
  Adding         myproj/sample.txt
  …
  Transmitting file data .........
  Committed revision 16.
  </screen>

 -          <para>This imports the local directory
 <filename>myproj</filename>
 -            into <filename>trunk/misc</filename> in your repository.  The
 -            directory <filename>trunk/misc</filename> need not exist
 before
 -            you import into it—<command>svn import</command> will
 -            recursively create directories for you:</para>
 +            <para>
 +            Note that it will <emphasis>not</emphasis> create a
 +            directory named <filename>myproj</filename> in the
 +            repository.  If that's what you want, simply
 +            add <filename>myproj</filename> to the end of the URL:</para>
 +
            <screen>
 -$ svn import -m "New import" myproj \
 -    http://svn.red-bean.com/repos/test/trunk/misc/myproj
 +$ svn import -m "New import" myproj http://svn.red-
 bean.com/repos/trunk/misc/myproj
  Adding         myproj/sample.txt
  …
  Transmitting file data .........
 -Committed revision 19.
 +Committed revision 16.
  </screen>

            <para>After importing data, note that the original tree is
 @@ -2215,6 +2281,15 @@
       24 harry               Jan 18 11:27 examples/
  </screen>

 +          <!-- dunno if this is worth mentioning, but it can be handy
 +          to use 'svn list' to do a recursive grep through one's
 +          working copy, ignoring all the files that aren't under
 +          revision control.  For example: "svn ls | xargs egrep
 +          buffer" searches for the word "buffer" only in those files
 +          that are under revision control. -->
 +
 +          <!-- that section really doesn't have any more detail; it
 +          says pretty much the same stuff. -->
            <para>For further details, see <xref
              linkend="svn.tour.history.browsing.list"/>.</para>

 @@ -2302,18 +2377,18 @@

            <screen>
  $ svn lock tree.jpg
 -svn: warning: Path '/tree.jpg is already locked by user 'harry in \
 +svn: warning: Path '/tree.jpg is already locked by user 'sally in \
       filesystem '/svn/repos/db'

  $ svn lock --force foo
 -'tree.jpg' locked by user 'sally'.
 +'tree.jpg' locked by user 'harry'.
  </screen>

            <para>Lock a file without a working copy:</para>

            <screen>
  $ svn lock http://svn.red-bean.com/repos/test/tree.jpg
 -'tree.jpg' locked by user 'sally'.
 +'tree.jpg' locked by user 'harry'.
  </screen>

            <para>For further details, see <xref
 @@ -2343,8 +2418,8 @@
          <refsect1>
            <title>Description</title>

 -          <para>The default target is the path of your current
 -            directory.  If no arguments are supplied, <command>svn
 +          <para>Shows log messages from the repository.
 +            If no arguments are supplied, <command>svn
              log</command> shows the log messages for all files and
              directories inside of (and including) the current working
              directory of your working copy.  You can refine the
 @@ -2580,6 +2655,10 @@
            <refpurpose>Apply the differences between two sources to a
            working copy path.</refpurpose>
          </refnamediv>
 +        <!-- I'd note that the third form is by far the most common (if
 that
 +        is indeed true, which I suspect it is).  In fact it might be
 +        good to reorder the programlistings so that that third form
 +        comes first. -->
          <refsect1>
            <title>Synopsis</title>
            <programlisting>svn merge sourceURL1[@N] sourceURL2[@M]
 [WCPATH]</programlisting>
 @@ -2717,6 +2796,10 @@
              Multiple directory URLs are committed atomically.  In both
              cases all the intermediate directories must already
              exist.</para>
 +          <!-- might it be worthwhile to answer the question "How do I
 +            create a deeply-nested directory structure atomically"?
 +            The answer would be "do a bunch of 'svn mkdir's in a wc,
 +            and then commit that"-->
          </refsect1>

          <refsect1>
 @@ -2774,6 +2857,23 @@
          </refsect1>
        </refentry>

 +      <!-- we could use an example of moving a directory.  In
 +      particular, it would be good to point out that the output of
 +      such a command is a tad confusing, in that we will see a D line
 +      for each file in the old directory, but no corresponding A line.
 +      Here's an example:
 +
 +      $ svn mv dee eff
 +      A         eff
 +      D         dee/a
 +      D         dee/b
 +      D         dee/c
 +      D         dee
 +
 +Note how the three files under "dee" each get their own D line,
 +whereas there's no corresponding A line for each.  This has confused
 +at least one newbie.
 +-->
        <refentry id="svn.ref.svn.c.move">

          <indexterm>
 @@ -3286,7 +3386,7 @@
          <refsect1>
            <title>Examples</title>

 -          <para>Set the mimetype on a file:</para>
 +          <para>Set the mime type on a file:</para>

            <screen>
  $ svn propset svn:mime-type image/jpeg foo.jpg
 @@ -3532,6 +3632,13 @@
  ?      whoops
  </screen>

 +          <warning>
 +            <command>svn revert</command> is inherently dangerous, since
 +            its entire purpose is to throw away data—namely, your
 +            uncommitted changes.  Once you've reverted, Subversion
 +            provides <emphasis>no way</emphasis> to get back those
 +            uncommitted changes, so be careful using it.
 +          </warning>
            <note>
              <para>If you provide no targets to <command>svn
                revert</command>, it will do nothing—to protect
 @@ -3565,7 +3672,7 @@
            <para>Print the status of working copy files and
              directories.  With no arguments, it prints only locally
              modified items (no repository access).  With
 -            <option>--show-updates</option>, add working revision
 +            <option>--show-updates</option>, adds working revision
              and server out-of-date information.  With
              <option>--verbose</option>, print full revision
              information on every item.</para>
 @@ -3629,7 +3736,7 @@
              <varlistentry>
                <term>'X'</term>
                <listitem>
 -                <para>Item is related to an externals definition.</para>
 +                <para>Item is present because of an externals
 definition.</para>
                </listitem>
              </varlistentry>

 @@ -3800,7 +3907,7 @@
                <term>T</term>
                <listitem>
                  <para>File was locked in this working copy, but the
 -                lock has been <quote>stolen</quote>and is invalid.
 +                lock has been <quote>stolen</quote> and is invalid.
                  The file is currently locked in the repository.  This
                  only appears when <option>--show-updates</option> is
                  used.</para>
 @@ -3811,7 +3918,7 @@
                <term>B</term>
                <listitem>
                  <para>File was locked in this working copy, but the
 -                lock has been <quote>broken</quote>and is invalid.
 +                lock has been <quote>broken</quote> and is invalid.
                  The file is no longer locked This only appears when
                  <option>--show-updates</option> is used.</para>
                </listitem>
 @@ -3929,6 +4036,8 @@
                update</command>).  <option>--show-updates</option> does
                <emphasis>not</emphasis> cause the status listing to
                reflect the repository's version of the item.</para>
 +            <!-- might we not add "but you can see the revision number
 +              in the repository with -verbose; see below"? -->
            </note>

            <para>And finally, the most information you can get out of
 @@ -3972,13 +4081,23 @@
          <refsect1>
            <title>Description</title>

 -          <para>This subcommand updates your working copy to mirror
 +          <para>The first variant
 +            (without <option>--relocate</option>) of this subcommand
 updates your working copy to mirror
              a new URL—usually a URL which shares a common
              ancestor with your working copy, although not
              necessarily.  This is the Subversion way to move a
              working copy to a new branch.  See <xref
              linkend="svn.branchmerge.switchwc"/> for an in-depth look at
              switching.</para>
 +          <para>
 +            The <option>--relocate</option> variant does something
 +            somewhat different: it updates your working copy to
 +            mirror <emphasis>the same</emphasis> repository directory,
 +            after that repository has acquired a different URL
 +            (typically because an administrator has moved the
 +            repository to another server, or to another URL on the
 +            same server).
 +          </para>
          </refsect1>

          <refsect1>
 @@ -4017,8 +4136,8 @@
            <title>Examples</title>

            <para>If you're currently inside the directory
 -            <filename>vendors</filename> which was branched to
 -            <filename>vendors-with-fix</filename> and you'd like to
 +            <filename>vendors</filename>, which was branched to
 +            <filename>vendors-with-fix</filename>, and you'd like to
              switch your working copy to that branch:</para>

            <screen>
 @@ -4054,8 +4173,8 @@
              other words, the contents of the repository doesn't
              change, but the main URL used to reach the root of the
              repository does.  For example, the hostname may change,
 -            the URL scheme, or any part of the URL which leads to the
 -            repository itself.  Rather than checkout a new working
 +            the URL scheme may change, and any part of the URL which
 leads to the
 +            repository itself may change.  Rather than check out a new
 working
              copy, you can have the <command>svn switch</command>
              command <quote>rewrite</quote> the beginnings of all the
              URLs in your working copy.  Use the
 @@ -4084,6 +4203,12 @@
  </screen>

            <warning>
 +            <!-- is this still true?  Whenever I've mangled a URL, svn
 +            always tells me so.  I assume it contacts the "to" repos,
 +            and only if it can do so, _and_ if the "new" repository
 +            has the UUID that the wc expects, does it succeed.   I
 +            further assume that this is pretty good protection against
 +            typos.  -->
              <para>Be careful when using the
              <option>--relocate</option> option.  If you mistype the
              argument, you might end up creating nonsensical URLs
 @@ -4224,7 +4349,7 @@
            <title>Description</title>

            <para><command>svn update</command> brings changes from the
 -            repository into your working copy.  If no revision given,
 +            repository into your working copy.  If no revision is given,
              it brings your working copy up-to-date with the
              <literal>HEAD</literal> revision.  Otherwise, it
              synchronizes the working copy to the revision given by the
 @@ -4234,7 +4359,7 @@
              linkend="svn.tour.cleanup"/>) found in the
              working copy.</para>

 -          <para>For each updated item a line will start with a
 +          <para>For each updated item, it prints a line that starts with
 a
              character reporting the action taken.  These characters
              have the following meaning:</para>

 @@ -4264,7 +4389,7 @@
              <varlistentry>
                <term>C</term>
                <listitem>
 -                <para>Conflict</para>
 +                <para>Conflicted</para>
                </listitem>
              </varlistentry>

 @@ -4329,7 +4454,7 @@
  Updated to revision 32.
  </screen>

 -          <para>You can also update your working copy to an older
 +          <para>You can also <quote>update</quote> your working copy to
 an older
              revision (Subversion doesn't have the concept of
              <quote>sticky</quote> files like CVS does; see <xref
              linkend="svn.forcvs"/>):</para>
 @@ -4347,7 +4472,7 @@
            <tip>
              <para>If you want to examine an older revision of a
                single file, you may want to use <command>svn
 -              cat</command>.</para>
 +              cat</command> instead; it won't change your working
 copy.</para>
            </tip>

          </refsect1>
 @@ -4375,6 +4500,10 @@
      <sect2 id="svn.ref.svnadmin.sw">
        <title><command>svnadmin</command> Switches</title>

 +      <!-- I think these options could be explained more clearly if we
 +      mentioned the subcommands to which they pertain.  For example, I
 +      assume that the first option listed - bdb-log-keep - pertains
 +      only to "svnadmin create".  -->
        <variablelist>

          <varlistentry>
 @@ -4382,6 +4511,9 @@
            <listitem>
              <para>(Berkeley DB specific) Disable automatic log removal
                of database log files.</para>
 +            <!-- can we include something that explains when we should
 +              use this option?  Without that context, this
 +              varlistentry is close to useless.-->
            </listitem>
          </varlistentry>

 @@ -4390,6 +4522,9 @@
            <listitem>
              <para>(Berkeley DB specific) Disables fsync when
                committing database transactions.</para>
 +            <!-- can we include something that explains when we should
 +              use this option?  Without that context, this
 +              varlistentry is close to useless.-->
            </listitem>
          </varlistentry>

 @@ -4424,6 +4559,11 @@
          <varlistentry>
            <term><option>--ignore-uuid</option></term>
            <listitem>
 +            <!-- This text directly contradicts the preceding.  It
 +            can't both ignore, and not ignore, the UUID by default.
 +            Alas, my source-reading-fu is but weak: I can't tell which
 +            is really the default, and am frankly too lazy to run a
 +            test to find out.  -->
              <para>By default, when loading an empty repository,
                <command>svnadmin</command> will use the
                <literal>UUID</literal> from the dump stream.  This
 @@ -4492,7 +4632,8 @@
      <!-- ===============================================================
 -->
      <sect2 id="svn.ref.svnadmin.c">
        <title><command>svnadmin</command> Subcommands</title>
 -
 +      <!-- this another of those spots where docbook puts a page break
 +      in the html-chunk.  It looks weird.  -->
        <refentry id="svn.ref.svnadmin.c.create">

          <indexterm>
 @@ -4575,8 +4716,8 @@
          <refsect1>
            <title>Description</title>

 -          <para><command>svnadmin deltify</command> only exists in
 -            current versions of Subversion due to historical reasons.
 +          <para><command>svnadmin deltify</command> exists in
 +            current versions of Subversion only for historical reasons.
              This command is deprecated and no longer needed.</para>

            <para>It dates from a time when Subversion offered
 @@ -4637,7 +4778,7 @@
              its properties, are presented in the dumpfile; for a
              directory, all of its properties are presented.</para>

 -          <para>There are a pair of useful options which modify the
 +          <para>There is a pair of useful options which modify the
              dumpfile generator's behavior.  The first is the
              <option>--incremental</option> option, which simply causes
              that first revision in the dumpfile stream to contain only
 @@ -4645,7 +4786,7 @@
              instead of being presented as the addition of a new tree,
              and in exactly the same way that every other revision in
              the dumpfile is presented.  This is useful for generating
 -            a dumpfile that is to be loaded into another repository
 +            a relatively small dumpfile, so long as that dumpfile is to
 be loaded into another repository
              which already has the files and directories that exist in
              the original repository.</para>

 @@ -4662,7 +4803,12 @@
              not to compress as well as their non-deltified counterparts
              when using third-party tools like <command>gzip</command>
              and <command>bzip2</command>.</para>
 -
 +          <!-- is "not compressing as well" really a disadvantage,
 +            given that the dumpfile itself is, in effect, already
 +            compressed?  Or did you mean that the sequence "svnadmin
 +            dump repos > dump; compress dump" generally creates a
 +            smaller dump.gz than does the sequence "svnadmin dump
 +            -deltas repos > dump; compress dump" ? -->
          </refsect1>
          <refsect1>
            <title>Switches</title>
 @@ -4728,7 +4874,8 @@
            <para>This subcommand is useful when you're trapped on a
              desert island with neither a net connection nor a copy of
              this book.</para>
 -
 +          <!-- although marginally less useful than, say, a cooler
 +            full of beer. -->
          </refsect1>

          <refsect1>
 @@ -4778,6 +4925,15 @@
  </screen>
          </refsect1>

 +        <warning>
 +        As described in
 +        <xref linkend="svn.reposadmin.basics.backends.bdb"/>,
 +        hot-copied Berkeley
 +        DB repositories are <emphasis>not</emphasis> portable across
 +        operating systems, nor will they work on a machine with a
 +        different word order (aka <quote>endianness</quote>), nor on a
 +        machine with a different word size.
 +        </warning>
        </refentry>

        <refentry id="svn.ref.svnadmin.c.list-dblogs">
 @@ -4961,7 +5117,7 @@


            <para>This lists the one locked file in the repository at
 -            <filename>/svn/repos</filename></para>
 +            <filename>/svn/repos</filename>:</para>

            <screen>
  $ svnadmin lslocks /svn/repos
 @@ -5259,6 +5415,8 @@
          </refsect1>
        </refentry>

 +      <!-- this could use a lot more explanation.  When should I use
 +      it?  What do I do if it fails? -->
        <refentry id="svn.ref.svnadmin.c.verify">

          <indexterm>
 @@ -5544,9 +5702,9 @@
              </varlistentry>

              <varlistentry>
 -              <term>'<literal>_U</literal>'</term>
 +              <term>'<literal> U</literal>'</term>
                <listitem>
 -                <para>Properties of item changed.</para>
 +                <para>Properties of item changed.  Note the leading
 space.</para>
                </listitem>
              </varlistentry>

 @@ -5577,8 +5735,10 @@
          <refsect1>
            <title>Examples</title>

 -          <para>This shows a list of all the changed files in
 -            revision 39 of a test repository:</para>
 +          <para>This shows a list of all the changed files and
 +            directories in
 +            revision 39 of a test repository.  Note that the first
 +            changed item is a directory, as evidenced by the trailing
 <literal>/</literal>:</para>

            <screen>
  $ svnlook changed -r 39 /usr/local/svn/repos
 @@ -5587,7 +5747,7 @@
  A   trunk/vendors/deli/sandwich.txt
  A   trunk/vendors/deli/pickle.txt
  U   trunk/vendors/baker/bagel.txt
 -_U  trunk/vendors/baker/croissant.txt
 + U  trunk/vendors/baker/croissant.txt
  UU  trunk/vendors/baker/pretzel.txt
  D   trunk/vendors/baker/baguette.txt
  </screen>
 @@ -5595,6 +5755,8 @@
          </refsect1>
        </refentry>

 +      <!-- when is this useful?  I imagine it's for use in a hook, but
 +      ... -->
        <refentry id="svn.ref.svnlook.c.date">

          <indexterm>
 @@ -5790,6 +5952,7 @@

        </refentry>

 +      <!-- again, when is this useful? -->
        <refentry id="svn.ref.svnlook.c.history">

          <indexterm>
 @@ -6124,6 +6287,7 @@
          </refsect1>
        </refentry>

 +      <!-- when is this useful? -->
        <refentry id="svn.ref.svnlook.c.tree">

          <indexterm>
 @@ -6264,17 +6428,28 @@
      <title><command>svnserve</command></title>

      <para><command>svnserve</command> allows access to Subversion
 -      repositories using the <literal>svn</literal> network protocol.
 -      You can run svnserve either as a standalone server process, or
 -      you can have another process, such as <command>inetd</command>,
 -      <command>xinetd</command> or <command>sshd</command>, launch it
 -      for you.</para>
 +      <!-- I'd rather not call it the "svn network protocol" because
 +      that's too easily confused with the svn _access method_. -->
 +      repositories using Subversion's custom network protocol.

 -    <para>Once the client has selected a repository by transmitting
 +      <!-- this implies that starting svnserve from inetd, xinetd, and
 +      sshd are all roughly equivalent.  But of course, only inetd and
 +      xinetd are equivalent; starting from sshd is very different. -->
 +      You can run <command>svnserve</command> as a standalone server
 +      process (for clients that are using
 +      the <literal>svn://</literal> access method);
 +      you can have a daemon such as <command>inetd</command> or
 +      <command>xinetd</command> launch it
 +      for you on demand (also for
 +       <literal>svn://</literal>),
 +      or you can have <command>sshd</command> launch it on demand for
 +      the <literal>svn+ssh://</literal> access method.</para>
 +
 +    <para>Regardless of the access method, once the client has selected a
 repository by transmitting
        its URL, <command>svnserve</command> reads a file named
        <filename>conf/svnserve.conf</filename> in the repository
 -      directory to determine repository-specific settings such as what
 -      authentication database to use and what authorization policies
 +      directory to determine repository-specific settings, such as what
 +      authentication database to use, and what authorization policies
        to apply.  See <xref linkend="svn.serverconfig.svnserve"/> for
 details of
        the <filename>svnserve.conf</filename> file.</para>

 @@ -6283,7 +6458,7 @@
        <title><command>svnserve</command> Switches</title>

        <para>Unlike the previous commands we've
 -        described. <command>svnserve</command> has no
 +        described, <command>svnserve</command> has no
          subcommands—<command>svnserve</command> is controlled
          exclusively by switches.</para>

 @@ -6300,6 +6475,8 @@
          </varlistentry>

          <varlistentry>
 +          <!-- might this be a good place to restate what's at
 +          http://subversion.tigris.org/faq.html#freebsd-listen-host ? -->
            <term><option>--listen-
 port</option>=<replaceable>PORT</replaceable></term>
            <listitem>
              <para>Causes svnserve to listen on
 @@ -6368,19 +6545,25 @@
            <listitem>
              <para>Causes <command>svnserve</command> to run in tunnel
                mode, which is just like the <command>inetd</command>
 -              mode of operation (serve one connection over
 -              stdin/stdout) except that the connection is considered
 +              mode of operation (both modes serve one connection over
 +              stdin/stdout, then exit), except that the connection is
 considered
                to be pre-authenticated with the username of the current
 -              uid.  This flag is selected by the client when running
 +              uid.  This flag is automatically passed for you by the
 client when running
                over a tunnel agent such as
 -              <command>ssh</command>.</para>
 +              <command>ssh</command>.
 +            That means there's rarely any need
 +            for <emphasis>you</emphasis>, the human, to pass this
 +            switch to <command>svnserve</command>.  So if you find
 yourself
 +            typing <literal>svnserve --tunnel</literal> on the
 +            command line, and wondering what to do next,
 +            read <xref linkend="svn.serverconfig.svnserve.sshauth"/>
 again.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>--tunnel-user NAME</option></term>
            <listitem>
 -            <para>Used in conjunction with <option>--tunnel</option>
 +            <para>Used in conjunction with the <option>--tunnel</option>
                switch; tells svnserve to assume that
                <replaceable>NAME</replaceable> is the authenticated
                user, rather than the UID of the svnserve
 @@ -6391,6 +6574,8 @@
          </varlistentry>

          <varlistentry>
 +          <!-- what's the benefit of this switch?  That is, when
 +          should I use it, and when shouldn't I? -->
            <term><option>--threads</option> (<option>-T</option>)</term>
            <listitem>
              <para>When running in daemon mode, causes
 @@ -6448,6 +6633,10 @@
            resultant revision number, or revision range, is written to
            standard output.</para>

 +        <para>It's common for a build script to include this output
 +        in a file that defines the version number of a
 +        program.</para>
 +
          <para><replaceable>TRAIL_URL</replaceable>, if present, is the
            trailing portion of the URL used to determine if
            <replaceable>WC_PATH</replaceable> itself is switched
 @@ -6455,9 +6644,9 @@
            <replaceable>WC_PATH</replaceable> does not rely on
            <replaceable>TRAIL_URL</replaceable>).</para>

 -        <para>When WC_PATH is not defined the current directory
 -          will be used as the working copy path.  TRAIL_URL cannot be
 -          defined if WC_PATH is not explicitly given.</para>
 +        <para>When <replaceable>WC_PATH</replaceable> is not defined, the
 current directory
 +          will be used as the working copy path.
 <replaceable>TRAIL_URL</replaceable> cannot be
 +          defined if <replaceable>WC_PATH</replaceable> is not explicitly
 given.</para>

        </refsect1>

 @@ -6515,8 +6704,12 @@
  4168
  </screen>

 -        <para>You can add TRAIL_URL to show that the working copy is
 -          not switched from what you expect.  Note that the WC_PATH was
 +        <!--  I gotta say, this doesn't clarify the purpose of
 +        TRAIL_URL for me.  Can you also give an example where
 +        specifying TRAIL_URL causes svnversion to emit different
 +        output than when we don't specify it? -->
 +        <para>You can add <replaceable>TRAIL_URL</replaceable> to show
 that the working copy is
 +          not switched from what you expect.  Note that the
 <replaceable>WC_PATH</replaceable> was
            required in this command:</para>

          <screen>
 @@ -6670,6 +6863,7 @@
              <term><literal>SVNReposName</literal></term>
              <listitem>

 +              <!-- shouldn't this say "GET responses" instead of "GET
 requests"?  -->
                <para>Specifies the name of a Subversion repository for
                  use in <literal>HTTP GET</literal> requests.  This
                  value will be prepended to the title of all directory
 @@ -6730,10 +6924,10 @@
      <para>Subversion allows users to invent arbitrarily-named
        versioned properties on files and directories, as well as
        unversioned properties on revisions.  The only restriction is on
 -      properties prefixed with <quote>svn:</quote>.  Properties in
 -      that namespace are reserved for Subversion's own use.  While
 +      properties whose names begin with <literal>svn:</literal>—
 +      those are reserved for Subversion's own use.  While
        these properties may be set by users to control Subversion's
 -      behavior, users may not invent new <quote>svn:</quote>
 +      behavior, users may not invent new <literal>svn:</literal>
        properties.</para>

      <sect2 id="svn.ref.properties.versioned-props">
 @@ -6773,7 +6967,7 @@
            <listitem>

              <para>If present on a directory, the value is a list of
 -              unversioned file patterns to be ignored
 +              <emphasis>unversioned</emphasis> file patterns to be
 ignored
                by <command>svn status</command> and other
                subcommands.  See
                <xref
 @@ -6801,9 +6995,11 @@

              <para>If present on a file, the value tells the client
                how to manipulate the file's line-endings in the
 -              working copy.  See
 +              working copy, and in exported trees.  See
                <xref
 -              linkend="svn.advanced.props.special.eol-style"/>.</para>
 +              linkend="svn.advanced.props.special.eol-style"/> and
 +              <xref linkend="svn.ref.svn.c.export"
 +/>.</para>

            </listitem>
          </varlistentry>
 @@ -6827,7 +7023,10 @@

              <para>If present on a file, indicates that the file is
                not an ordinary file, but a symbolic link or other
 -              special object.</para>
 +              special object<footnote><para>As of this writing,
 +              symbolic links are indeed the
 +              only <quote>special</quote> objects.  But there might
 +              be more in future releases of
 Subversion.</para></footnote>.</para>

            </listitem>
          </varlistentry>
 @@ -6869,8 +7068,8 @@
            <listitem>

              <para>Contains the UTC time the revision was created, in
 -              ISO format.  The value comes from the server
 -              machine's clock.</para>
 +              ISO 8601 format.  The value comes from the
 <emphasis>server</emphasis>
 +              machine's clock, not the client's.</para>

            </listitem>
          </varlistentry>
 @@ -6958,6 +7157,11 @@
          <para>access control</para>
        </refsect1>

 +      <!-- an example would be nice here.  I'm guessing that in 1.4
 +      and earlier, people used the pre-commit hook for access control,
 +      and presumably that didn't work well - else why was this hook
 +      invented?  So it'd be nice to explain why start-commit is better
 +      than pre-commit, at least in that case.  -->
      </refentry>

      <!-- ===============================================================
 -->
 @@ -7034,12 +7238,12 @@

          <para>The post-commit hook is run after the transaction is
            committed, and a new revision created.  Most people use
 -          this hook to send out descriptive emails about the commit
 +          this hook to send out descriptive emails about the commit,
            or to notify some other tool (such as an issue tracker)
            that a commit has happened.  Some configurations also use
            this hook to trigger backup processes.</para>

 -        <para>The output from and exit value returned by the
 +        <para>The output from, and exit value returned by, the
            post-commit hook program are ignored.</para>

        </refsect1>
 @@ -7093,9 +7297,9 @@
            exit value before a revision property modification can
            happen.</para>

 -        <para>If the pre-revprop-change hook is not implemented or the
 -          hook program returns a non-zero exit value, no change to the
 -          property will be made, and anything printed to stderr is
 +        <para>If the pre-revprop-change hook doesn't exist, isn't
 +          executable, or returns a non-zero exit value, no change to
 +          the property will be made, and anything printed to stderr is
            marshalled back to the client.</para>

        </refsect1>
 @@ -7123,8 +7327,8 @@
            </listitem>
          </orderedlist>

 -        <para>Additionally, Subversion passes to the hook program via
 -          standard input the proposed value of the property.</para>
 +        <para>Additionally, Subversion passes to the hook program, via
 +          standard input, the proposed value of the property.</para>

        </refsect1>

 @@ -7162,7 +7366,7 @@
            typically used to send email notification of the property
            change.</para>

 -        <para>The output from and exit value returned by the
 +        <para>The output from, and exit value returned by, the
            post-revprop-change hook program are ignored.</para>

        </refsect1>
 @@ -7193,8 +7397,8 @@
            </listitem>
          </orderedlist>

 -        <para>Additionally, Subversion passes to the hook program via
 -          standard input the previous value of the property.</para>
 +        <para>Additionally, Subversion passes to the hook program, via
 +          standard input, the previous value of the property.</para>

        </refsect1>

 @@ -7230,7 +7434,7 @@
            allowed to <quote>steal</quote> the existing lock.</para>

          <para>If the pre-lock hook program returns a non-zero exit
 -          value, the lock action is aborted and anything printed to
 +          value, the lock action is aborted, and anything printed to
            stderr is marshalled back to the client.</para>

        </refsect1>
 @@ -7283,7 +7487,7 @@
            locked.  It is typically used to send email notification of
            the lock event.</para>

 -        <para>The output from and exit value returned by the post-look
 +        <para>The output from, and exit value returned by, the post-lock
            hook program are ignored.</para>

        </refsect1>
 @@ -7305,7 +7509,7 @@
          </orderedlist>

          <para>Additionally, the list of paths locked is passed to the
 -          hook program via standard input, one path per line.</para>
 +          hook program, via standard input, one path per line.</para>

        </refsect1>

 @@ -7343,7 +7547,7 @@
            by the hook.</para>

          <para>If the pre-unlock hook program returns a non-zero exit
 -          value, the unlock action is aborted and anything printed to
 +          value, the unlock action is aborted, and anything printed to
            stderr is marshalled back to the client.</para>

        </refsect1>
 @@ -7396,7 +7600,7 @@
            been unlocked.  It is typically used to send email
            notification of the unlock event.</para>

 -        <para>The output from and exit value returned by the
 +        <para>The output from, and exit value returned by, the
            post-unlock hook program are ignored.</para>

        </refsect1>


 }}}

-- 
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/65>
SvnBook <http://svnbook.red-bean.com/>


More information about the svnbook-dev mailing list