[svnbook] r4416 committed - * en/book/ch00-preface.xml,...

svnbook at googlecode.com svnbook at googlecode.com
Fri Feb 8 10:10:04 CST 2013


Revision: 4416
Author:   cmpilato at gmail.com
Date:     Fri Feb  8 08:09:53 2013
Log:      * en/book/ch00-preface.xml,
* en/book/ch01-fundamental-concepts.xml,
* en/book/ch02-basic-usage.xml,
* en/book/ch03-advanced-topics.xml
   More indexing work.
http://code.google.com/p/svnbook/source/detail?r=4416

Modified:
  /trunk/en/book/ch00-preface.xml
  /trunk/en/book/ch01-fundamental-concepts.xml
  /trunk/en/book/ch02-basic-usage.xml
  /trunk/en/book/ch03-advanced-topics.xml

=======================================
--- /trunk/en/book/ch00-preface.xml	Fri Feb  8 06:49:58 2013
+++ /trunk/en/book/ch00-preface.xml	Fri Feb  8 08:09:53 2013
@@ -61,7 +61,6 @@
      <para>
        <indexterm>
          <primary>Subversion</primary>
-        <secondary>defined</secondary>
        </indexterm>
        <indexterm>
          <primary>version control system</primary>
=======================================
--- /trunk/en/book/ch01-fundamental-concepts.xml	Fri Feb  8 06:49:58 2013
+++ /trunk/en/book/ch01-fundamental-concepts.xml	Fri Feb  8 08:09:53 2013
@@ -48,7 +48,6 @@
        <para>
          <indexterm>
            <primary>repository</primary>
-          <secondary>defined</secondary>
          </indexterm>
          <indexterm>
            <primary>repository</primary>
@@ -100,8 +99,7 @@

        <para>
          <indexterm>
-          <primary>working copy</primary>
-          <secondary>defined</secondary>
+          <primary>working copies</primary>
          </indexterm>A version control system's value comes from the
          fact that it tracks versions of files and directories, but the
          rest of the software universe doesn't operate
@@ -318,8 +316,7 @@

          <para>
            <indexterm>
-            <primary>conflicts</primary>
-            <secondary>defined</secondary>
+            <primary>conflict</primary>
            </indexterm>But what if Sally's changes
            <emphasis>do</emphasis> overlap with Harry's changes?  What
            then?  This situation is called a
@@ -431,7 +428,6 @@
        <para>
          <indexterm>
            <primary>revision</primary>
-          <secondary>defined</secondary>
          </indexterm>Each time the repository accepts a commit, this
          creates a new state of the filesystem tree, called a
          <firstterm>revision</firstterm>.  Each revision is assigned a
@@ -669,8 +665,7 @@

        <para>
          <indexterm>
-          <primary>working copy</primary>
-          <secondary>defined</secondary>
+          <primary>working copies</primary>
          </indexterm>A Subversion working copy is an ordinary directory
          tree on your local system, containing a collection of files.
          You can edit these files however you wish, and if they're
@@ -697,7 +692,6 @@
        <para>
          <indexterm>
            <primary>administrative directory</primary>
-          <secondary>defined</secondary>
          </indexterm>
          <indexterm>
            <primary>.svn</primary>
@@ -857,8 +851,8 @@
              <primary>checking out</primary>
            </indexterm>
            <indexterm>
-            <primary>working copy</primary>
-            <secondary>creation</secondary>
+            <primary>working copies</primary>
+            <secondary>creating</secondary>
              <see>checking out</see>
            </indexterm>To get a working copy, you must <firstterm>check
            out</firstterm> some subtree of the repository.  (The term
@@ -892,7 +886,6 @@
          <para>
            <indexterm>
              <primary>committing</primary>
-            <secondary>defined</secondary>
            </indexterm>
            <indexterm>
              <primary>checking in</primary>
@@ -952,8 +945,8 @@
              <primary>updating</primary>
            </indexterm>
            <indexterm>
-            <primary>working copy</primary>
-            <secondary>update</secondary>
+            <primary>working copies</primary>
+            <secondary>updating</secondary>
              <see>updating</see>
            </indexterm>To bring her project up to date, Sally can ask
            Subversion to <firstterm>update</firstterm> her working
@@ -992,7 +985,7 @@

          <para>
            <indexterm>
-            <primary>working copy</primary>
+            <primary>working copies</primary>
              <secondary>mixed-revision</secondary>
            </indexterm>As a general principle, Subversion tries to be
            as flexible as possible.  One special kind of flexibility is
=======================================
--- /trunk/en/book/ch02-basic-usage.xml	Thu Feb  7 12:43:50 2013
+++ /trunk/en/book/ch02-basic-usage.xml	Fri Feb  8 08:09:53 2013
@@ -227,19 +227,6 @@
      <sect2 id="svn.tour.importing.layout">
        <title>Recommended Repository Layout</title>

-      <indexterm>
-        <primary>trunk</primary>
-      </indexterm>
-      <indexterm>
-        <primary>tags</primary>
-      </indexterm>
-      <indexterm>
-        <primary>branches</primary>
-      </indexterm>
-      <indexterm>
-        <primary>project root</primary>
-      </indexterm>
-
        <para>Subversion provides the ultimate flexibility in terms of
          how you arrange your data.  Because it simply versions
          directories and files, and because it ascribes no particular
@@ -251,12 +238,24 @@
          completely different and unpredictable arrangements of the
          data within them.</para>

-      <para>To counteract this confusion, we recommend that you follow
-        a repository layout convention (established long ago, in the
-        nascency of the Subversion project itself) in which a handful
-        of strategically named Subversion repository directories
-        convey valuable meaning about the data they hold.  Most
-        projects have a recognizable <quote>main line</quote>,
+      <para>
+        <indexterm>
+          <primary>trunk</primary>
+        </indexterm>
+        <indexterm>
+          <primary>tags</primary>
+        </indexterm>
+        <indexterm>
+          <primary>branches</primary>
+        </indexterm>
+        <indexterm>
+          <primary>project root</primary>
+        </indexterm>To counteract this confusion, we recommend that
+        you follow a repository layout convention (established long
+        ago, in the nascency of the Subversion project itself) in
+        which a handful of strategically named Subversion repository
+        directories convey valuable meaning about the data they hold.
+        Most projects have a recognizable <quote>main line</quote>,
          or <firstterm>trunk</firstterm>, of development;
          some <firstterm>branches</firstterm>, which are divergent
          copies of development lines; and
@@ -375,13 +374,12 @@
    <sect1 id="svn.tour.initial">
      <title>Creating a Working Copy</title>

-    <indexterm>
-      <primary>svn</primary>
-      <secondary>subcommands</secondary>
-      <tertiary>checkout</tertiary>
-    </indexterm>
-
-    <para>Most of the time, you will start using a Subversion
+    <para>
+      <indexterm>
+        <primary>svn</primary>
+        <secondary>subcommands</secondary>
+        <tertiary>checkout</tertiary>
+      </indexterm>Most of the time, you will start using a Subversion
        repository by performing a <firstterm>checkout</firstterm> of
        your project.  Checking out a directory from a repository
        creates a working copy of that directory on your local machine.
@@ -610,19 +608,25 @@
      <sect2 id="svn.tour.cycle.edit">
        <title>Make Your Changes </title>

-      <para>Now you can get to work and make changes in your working
-        copy.  You can make two kinds of changes to your working
-        copy: <firstterm>file changes</firstterm> and <firstterm>tree
-        changes</firstterm>.  You don't need to tell Subversion that
-        you intend to change a file; just make your changes using your
-        text editor, word processor, graphics program, or whatever
-        tool you would normally use.  Subversion automatically detects
-        which files have been changed, and in addition, it handles
-        binary files just as easily as it handles text files—and
-        just as efficiently, too.  Tree changes are different, and
-        involve changes to a directory's structure.  Such changes
-        include adding and removing files, renaming files or
-        directories, and copying files or directories to new
+      <para>
+        <indexterm>
+          <primary>file changes</primary>
+        </indexterm>
+        <indexterm>
+          <primary>tree changes</primary>
+        </indexterm>Now you can get to work and make changes in your
+        working copy.  You can make two kinds of changes to your
+        working copy: <firstterm>file changes</firstterm>
+        and <firstterm>tree changes</firstterm>.  You don't need to
+        tell Subversion that you intend to change a file; just make
+        your changes using your text editor, word processor, graphics
+        program, or whatever tool you would normally use.  Subversion
+        automatically detects which files have been changed, and in
+        addition, it handles binary files just as easily as it handles
+        text files—and just as efficiently, too.  Tree changes
+        are different, and involve changes to a directory's structure.
+        Such changes include adding and removing files, renaming files
+        or directories, and copying files or directories to new
          locations.  For tree changes, you use Subversion operations
          to <quote>schedule</quote> files and directories for removal,
          addition, copying, or moving.  These changes may take place
@@ -632,8 +636,15 @@
        <sidebar>
          <title>Versioning Symbolic Links</title>

-        <para>On non-Windows platforms, Subversion is able to version
-          files of the special type <firstterm>symbolic
+        <para>
+          <indexterm>
+            <primary>svmlink</primary>
+          </indexterm>
+          <indexterm>
+            <primary>svmbolic link</primary>
+            <see>symlink</see>
+          </indexterm>On non-Windows platforms, Subversion is able to
+          version files of the special type <firstterm>symbolic
            link</firstterm> (or <quote>symlink</quote>).  A symlink is
            a file that acts as a sort of transparent reference to some
            other object in the filesystem, allowing programs to read
@@ -802,11 +813,10 @@
      <sect2 id="svn.tour.cycle.examine">
        <title>Review Your Changes</title>

-      <indexterm>
-        <primary>log message</primary>
-      </indexterm>
-
-      <para>Once you've finished making changes, you need to commit
+      <para>
+        <indexterm>
+          <primary>log message</primary>
+        </indexterm>Once you've finished making changes, you need to commit
          them to the repository, but before you do so, it's usually a
          good idea to take a look at exactly what you've changed.  By
          examining your changes before you commit, you can compose a
@@ -832,20 +842,20 @@
            when you are working offline or are otherwise unable to
            contact your repository over the network.</para>

-        <indexterm>
-          <primary>text-base</primary>
-        </indexterm>
-        <indexterm>
-          <primary>delta</primary>
-        </indexterm>
-
-        <para>Subversion does this by keeping private caches of
-          pristine, unmodified versions of each versioned file inside
-          its working copy administrative area (or prior to version 1.7,
-          potentially multiple administrative areas).  This allows
-          Subversion to report—and revert—local
-          modifications to those files <emphasis>without network
-          access</emphasis>.  This cache (called the
+        <para>
+          <indexterm>
+            <primary>text-base</primary>
+          </indexterm>
+          <indexterm>
+            <primary>delta</primary>
+          </indexterm>Subversion does this by keeping private caches
+          of pristine, unmodified versions of each versioned file
+          inside its working copy administrative area (or prior to
+          version 1.7, potentially multiple administrative areas).
+          This allows Subversion to report—and
+          revert—local modifications to those
+          files <emphasis>without network access</emphasis>.  This
+          cache (called the
            <firstterm>text-base</firstterm>) also allows Subversion to
            send the user's local modifications during a commit to the
            server as a compressed <firstterm>delta</firstterm> (or
@@ -1051,16 +1061,16 @@
        <sect3 id="svn.tour.cycle.examine.diff">
          <title>Examine the details of your local modifications</title>

-        <indexterm>
-          <primary>svn</primary>
-          <secondary>subcommands</secondary>
-          <tertiary>diff</tertiary>
-        </indexterm>
-        <indexterm>
-          <primary>unified diff</primary>
-        </indexterm>
-
-        <para>Another way to examine your changes is with the
+        <para>
+          <indexterm>
+            <primary>svn</primary>
+            <secondary>subcommands</secondary>
+            <tertiary>diff</tertiary>
+          </indexterm>
+          <indexterm>
+            <primary>diff</primary>
+            <secondary>unified</secondary>
+          </indexterm>Another way to examine your changes is with the
            <command>svn diff</command> command, which displays
            differences in file content.  When you run <userinput>svn
            diff</userinput> at the top of your working copy with no
@@ -1123,11 +1133,19 @@
  </screen>
          </informalexample>

-        <indexterm>
-          <primary>patches</primary>
-        </indexterm>
-
-        <para>The <command>svn diff</command> command produces this
+        <para>
+          <indexterm>
+            <primary>svn</primary>
+            <secondary>subcommands</secondary>
+            <tertiary>patch</tertiary>
+          </indexterm>
+          <indexterm>
+            <primary>patch</primary>
+          </indexterm>
+          <indexterm>
+            <primary>patch file</primary>
+            <see>patch</see>
+          </indexterm>The <command>svn diff</command> command produces this
            output by comparing your working files against its pristine
            text-base.  Files scheduled for addition are displayed as
            files in which every line was added; files scheduled for
@@ -1267,7 +1285,7 @@
        <title>Resolve Any Conflicts</title>

        <indexterm>
-        <primary>conflicts</primary>
+        <primary>conflict</primary>
          <secondary>resolving</secondary>
        </indexterm>

@@ -1468,7 +1486,7 @@
          <title>Viewing conflict differences interactively</title>

          <indexterm>
-          <primary>conflicts</primary>
+          <primary>conflict</primary>
            <secondary>reviewing</secondary>
          </indexterm>

@@ -1530,7 +1548,7 @@
          <title>Resolving conflict differences interactively</title>

          <indexterm>
-          <primary>conflicts</primary>
+          <primary>conflict</primary>
            <secondary>resolution</secondary>
            <tertiary>interactive</tertiary>
          </indexterm>
@@ -1591,7 +1609,7 @@
          <title>Postponing conflict resolution</title>

          <indexterm>
-          <primary>conflicts</primary>
+          <primary>conflict</primary>
            <secondary>resolution</secondary>
            <tertiary>postponing</tertiary>
          </indexterm>
@@ -1620,7 +1638,7 @@
          <itemizedlist>

            <indexterm>
-            <primary>conflicts</primary>
+            <primary>conflict</primary>
              <secondary>conflict markers</secondary>
            </indexterm>

@@ -1800,7 +1818,7 @@
          <title>Manual conflict resolution</title>

          <indexterm>
-          <primary>conflicts</primary>
+          <primary>conflict</primary>
            <secondary>resolution</secondary>
            <tertiary>manual</tertiary>
          </indexterm>
@@ -1927,7 +1945,7 @@
            revision</title>

          <indexterm>
-          <primary>conflicts</primary>
+          <primary>conflict</primary>
            <secondary>resolution</secondary>
          </indexterm>

@@ -2896,8 +2914,16 @@
        markers as resolved and commit them, if you really wanted to.
        But this is rarely done in practice.</para></footnote></para>

-    <para>But what happens if your collaborators move or delete a file
-      that you are still working on?  Maybe there was a
+    <para>
+      <indexterm>
+        <primary>tree conflict</primary>
+      </indexterm>
+      <indexterm>
+        <primary>conflict</primary>
+        <secondary>tree</secondary>
+        <see>tree conflict</see>
+      </indexterm>But what happens if your collaborators move or
+      delete a file that you are still working on?  Maybe there was a
        miscommunication, and one person thinks the file should be
        deleted, while another person still wants to commit changes to
        the file.  Or maybe your collaborators did some refactoring,
@@ -3116,9 +3142,9 @@
  </screen>
        </informalexample>

-      <para><filename>bar.c</filename> is now said to be the
-        <firstterm>victim</firstterm> of a tree conflict.
-        It cannot be committed until the conflict is resolved:</para>
+      <para><filename>bar.c</filename> is now said to be the victim of
+        a tree conflict.  It cannot be committed until the conflict is
+        resolved:</para>

        <informalexample>
          <screen>
=======================================
--- /trunk/en/book/ch03-advanced-topics.xml	Thu Feb  7 12:43:50 2013
+++ /trunk/en/book/ch03-advanced-topics.xml	Fri Feb  8 08:09:53 2013
@@ -61,9 +61,13 @@
          syntax.</para>
      </note>

-    <para>But occasionally, you need to pinpoint a moment in time for
-      which you don't already have a revision number memorized or
-      handy.  So besides the integer revision numbers,
+    <para>
+      <indexterm>
+        <primary>revision</primary>
+        <secondary>keywords</secondary>
+      </indexterm>But occasionally, you need to pinpoint a moment in
+      time for which you don't already have a revision number
+      memorized or handy.  So besides the integer revision numbers,
        <command>svn</command> allows as input some additional forms of
        revision specifiers: <firstterm>revision keywords</firstterm>
        and revision dates.</para>
@@ -405,21 +409,45 @@
        street.  Our motorist—and our Subversion—need a
        little more detail to do the right thing.</para>

-    <para>Fortunately, Subversion allows you to tell it exactly which
-      Main Street you meant.  The mechanism used is called a
-      <firstterm>peg revision</firstterm>, and you provide these to
-      Subversion for the sole purpose of identifying unique lines of
-      history.  Because at most one versioned object may occupy a path
-      at any given time—or, more precisely, in any one
-      revision—the combination of a path and a peg revision is
-      all that is needed to unambiguously identify a specific line
+    <para>
+      <indexterm>
+        <primary>revision</primary>
+        <secondary>peg revision</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>at syntax</primary>
+        <see>syntax, at syntax</see>
+      </indexterm>
+      <indexterm>
+        <primary>@</primary>
+        <see>syntax, at syntax</see>
+      </indexterm>
+      <indexterm>
+        <primary>syntax</primary>
+        <secondary>at syntax</secondary>
+      </indexterm>Fortunately, Subversion allows you to tell it
+      exactly which Main Street you meant.  The mechanism used is
+      called a <firstterm>peg revision</firstterm>, and you provide
+      these to Subversion for the sole purpose of identifying unique
+      lines of history.  Because at most one versioned object may
+      occupy a path at any given time—or, more precisely, in any
+      one revision—the combination of a path and a peg revision
+      is all that is needed to unambiguously identify a specific line
        of history.  Peg revisions are specified to the Subversion
        command-line client using <firstterm>at syntax</firstterm>, so
        called because the syntax involves appending an <quote>at
        sign</quote> (<literal>@</literal>) and the peg revision to the
        end of the path with which the revision is associated.</para>

-    <para>But what of the <option>--revision</option>
+    <para>
+      <indexterm>
+        <primary>revision</primary>
+        <secondary>operative revision</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>revision</primary>
+        <secondary>operative revision range</secondary>
+      </indexterm>But what of the <option>--revision</option>
        (<option>-r</option>) of which we've spoken so much in this
        book?  That revision (or set of revisions) is called the
        <firstterm>operative revision</firstterm> (or
@@ -673,10 +701,6 @@
    <sect1 id="svn.advanced.props">
      <title>Properties</title>

-    <indexterm>
-      <primary>properties</primary>
-    </indexterm>
-
      <para>We've already covered in detail how Subversion stores and
        retrieves various versions of files and directories in its
        repository.  Whole chapters have been devoted to this most
@@ -686,7 +710,10 @@

      <para>But it doesn't stop there.</para>

-    <para>In addition to versioning your directories and files,
+    <para>
+      <indexterm>
+        <primary>properties</primary>
+      </indexterm>In addition to versioning your directories and files,
        Subversion provides interfaces for adding, modifying, and
        removing versioned metadata on each of your versioned
        directories and files.  We refer to this metadata as
@@ -2147,7 +2174,11 @@
        <sect3 id="svn.advanced.props.ref.ephemeral">
          <title>Ephemeral transaction properties</title>

-        <para>Subversion reserves a set of <firstterm>ephemeral
+        <para>
+          <indexterm>
+            <primary>properties</primary>
+            <secondary>ephemeral transaction properties</secondary>
+          </indexterm>Subversion reserves a set of <firstterm>ephemeral
            transaction properties</firstterm> for its own use.  These
            are essentially commit transaction properties which are set
            by the client at the earliest opportunity during the commit
@@ -2406,8 +2437,15 @@
          whether contextual difference reports for that file are
          possible.  Otherwise, to Subversion, bytes are bytes.</para>

-      <para>This means that by default, Subversion doesn't pay any
-        attention to the type of <firstterm>end-of-line (EOL)
+      <para>
+        <indexterm>
+          <primary>line endings</primary>
+        </indexterm>
+        <indexterm>
+          <primary>end-of-line (EOL)</primary>
+          <see>line endings, defined</see>
+        </indexterm>This means that by default, Subversion doesn't pay
+        any attention to the type of <firstterm>end-of-line (EOL)
          markers</firstterm> used in your files.  Unfortunately,
          different operating systems have different conventions about
          which character sequences represent the end of a line of text
@@ -2418,9 +2456,13 @@
          software, however, just uses the <literal>LF</literal>
          character to denote the end of a line.</para>

-      <para>Not all of the various tools on these operating systems
-        understand files that contain line endings in a format that
-        differs from the <firstterm>native line-ending
+      <para>
+        <indexterm>
+          <primary>line endings</primary>
+          <secondary>native</secondary>
+        </indexterm>Not all of the various tools on these operating
+        systems understand files that contain line endings in a format
+        that differs from the <firstterm>native line-ending
          style</firstterm> of the operating system on which they are
          running.  So, typically, Unix programs treat the
          <literal>CR</literal> character present in Windows files as a
@@ -2554,19 +2596,31 @@
        directories—its output can get quite noisy where many of
        these things exist.</para>

-    <para>So Subversion provides several ways for telling it which files
-      you would prefer that it simply disregard.  One of the ways
-      involves the use of Subversion's runtime configuration system
-      (see <xref linkend="svn.advanced.confarea" />), and therefore
-      applies to all the Subversion operations that make use of that
-      runtime configuration—generally those performed on a particular
-      computer or by a particular user of a computer.  Two other methods
-      make use of Subversion's directory property support and are more
-      tightly bound to the versioned tree itself, and therefore
-      affects everyone who has a working copy of that tree.  All of
-      these mechanisms use <firstterm>file patterns</firstterm> (strings
-      of literal and special wildcard characters used to match against
-      filenames) to decide which files to ignore.</para>
+    <para>
+      <indexterm>
+        <primary>file patterns</primary>
+      </indexterm>
+      <indexterm>
+        <primary>globs</primary>
+        <see>file patterns</see>
+      </indexterm>
+      <indexterm>
+        <primary>shell wildcard patterns</primary>
+        <see>file patterns</see>
+      </indexterm>So Subversion provides several ways for telling it
+      which files you would prefer that it simply disregard.  One of
+      the ways involves the use of Subversion's runtime configuration
+      system (see <xref linkend="svn.advanced.confarea" />), and
+      therefore applies to all the Subversion operations that make use
+      of that runtime configuration—generally those performed on
+      a particular computer or by a particular user of a computer.
+      Two other methods make use of Subversion's directory property
+      support and are more tightly bound to the versioned tree itself,
+      and therefore affects everyone who has a working copy of that
+      tree.  All of these mechanisms use <firstterm>file
+      patterns</firstterm> (strings of literal and special wildcard
+      characters used to match against filenames) to decide which
+      files to ignore.</para>

      <para>The Subversion runtime configuration system provides an
        option, <literal>global-ignores</literal>, whose value is a
@@ -2931,7 +2985,10 @@
    <sect1 id="svn.advanced.props.special.keywords">
      <title>Keyword Substitution</title>

-    <para>Subversion has the ability to substitute
+    <para>
+      <indexterm>
+        <primary>keywords</primary>
+      </indexterm>Subversion has the ability to substitute
        <firstterm>keywords</firstterm>—pieces of useful,
        dynamic information about a versioned file—into the
        contents of the file itself.  Keywords generally provide
@@ -2969,6 +3026,56 @@
        some of which have aliases that you can also use:</para>

      <variablelist>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>Date</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>LastChangedDate</secondary>
+        <see>keywords, Date</see>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>Revision</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>LastChangedRevision</secondary>
+        <see>keywords, Revision</see>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>Rev</secondary>
+        <see>keywords, Revision</see>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>Author</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>LastChangedBy</secondary>
+        <see>keywords, Author</see>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>HeadURL</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>URL</secondary>
+        <see>keywords, HeadURL</see>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>Id</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>keywords</primary>
+        <secondary>Header</secondary>
+      </indexterm>
+
        <varlistentry>
          <term><literal>Date</literal></term>
          <listitem>
@@ -3280,13 +3387,21 @@
    <sect1 id="svn.advanced.sparsedirs">
      <title>Sparse Directories</title>

-    <para>By default, most Subversion operations on directories act in
-      a recursive manner.  For example, <command>svn
-      checkout</command> creates a working copy with every file and
-      directory in the specified area of the repository, descending
-      recursively through the repository tree until the entire
-      structure is copied to your local disk.  Subversion 1.5
-      introduces a feature called <firstterm>sparse
+    <para>
+      <indexterm>
+        <primary>sparse directories</primary>
+      </indexterm>
+      <indexterm>
+        <primary>checkouts</primary>
+        <secondary>shallow</secondary>
+        <see>sparse directories</see>
+      </indexterm>By default, most Subversion operations on
+      directories act in a recursive manner.  For
+      example, <command>svn checkout</command> creates a working copy
+      with every file and directory in the specified area of the
+      repository, descending recursively through the repository tree
+      until the entire structure is copied to your local disk.
+      Subversion 1.5 introduces a feature called <firstterm>sparse
        directories</firstterm> (or <firstterm>shallow
        checkouts</firstterm>) that allows you to easily check out a
        working copy—or a portion of a working copy—more
@@ -3345,6 +3460,23 @@

      <variablelist>

+      <indexterm>
+        <primary>depth</primary>
+        <secondary>empty</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>depth</primary>
+        <secondary>files</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>depth</primary>
+        <secondary>immediates</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>depth</primary>
+        <secondary>infinity</secondary>
+      </indexterm>
+
        <varlistentry>
          <term><literal>--depth empty</literal></term>
          <listitem>
@@ -3381,7 +3513,11 @@

      </variablelist>

-    <para>Of course, merely combining two existing options into one
+    <para>
+      <indexterm>
+        <primary>depth</primary>
+        <secondary>ambient</secondary>
+      </indexterm>Of course, merely combining two existing options into one
        hardly constitutes a new feature worthy of a whole section in
        our book.  Fortunately, there is more to this story.  This idea
        of depth extends not just to the operations you perform with
@@ -3389,11 +3525,11 @@
        copy citizen's <firstterm>ambient depth</firstterm>, which is
        the depth persistently recorded by the working copy for that
        item.  Its key strength is this very persistence—the fact
-      that it is <firstterm>sticky</firstterm>.  The working copy
-      remembers the depth you've selected for each item in it until
-      you later change that depth selection; by default, Subversion
-      commands operate on the working copy citizens present,
-      regardless of their selected depth settings.</para>
+      that it is <quote>sticky</quote>.  The working copy remembers
+      the depth you've selected for each item in it until you later
+      change that depth selection; by default, Subversion commands
+      operate on the working copy citizens present, regardless of
+      their selected depth settings.</para>

      <tip>
        <para>You can check the recorded ambient depth of a working copy
@@ -3740,17 +3876,25 @@
        made, and then spit out an image of a busted-up red Mustang with
        a cracked windshield!</para>

-    <para>Of course, things would have gone more smoothly if Harry and
-      Sally had serialized their modifications to the image—if,
-      say, Harry had waited to draw his windshield cracks on Sally's
-      now-red car, or if Sally had tweaked the color of a car whose
-      windshield was already cracked.  As is discussed in
-      <xref linkend="svn.basic.vsn-models.copy-merge" />, most of
+    <para>
+      <indexterm>
+        <primary>locks</primary>
+      </indexterm>
+      <indexterm>
+        <primary>checkouts</primary>
+        <secondary>reserved</secondary>
+        <see>locking</see>
+      </indexterm>Of course, things would have gone more smoothly if
+      Harry and Sally had serialized their modifications to the
+      image—if, say, Harry had waited to draw his windshield
+      cracks on Sally's now-red car, or if Sally had tweaked the color
+      of a car whose windshield was already cracked.  As is discussed
+      in <xref linkend="svn.basic.vsn-models.copy-merge" />, most of
        these types of problems go away entirely where perfect
        communication between Harry and Sally
        exists.<footnote><para>Communication wouldn't have been such bad
        medicine for Harry and Sally's Hollywood namesakes, either, for
-      that matter.</para></footnote>  But as one's version control
+      that matter.</para></footnote> But as one's version control
        system is, in fact, one form of communication, it follows that
        having that software facilitate the serialization of
        nonparallelizable editing efforts is no bad thing.  This is
@@ -3794,22 +3938,30 @@
          of <quote>lock</quote> with which Subversion, and therefore
          this book, sometimes needs to be concerned.</para>

-      <para>The second is <firstterm>working copy locks</firstterm>,
-        used internally by Subversion to prevent clashes between
-        multiple Subversion clients operating on the same working
-        copy.  This is the sort of lock indicated by an
+      <para>
+        <indexterm>
+          <primary>locks</primary>
+          <secondary>administrative</secondary>
+        </indexterm>The second is <firstterm>administrative
+        locks</firstterm>, used internally by Subversion to prevent
+        clashes between multiple Subversion clients operating on the
+        same working copy.  This is the sort of lock indicated by an
          <computeroutput>L</computeroutput> in the third column of
          <command>svn status</command> output, and removed by the
          <command>svn cleanup</command> command, as described in <xref
          linkend="svn.tour.cleanup"/>.</para>

-      <para>Third, there are <firstterm>database locks</firstterm>,
-        used internally by the Berkeley DB backend to prevent clashes
-        between multiple programs trying to access the database.  This
-        is the sort of lock whose unwanted persistence after an error
-        can cause a repository to be <quote>wedged,</quote> as
-        described in <xref linkend="svn.reposadmin.maint.recovery"
-        />.</para>
+      <para>
+        <indexterm>
+          <primary>locks</primary>
+          <secondary>database</secondary>
+        </indexterm>Third, there are <firstterm>database
+        locks</firstterm>, used internally by the Berkeley DB backend
+        to prevent clashes between multiple programs trying to access
+        the database.  This is the sort of lock whose unwanted
+        persistence after an error can cause a repository to
+        be <quote>wedged,</quote> as described in
+        <xref linkend="svn.reposadmin.maint.recovery" />.</para>

        <para>You can generally forget about these other kinds of locks
          until something goes wrong that requires you to care about
@@ -3823,7 +3975,18 @@
      <sect2 id="svn.advanced.locking.creation">
        <title>Creating Locks</title>

-      <para>In the Subversion repository, a
+      <para>
+        <indexterm>
+          <primary>locks</primary>
+        </indexterm>
+        <indexterm>
+          <primary>locks</primary>
+          <secondary>lock token</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>locking</primary>
+          <secondary>lock owner</secondary>
+        </indexterm>In the Subversion repository, a
          <firstterm>lock</firstterm> is a piece of metadata that
          grants exclusive access to one user to change a file.  This
          user is said to be the <firstterm>lock owner</firstterm>.
@@ -3839,8 +4002,17 @@
          the commit process as a form of proof that the client knows which
          lock it is using.</para>

-      <para>To demonstrate lock creation, let's refer back to our
-        example of multiple graphic designers working on the same
+      <para>
+        <indexterm>
+          <primary>svn</primary>
+          <secondary>subcommands</secondary>
+          <tertiary>lock</tertiary>
+        </indexterm>
+        <indexterm>
+          <primary>locks</primary>
+          <secondary>creation</secondary>
+        </indexterm>To demonstrate lock creation, let's refer back to
+        our example of multiple graphic designers working on the same
          binary image files.  Harry has decided to change a JPEG image.
          To prevent other people from committing changes to the file
          while he is modifying it (as well as alerting them that he is
@@ -3938,17 +4110,22 @@
            authenticating as the lock owner isn't enough to prevent
            accidents.</para>

-        <para>For example, suppose you lock a file using a computer at
-          your office, but leave work for the day before you finish
-          your changes to that file.  It should not be possible to
-          accidentally commit changes to that same file from your home
-          computer later that evening simply because you've
-          authenticated as the lock's owner.  In other words, the lock
-          token prevents one piece of Subversion-related software from
-          undermining the work of another.  (In our example, if you
-          really need to change the file from an alternative working
-          copy, you would need to <firstterm>break</firstterm> the
-          lock and relock the file.)</para>
+        <para>
+          <indexterm>
+            <primary>locks</primary>
+            <secondary>breaking</secondary>
+          </indexterm>For example, suppose you lock a file using a
+          computer at your office, but leave work for the day before
+          you finish your changes to that file.  It should not be
+          possible to accidentally commit changes to that same file
+          from your home computer later that evening simply because
+          you've authenticated as the lock's owner.  In other words,
+          the lock token prevents one piece of Subversion-related
+          software from undermining the work of another.  (In our
+          example, if you really need to change the file from an
+          alternative working copy, you would need
+          to <firstterm>break</firstterm> the lock and relock the
+          file.)</para>

        </sidebar>

@@ -4014,9 +4191,18 @@
          <literal>no-unlock</literal> runtime configuration option (see
          <xref linkend="svn.advanced.confarea" />).</para>

-      <para>Of course, locking a file doesn't oblige one to commit a
-        change to it.  The lock can be released at any time with a
-        simple <command>svn unlock</command> command:</para>
+      <para>
+        <indexterm>
+          <primary>svn</primary>
+          <secondary>subcommands</secondary>
+          <tertiary>unlock</tertiary>
+        </indexterm>
+        <indexterm>
+          <primary>locks</primary>
+          <secondary>releasing</secondary>
+        </indexterm>Of course, locking a file doesn't oblige one to
+        commit a change to it.  The lock can be released at any time
+        with a simple <command>svn unlock</command> command:</para>

        <informalexample>
          <screen>
@@ -4031,7 +4217,16 @@
      <sect2 id="svn.advanced.locking.discovery">
        <title>Discovering Locks</title>

-      <para>When a commit fails due to someone else's locks, it's
+      <para>
+        <indexterm>
+          <primary>svn</primary>
+          <secondary>subcommands</secondary>
+          <tertiary>status</tertiary>
+        </indexterm>
+        <indexterm>
+          <primary>locks</primary>
+          <secondary>discovery</secondary>
+        </indexterm>When a commit fails due to someone else's locks, it's
          fairly easy to learn about them.  The easiest way is to run
          <userinput>svn status -u</userinput>:</para>

@@ -4046,7 +4241,12 @@
  </screen>
        </informalexample>

-      <para>In this example, Sally can see not only that her copy of
+      <para>
+        <indexterm>
+          <primary>svn</primary>
+          <secondary>subcommands</secondary>
+          <tertiary>info</tertiary>
+        </indexterm>In this example, Sally can see not only that her copy  
of
          <filename>foo.h</filename> is out of date, but also that one of the
          two modified files she plans to commit is locked in the
          repository.  The <literal>O</literal> symbol stands for
@@ -4107,7 +4307,11 @@
      <sect2 id="svn.advanced.locking.break-steal">
        <title>Breaking and Stealing Locks</title>

-      <para>A repository lock isn't sacred—in Subversion's
+      <para>
+        <indexterm>
+          <primary>locks</primary>
+          <secondary>breaking</secondary>
+        </indexterm>A repository lock isn't sacred—in Subversion's
          default configuration state, locks can be released not only by
          the person who created them, but by anyone.  When somebody
          other than the original lock creator destroys a lock, we refer
@@ -4180,7 +4384,11 @@
          authorization requirements are ignored, and the remote lock is
          broken.</para>

-      <para>Simply breaking a lock may not be enough.  In
+      <para>
+        <indexterm>
+          <primary>locks</primary>
+          <secondary>stealing</secondary>
+        </indexterm>Simply breaking a lock may not be enough.  In
          the running example, Sally may not only want to break Harry's
          long-forgotten lock, but relock the file for her own use.
          She can accomplish this by using <command>svn unlock</command>
@@ -4203,13 +4411,18 @@
  </screen>
        </informalexample>

-      <para>In any case, whether the lock is broken or stolen, Harry
-        may be in for a surprise.  Harry's working copy still contains
-        the original lock token, but that lock no longer exists.  The
-        lock token is said to be <firstterm>defunct</firstterm>.  The
-        lock represented by the lock token has either been broken (no
-        longer in the repository) or stolen (replaced with a
-        different lock).  Either way, Harry can see this by asking
+      <para>
+        <indexterm>
+          <primary>locks</primary>
+          <secondary>defunct</secondary>
+        </indexterm>In any case, whether the lock is broken or stolen,
+        Harry may be in for a surprise.  Harry's working copy still
+        contains the original lock token, but that lock no longer
+        exists.  The lock token is said to
+        be <firstterm>defunct</firstterm>.  The lock represented by
+        the lock token has either been broken (no longer in the
+        repository) or stolen (replaced with a different lock).
+        Either way, Harry can see this by asking
          <command>svn status</command> to contact the
          repository:</para>

@@ -4378,7 +4591,18 @@
        uses your repository, every other user will need to perform the
        same checkout operations that you did.</para>

-    <para>Fortunately, Subversion provides support for
+    <para>
+      <indexterm>
+        <primary>externals definitions</primary>
+      </indexterm>
+      <indexterm>
+        <primary>externals</primary>
+        <see>externals definitions</see>
+      </indexterm>
+      <indexterm>
+        <primary>properties</primary>
+        <secondary>svn:externals</secondary>
+      </indexterm>Fortunately, Subversion provides support for
        <firstterm>externals definitions</firstterm>.  An externals
        definition is a mapping of a local directory to the
        URL—and ideally a particular revision—of a versioned
@@ -4678,7 +4902,11 @@
  </screen>
      </informalexample>

-    <para>Subversion 1.6 also introduced support for external
+    <para>
+      <indexterm>
+        <primary>externals</primary>
+        <secondary>file</secondary>
+      </indexterm>Subversion 1.6 also introduced support for external
        definitions for files.  <firstterm>File externals</firstterm>
        are configured just like externals for directories and appear as
        a versioned file in the working copy.</para>
@@ -4842,7 +5070,11 @@
          contents in the external content.</para>
      </warning>

-    <para>Besides the <command>svn checkout</command>, <command>svn
+    <para>
+      <indexterm>
+        <primary>working copies</primary>
+        <secondary>disjoint</secondary>
+      </indexterm>Besides the <command>svn checkout</command>, <command>svn
        update</command>, <command>svn switch</command>, and
        <command>svn export</command> commands which actually manage the
        <firstterm>disjoint</firstterm> (or disconnected) subdirectories
@@ -4888,7 +5120,10 @@
        degree, the details of the changes being made heavily influence
        the methodology used to distinguish them.</para>

-    <para>Subversion provides a <firstterm>changelists</firstterm>
+    <para>
+      <indexterm>
+        <primary>changelists</primary>
+      </indexterm>Subversion provides a <firstterm>changelists</firstterm>
        feature that adds yet another method to the mix.  Changelists
        are basically arbitrary labels (currently at most one per file)
        applied to working copy files for the express purpose of
@@ -4921,7 +5156,16 @@
      <sect2 id="svn.advanced.changelists.creating">
        <title>Creating and Modifying Changelists</title>

-      <para>You can create, modify, and delete changelists using the
+      <para>
+        <indexterm>
+          <primary>svn</primary>
+          <secondary>subcommands</secondary>
+          <tertiary>changelist</tertiary>
+        </indexterm>
+        <indexterm>
+          <primary>changelists</primary>
+          <secondary>creating</secondary>
+        </indexterm>You can create, modify, and delete changelists using  
the
          <command>svn changelist</command> command.  More accurately,
          you use this command to set or unset the changelist
          association of a particular working copy file.  A changelist
@@ -4995,10 +5239,19 @@
  </screen>
        </informalexample>

-      <para>Fortunately, Harry catches his mistake.  At this point, he
-        has two options.  He can remove the changelist association
-        from <filename>button.c</filename>, and then assign a
-        different changelist name:</para>
+      <para>
+        <indexterm>
+          <primary>svn</primary>
+          <secondary>subcommands</secondary>
+          <tertiary>changelist</tertiary>
+        </indexterm>
+        <indexterm>
+          <primary>changelists</primary>
+          <secondary>removing</secondary>
+        </indexterm>Fortunately, Harry catches his mistake.  At this
+        point, he has two options.  He can remove the changelist
+        association from <filename>button.c</filename>, and then
+        assign a different changelist name:</para>

        <informalexample>
          <screen>
@@ -5010,7 +5263,16 @@
  </screen>
        </informalexample>

-      <para>Or, he can skip the removal and just assign a new
+      <para>
+        <indexterm>
+          <primary>svn</primary>
+          <secondary>subcommands</secondary>
+          <tertiary>changelist</tertiary>
+        </indexterm>
+        <indexterm>
+          <primary>changelists</primary>
+          <secondary>reassigning</secondary>
+        </indexterm>Or, he can skip the removal and just assign a new
          changelist name.  In this case, Subversion will first warn
          Harry that <filename>button.c</filename> is being removed from
          the first changelist:</para>
@@ -5260,7 +5522,11 @@
            URL schemes and protocols the client knows how to use.</para>
        </tip>

-      <para>When the server process receives a client request, it
+      <para>
+        <indexterm>
+          <primary>authentication</primary>
+          <secondary>credentials</secondary>
+        </indexterm>When the server process receives a client request, it
          often demands that the client identify itself.  It issues
          an authentication challenge to the client, and the client
          responds by providing <firstterm>credentials</firstterm> back




More information about the svnbook-dev mailing list