[SvnBook] #61: [PATCH] Hanchrow review [:ch2]

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

#61: [PATCH] Hanchrow review [:ch2]
 Reporter:  cmpilato     |       Owner:  nobody       
     Type:  enhancement  |      Status:  new          
 Priority:  normal       |   Milestone:  1.5          
Component:  content      |     Version:  nightly/trunk
 Keywords:               |  
 From: Eric Hanchrow <offby1 at blarg.net>

 This is a bazillion different changes; I'm reading the book start to
 finish and whining^Wmaking constructive suggestions about anything and

 Index: tools/svnbook.el
 --- tools/svnbook.el    (revision 2735)
 +++ tools/svnbook.el    (working copy)
 @@ -42,7 +42,9 @@
          (replace-match ">" nil t))

 +(when (not (boundp 'sgml-catalog-files))
 +  (setq sgml-catalog-files '()))
 +(add-to-list 'sgml-catalog-files '("/usr/local/prod/sgml/dblite/catalog")
  (setq sgml-omittag-transparent t
        sgml-trace-entity-lookup nil
        sgml-live-element-indicator t
 @@ -52,7 +54,6 @@
        ;; NOTE: I removed the -u from sgml-validate-command to get rid of
 stupid errors in the DTDs. -Fitz
        sgml-set-face t
        sgml-mode-hook (quote (auto-fill-mode))
 -      sgml-catalog-files (append sgml-catalog-files
        sgml-auto-activate-dtd t)

 Index: en/HACKING
 --- en/HACKING  (revision 2735)
 +++ en/HACKING  (working copy)
 @@ -1,5 +1,5 @@
  This style guide is intended to be *an addition to* the O'Reilly and
 -Associates style guide at
 +Associates style guide at

 Index: en/book/appc-webdav.xml
 --- en/book/appc-webdav.xml     (revision 2735)
 +++ en/book/appc-webdav.xml     (working copy)
 @@ -238,7 +238,7 @@
      <para>The original WebDAV standard has been widely successful.
        Every modern computer operating system has a general WebDAV
        client built-in (details to follow), and a number of popular
 -      standalone applications are also able to speak WebDAV —
 +      standalone applications are also able to speak WebDAV—
        Microsoft Office, Dreamweaver, and Photoshop to name a few.  On
        the server end, the Apache webserver has been able to provide
        WebDAV services since 1998 and is considered the de-facto
 Index: en/book/ch00-preface.xml
 --- en/book/ch00-preface.xml    (revision 2735)
 +++ en/book/ch00-preface.xml    (working copy)
 @@ -37,6 +37,7 @@
      flexible.  And for the most part, almost all newly-started
      open-source projects now choose Subversion instead of CVS.</para>

 +  <!-- Just 1.4?  Not 1.5, 1.6, and so on? -->
    <para>This book is written to document the 1.4 series of the
      Subversion version control system.  We have made every attempt to
      be thorough in our coverage.  However, Subversion has a thriving
 @@ -57,11 +58,11 @@
        use Subversion to manage their data.  While Subversion runs on a
        number of different operating systems, its primary user
        interface is command-line based.  That command-line tool
 -      (<command>svn</command>) and auxiliary program are the focus of
 +      (<command>svn</command>), and some auxiliary programs, are the
 focus of
        this book.</para>

      <para>For consistency, the examples in this book assume the reader
 -      is using a Unix-like operating system and relatively comfortable
 +      is using a Unix-like operating system, and is relatively
        with Unix and command-line interfaces.  That said, the
        <command>svn</command> program also runs on non-Unix platforms
        like Microsoft Windows.  With a few minor exceptions, such as
 @@ -145,7 +146,7 @@
              learn how to do more advanced things with Subversion, such
              as how to use branches and perform merges (<xref
              linkend="svn.branchmerge"/>), how to use Subversion's
 -            property support ((<xref linkend="svn.advanced"/>), how to
 +            property support (<xref linkend="svn.advanced"/>), how to
              configure runtime options (<xref
              linkend="svn.customization"/>), and other things.  These
              chapters aren't critical at first, but be sure to read
 @@ -303,7 +304,7 @@
            <term><xref linkend="svn.serverconfig"/></term>
              <para>Explains how to configure your Subversion server and
 -              the three ways to access your repository:
 +              the ways to access your repository, including:
                <literal>HTTP</literal>, the <literal>svn</literal>
                protocol, and local disk access.  It also covers the
                of authentication, authorization and anonymous
 @@ -421,6 +422,7 @@
      <para>The online home of this book's development and most of the
        volunteer-driven translation efforts around it is <ulink
        url="http://svnbook.red-bean.com"/>.  There, you can find links
 +      <!-- what's the difference between a "snapshot" and a "tagged
 version"? -->
        to the latest snapshots and tagged versions of the book in
        various formats, as well as instructions for accessing the
        book's Subversion repository (where lives its DocBook XML source
 @@ -580,7 +582,11 @@

      <title>What is Subversion?</title>

 -    <para>Subversion is a free/open-source version control system.
 +    <!-- I'd like to set off the phrase "version control system"
 +    somehow, because the next sentence talks _only_ about it, and not
 +    about the phrase "free/open-source".  But I'm not sure how to do
 +    that while conforming to this document's standard style. -->
 +    <para>Subversion is a free/open-source <firstterm>version control
        That is, Subversion manages files and directories, and the
        changes made to them, over time.  This allows you to recover
        older versions of your data, or examine the history of how your
 @@ -591,6 +597,7 @@
        be used by people on different computers.  At some level, the
        ability for various people to modify and manage the same set of
        data from their respective locations fosters collaboration.
 +      <!-- it's not clear to me what "conduit" we're referring to -->
        Progress can occur more quickly without a single conduit through
        which all modifications must occur.  And because the work is
        versioned, you need not fear that quality is the trade-off for
 Index: en/book/ch03-advanced-topics.xml
 --- en/book/ch03-advanced-topics.xml    (revision 2735)
 +++ en/book/ch03-advanced-topics.xml    (working copy)
 @@ -926,7 +926,7 @@
            it, this RFC describes the concept of media types and
            subtypes, and recommends a syntax for the representation of
            those types.  Today, MIME media types—or, MIME
 -          types— are used almost universally across e-mail
 +          types—are used almost universally across e-mail
            applications, Web servers, and other software as the de
            facto mechanism for clearing up the file content
 @@ -2593,7 +2593,7 @@
        to give the project a name.
          <para><quote>You're not supposed to name it.  Once you name it,
 -          you start getting attached to it.</quote> — Mike
 +          you start getting attached to it.</quote>—Mike
        Let's say you called your software Frabnaggilywort.  At this
 Index: en/book/ch05-repository-admin.xml
 --- en/book/ch05-repository-admin.xml   (revision 2735)
 +++ en/book/ch05-repository-admin.xml   (working copy)
 @@ -419,7 +419,7 @@
              however, assumes that the reader is thinking
 -        —a versioned filesystem implementation that uses the
 +       —a versioned filesystem implementation that uses the
          native OS filesystem to store data.</para>

        <para><xref linkend="svn.reposadmin.basics.backends.tbl-1" />
 Index: en/book/ch01-fundamental-concepts.xml
 --- en/book/ch01-fundamental-concepts.xml       (revision 2735)
 +++ en/book/ch01-fundamental-concepts.xml       (working copy)
 @@ -1,3 +1,13 @@
 +<!-- note that when I say "on IRC", I mean "on the #svn channel on
 +irc.freenode.org" -->
 +<!-- a general note: we're using the word "merge" in two somewhat
 +  different ways.  One way describes what happens when we "svn up" a
 +  file that has uncommitted changes; the other way of course describes
 +  what happens when we do "svn merge".  I fear this may confuse
 +  people.  Naturally I can't think of how to alleviate that confusion
 +  :-| -->
  <chapter id="svn.basic">
    <title>Fundamental Concepts</title>

 @@ -54,6 +64,7 @@
        was the last person to change this file, and what changes did
        he make?</quote> These are the sorts of questions that are at
        the heart of any <firstterm>version control system</firstterm>:
 +      <!-- isn't "record and track" redundant?  :-)  -->
        systems that are designed to record and track changes to data
        over time.
 @@ -187,6 +198,7 @@
      <sect2 id="svn.basic.vsn-models.copy-merge">
        <title>The Copy-Modify-Merge Solution</title>

 +      <!-- I'd say "most other version control systems" -->
        <para>Subversion, CVS, and a number of other version control
          systems use a <firstterm>copy-modify-merge</firstterm> model as
          alternative to locking.  In this model, each user's client
 @@ -207,6 +219,10 @@
          later, the repository informs him that his file A is
          <firstterm>out-of-date</firstterm>.  In other words, that file
          A in the repository has somehow changed since he last copied
 +        <!-- I fear that using the term "merge" here might lead
 +        newbies to think that they should type "svn merge" in this
 +        situation, which of course isn't the case: they instead need
 +        to type "svn up". -->
          it.  So Harry asks his client to <firstterm>merge</firstterm>
          any new changes from the repository into his working copy of
          file A.  Chances are that Sally's changes don't overlap with
 @@ -252,6 +268,9 @@
          communication.  When users communicate poorly, both syntactic
          and semantic conflicts increase.  No system can force users to
          communicate perfectly, and no system can detect semantic
 +        <!-- one isn't lulled "into a promise"; I'd say "lulled into a
 +        false sense of security that ..." or "lulled into thinking
 +        that ..." -->
          conflicts.  So there's no point in being lulled into a false
          promise that a locking system will somehow prevent conflicts;
          in practice, locking seems to inhibit productivity more than
 @@ -277,7 +296,7 @@

          <para>While Subversion is still primarily a copy-modify-merge
            system, it still recognizes the need to lock an occasional
 -          file ands provide mechanisms for this.  This feature is
 +          file, and thus provide mechanisms for this.  This feature is
            discussed later in this book, in
            <xref linkend="svn.advanced.locking"/>.</para>

 @@ -332,6 +351,7 @@
          Windows platforms will need to use an unofficially
          <quote>standard</quote> syntax for accessing repositories
          that are on the same machine, but on a different drive than
 +        <!-- file://localhost/X:/path/to/repos works too -->
          the client's current working drive.  Either of the two
          following URL path syntaxes will work where
          <literal>X</literal> is the drive on which the repository
 @@ -362,7 +382,11 @@

 -      <para>Finally, it should be noted that the Subversion client will
 +      <!-- isn't this behavior dependent upon the various LC_
 +      environment variables?  If so, might it be useful to include a
 +      footnote that says so, and points to the section that explains
 +      in detail? -->
 +      <para>Finally, the Subversion client will
          automatically encode URLs as necessary, just like a web browser
          does.  For example, if a URL contains a space or upper-ASCII
 @@ -457,6 +481,8 @@
  Makefile  integer.c  button.c  .svn/

 +      <!-- maybe instead, say "The letter A's in the left margin", and
 +      perhaps emphasize the letter "a" in the word "adding" -->
        <para>The list of letter A's indicates that Subversion is adding
          a number of items to your working copy.  You now have a
          personal copy of the repository's <filename>/calc</filename>
 @@ -465,6 +491,9 @@
          extra information needed by Subversion, as mentioned

 +      <!-- this sidebar seems a tad out of place.  Might not a
 +      better place for it be the end of svn.basic.in-action, where we
 +      already talked about URLs in some detail? -->
        <sidebar id="svn.basic.in-action.wc.sb-1">
          <title>Repository URLs</title>

 @@ -488,6 +517,8 @@
 +                <!-- should this be 'file://' instead - i.e., two
 +                slashes instead of three?  Nit-picky, I admit. -->
                  <entry>direct repository access (on local disk)</entry>
 @@ -508,6 +539,13 @@
 +                <!-- svn+ssh:// isn't as similar to svn:// as https://
 +                is to http://.  People on IRC are occasionally
 +                suprised to learn that svn+ssh does _not_ contact a
 +                daemon, but instead starts up its own "one-shot"
 +                svnserve process.  This statement might further that
 +                confusion.  Naturally I can't think of any way to
 +                improve it that is short enough :-| -->
                  <entry>same as <literal>svn://</literal>, but through
                    an SSH tunnel.</entry>
 @@ -525,7 +563,7 @@

        <para>Suppose you make changes to <filename>button.c</filename>.
          Since the <filename>.svn</filename> directory remembers the
 -        file's modification date and original contents, Subversion can
 +        file's original modification date and contents, Subversion can
          tell that you've changed the file.  However, Subversion does
          not make your changes public until you explicitly tell it to.
          The act of publishing your changes is more commonly known as
 @@ -556,6 +594,9 @@
          unchanged; Subversion only modifies working copies at the
          user's request.</para>

 +      <!-- if, above, you still refer to this process as "merging",
 +      then it would be good to say something like "this is the
 +      'merging' step we referred to above" -->
        <para>To bring her project up to date, Sally can ask
          Subversion to <firstterm>update</firstterm> her working copy,
          by using the Subversion <command>update</command> command.
 @@ -582,7 +623,10 @@
          in the <filename>.svn</filename> directory, and further
          information in the repository, to decide which files need to
          be brought up to date.</para>
 +      <!-- this probably isn't the place, but you might want to
 +        mention that this process doesn't send any more information
 +        over the network than needed.  People on IRC occasionally ask
 +        about this.  -->

 @@ -593,9 +637,11 @@
        <para>An <command>svn commit</command> operation publishes
          changes to any number of files and directories as a single
          atomic transaction.  In your working copy, you can change
 -        files' contents, create, delete, rename and copy files and
 -        directories, and then commit a complete set of changes as an
 +        files' contents; create, delete, rename and copy files and
 +        directories; and then commit a complete set of changes as an
          atomic transaction.</para>
 +      <!-- might we mention properties here too?  They're another type
 +           of change that can be made. -->

        <para>By <quote>atomic transaction</quote>, we mean simply this:
          either all of the changes happen in the repository, or none of
 @@ -715,6 +761,10 @@

 +      <!-- It's not clear to me if subversion looks at any other
 +      information, in particular, the file's size or contents.  It
 +      might be worthwhile mentioning such other tests, if they
 +      exist.  -->
        <para>Given this information, by talking to the repository,
          Subversion can tell which of the following four states a
          working file is in:</para>
 @@ -774,6 +824,12 @@
                changes.  If Subversion can't complete the merge in a
                plausible way automatically, it leaves it to the user to
                resolve the conflict.</para>
 +            <!-- at some point it might be worth mentioning that if,
 +              by coincidence, the local changes match those on the
 +              server, not only will the merge succeed, but the file
 +              will suddenly appear to be not modified.  This is of
 +              course correct behavior, but I suspect it might surprise
 +              some people. -->
 @@ -892,7 +948,7 @@
            contained in a subdirectory, or perhaps you'd like to figure
            out when a bug first came into existence in a specific file.
            This is the <quote>time machine</quote> aspect of a version
 -          control system — the feature which allows you to move
 +          control system—the feature which allows you to move
            any portion of your working copy forward and backward in

 Index: en/book/ch06-server-configuration.xml
 --- en/book/ch06-server-configuration.xml       (revision 2735)
 +++ en/book/ch06-server-configuration.xml       (working copy)
 @@ -409,7 +409,7 @@
              <xref linkend="svn.serverconfig.multimethod"/>.)  Note
              that this is also one of the reasons we warn against
              accessing repositories via <literal>svn+ssh://</literal>
 -            URLs — from a security standpoint, it's effectively
 +            URLs—from a security standpoint, it's effectively
              the same as local users accessing
              via <literal>file://</literal>, and can entail all the
              same problems if the administrator isn't careful.</para>
 @@ -2088,7 +2088,7 @@
              the <quote>default</quote> MIME type,
              typically <literal>text/plain</literal>.  This can be
              frustrating, however, if a user wishes repository files to
 -            render as something more meaningful — for example,
 +            render as something more meaningful—for example,
              it might be nice to have a <filename>foo.html</filename> file
              in the repository actually render as HTML when
 @@ -2219,7 +2219,7 @@
            even the simplest Subversion client operation generates
            multiple network requests.  It's very difficult to look at
            the <filename>access_log</filename> and deduce what the
 -          client was doing — most operations look like a series
 +          client was doing—most operations look like a series
            of cryptic <literal>PROPPATCH</literal>,
            <literal>PUT</literal>, and <literal>REPORT</literal>
            requests.  To make things worse, many client operations send
 Index: en/book/ch04-branching-and-merging.xml
 --- en/book/ch04-branching-and-merging.xml      (revision 2735)
 +++ en/book/ch04-branching-and-merging.xml      (working copy)
 @@ -1038,7 +1038,7 @@
            file.  This can lead to problems, especially because the
            same thing happens with renamed files.  A lesser-known fact
            about Subversion is that it lacks <quote>true
 -          renames</quote> — the <command>svn move</command>
 +          renames</quote>—the <command>svn move</command>
            command is nothing more than an aggregation of <command>svn
            copy</command> and <command>svn delete</command>.</para>

 @@ -1064,7 +1064,7 @@
            operation has deleted the latest version
            of <filename>integer.c</filename> file (the one containing
            Sally's latest changes), and blindly added your
 -          new <filename>whole.c</filename> file — which is a
 +          new <filename>whole.c</filename> file—which is a
            duplicate of the <emphasis>older</emphasis> version
            of <filename>integer.c</filename>.  The net effect is that
            merging your <quote>rename</quote> to the branch has removed
 @@ -1401,8 +1401,8 @@
          particular revision tree, and the second coordinate is a path
          within that tree.  So every version of your file or directory
          can be defined by a specific coordinate pair.  (Remember the
 -        familiar <quote>peg revision</quote> syntax — foo.c at 224
 -        — mentioned back in
 +        familiar <quote>peg revision</quote> syntax—foo.c at 224
 +       —mentioned back in
          <xref linkend="svn.advanced.pegrevs"/>.) </para>

        <para>First, you might need to use <command>svn log</command> to
 Index: en/book/ch02-basic-usage.xml
 --- en/book/ch02-basic-usage.xml        (revision 2735)
 +++ en/book/ch02-basic-usage.xml        (working copy)
 @@ -98,6 +98,10 @@

 +      <!-- it might also be worth emphasizing - even though the example
 +      above clearly shows it - that the repo does *not* get a new
 +      directory named "mytree".  I occasionally find people on IRC are
 +      surprised by this.  -->
        <para>Note that after the import is finished, the original tree
          is <emphasis>not</emphasis> converted into a working copy.  To
          start working, you still need to <command>svn
 @@ -125,7 +129,7 @@

        <para>You'll learn more about tags and branches in <xref
 -      linkend="svn.branchmerge"/>.  For details and how to setup
 +      linkend="svn.branchmerge"/>.  For details, and how to set up
        multiple projects, see <xref
        linkend="svn.branchmerge.maint.layout"/> and <xref
        linkend="svn.reposadmin.projects.chooselayout"/> to read more
 @@ -147,8 +151,8 @@
        copy</quote> of it on your local machine.  This copy contains
        the <literal>HEAD</literal> (latest revision) of the Subversion
        repository that you specify on the command line:</para>
 +    <!-- well, unless you specify a "-r" option, of course. -->

  $ svn checkout http://svn.collab.net/repos/svn/trunk
  A    trunk/Makefile.in
 @@ -209,6 +213,9 @@
        repository by specifying the subdirectory in the checkout

 +    <!-- are you sure you want to introduce the "-r" option here,
 +    without describing it?  It might make a reader think that it's
 +    needed in order to check out a subdirectory. -->
  $ svn checkout -r 8810 \
 @@ -223,27 +230,27 @@

      <para>Since Subversion uses a <quote>copy-modify-merge</quote>
        model instead of <quote>lock-modify-unlock</quote> (see <xref
 -      linkend="svn.basic.vsn-models"/>), you're already able to start
 +      linkend="svn.basic.vsn-models"/>), you can start right in
        making changes to the files and directories in your working
        copy.  Your working copy is just like any other collection of
        files and directories on your system.  You can edit and change
        them, move them around, you can even delete the entire working
        copy and forget about it.</para>

 -      <note>
 +      <warning>

          <para>While your working copy is <quote>just like any other
            collection of files and directories on your system</quote>,
            you can edit files at will, but you must tell Subversion
 -          about <emphasis>everything else</emphasis>that you do.  For
 +          about <emphasis>everything else</emphasis> that you do.  For
            example, if you want to copy or move an item in a working
            copy, you should use <command>svn copy</command> or
            <command>svn move</command> instead of the copy and move
            commands provided by your operating system.  We'll talk more
            about them later in this chapter.</para>
 -      </note>
 +      </warning>

 -    <para>Unless you're ready to commit a new file or directory, or
 +    <para>Unless you're ready to commit the addition of a new file or
 directory, or
        changes to existing ones, there's no need to further notify the
        Subversion server that you've done anything.</para>

 @@ -257,9 +264,12 @@
          an important directory.  Whatever you do, don't delete or
          change anything in the administrative area!  Subversion
          depends on it to manage your working copy.</para>
 +      <!-- that warning is useful on its own, but how about telling me
 +        how to recover if I _have_ deleted that directory?  Believe
 +        me, it happens.  -->

 +    <!-- as above, I think the "-r" option here is a distraction. -->
      <para>While you can certainly check out a working copy with the
        URL of the repository as the only argument, you can also specify
        a directory after your repository URL.  This places your working
 @@ -288,6 +298,7 @@

        <para>When you perform a Subversion operation that requires you
          to authenticate, by default Subversion caches your
 +        <!-- perhaps say "for convenience - so that you don't have to
 enter them again" -->
          authentication credentials on disk.  If you're concerned about
          caching your Subversion passwords,<footnote><para>Of course,
          you're not terribly worried—first because you know that
 @@ -438,7 +449,7 @@
          to each item to let you know what actions Subversion performed
          to bring your working copy up-to-date.  To find out what these
          letters mean, see <xref linkend
 -        ="svn.ref.svn.c.update"/></para>
 +        ="svn.ref.svn.c.update"/>.</para>


 @@ -467,8 +478,8 @@
          text files—and just as efficiently too.  For tree
          changes, you can ask Subversion to <quote>mark</quote> files
          and directories for scheduled removal, addition, copying, or
 -        moving.  While these changes may take place immediately in
 -        your working copy, no additions or removals will happen in the
 +        moving.  These changes take place immediately in
 +        your working copy, but no additions or removals happen in the
          repository until you commit them.</para>

        <para>Here is an overview of the five Subversion subcommands
 @@ -487,9 +498,9 @@

          <para>When a symlink is committed into a Subversion
            repository, Subversion remembers that the file was in fact a
 -          symlink, as well as to what object the symlink
 +          symlink, as well as the object to which the symlink
            <quote>points</quote>.  When that symlink is checked out to
 -          another working copy on a supporting system, Subversion
 +          another working copy on a non-Windows system, Subversion
            reconstructs a real filesystem-level symbolic link from the
            versioned symlink.  But that doesn't in any way limit the
            usability of working copies on systems such as Windows which
 @@ -526,16 +537,17 @@
                repository.  If <filename>foo</filename> is a file or
                link, it is immediately deleted from your working copy.
                If <filename>foo</filename> is a directory, it is not
 -              deleted, but Subversion schedules it for deletion.  When
 +              deleted, but versioned files under it are, and
 +              Subversion schedules it, and versioned directories under
 it, for deletion.  When
                you commit your changes, <filename>foo</filename> will
 -              be removed from your working copy and the repository.
 +              be entirely removed from your working copy and the
                <footnote><para>Of course, nothing is ever totally
                deleted from the repository—just from the
                <literal>HEAD</literal> of the repository.  You can get
                back anything you delete by checking out (or updating
 -              your working copy) a revision earlier than the one in
 +              your working copy to) a revision earlier than the one in
                which you deleted it. Also see <xref

 @@ -623,11 +635,11 @@
          <title>Look Ma! No Network!</title>

 -        <para>The commands (<command>svn status</command>,
 +        <para>The commands <command>svn status</command>,
            <command>svn diff</command>, and <command>svn
 -          revert</command>) can be used without any network access
 -          (assuming, of course, that your repository is across the
 -          network and not local).  This makes it easy to manage your
 +          revert</command> can be used without any network access
 +          even if your repository <emphasis>is</emphasis> across the
 +          network.  This makes it easy to manage your
            changes-in-progress when you are somewhere without a network
            connection, such as travelling on an airplane, riding a
            commuter train or hacking on the beach.<footnote><para>And
 @@ -654,6 +666,7 @@
        <para>Subversion has been optimized to help you with this task,
          and is able to do many things without communicating with the
          repository.  In particular, your working copy contains a
 +        <!-- "secret"?  nah.  "hidden", maybe. -->
          secret cached <quote>pristine</quote> copy of each version
          controlled file within the <filename>.svn</filename> area.
          Because of this, Subversion can quickly show you how your
 @@ -689,14 +702,15 @@


 -        <para>If you run <command>svn status</command> at the top of
 -          your working copy with no arguments, it will detect all file
 +        <para>If you run <command>svn status</command>, with no
 arguments, at the top of
 +          your working copy, it will detect all file
            and tree changes you've made.  Below are a few examples of
            the most common status codes that <command>svn
            status</command> can return.  (Note that the text following
            <literal>#</literal> is not
            actually printed by <command>svn status</command>.)</para>

 +        <!-- conflicts can come from merges, too, of course. -->
  A       stuff/loot/bloo.h   # file is scheduled for addition
  C       stuff/loot/lump.c   # file has textual conflicts from an update
 @@ -705,9 +719,9 @@

          <para>In this output format <command>svn status</command>
 -          prints six columns of characters, followed by several
 -          whitespace characters, followed by a file or directory name.
 -          The first column tells the status of a file or directory
 +          prints six characters -- letters or whitespace -- followed by
 +          more whitespace characters, followed by a file or directory
 +          The letter tells the status of a file or directory
            and/or its contents.  The codes we listed are:</para>

 @@ -726,6 +740,7 @@
                <para>The file <filename>item</filename> is in a state
                  of conflict.  That is, changes received from the
 +                <!-- again, it could conflict due to a merge, too -->
                  server during an update overlap with local changes
                  that you have in your working copy.  You must resolve
                  this conflict before committing your changes to the
 @@ -761,6 +776,10 @@
  D      stuff/fish.c

 +        <!-- Ooh, this is subtle.  -v apparently changes _both_ the
 +        files that "status" reports on (at least, if you haven't
 +        specified a file name), _and_ the information that appears for
 +        each file.  Is it worth mentioning this here?  -->
          <para><command>svn status</command> also has a
            <option>--verbose (-v)</option> switch, which will show you
            the status of <emphasis>every</emphasis> item in your
 @@ -780,16 +799,18 @@

          <para>This is the <quote>long form</quote> output of
 -          <command>svn status</command>.  The first column remains the
 -          same, but the second column shows the working-revision of
 +          <command>svn status</command>.  The letters in the first column
 mean the
 +          <!-- what does "working-revision" mean?  If you don't want
 +          to define it here, then we should probably wrap it in
 <firstterm/>. -->
 +          same as in the above, but the second column shows the working-
 revision of
            the item.  The third and fourth columns show the revision in
 -          which the item last changed, and who changed it (these
 -          columns are not to be confused with the columns of
 -          characters that we just discussed).</para>
 +          which the item last changed, and who changed it.</para>

          <para>None of the above invocations to <command>svn
 -          status</command> contact the repository, they work only
 -          locally by comparing the metadata in the
 +          status</command> contact the repository—instead, they
 +          compare the metadata in the
            <filename>.svn</filename> directory with the working copy.
            Finally, there is the <option>--show-updates (-u)</option>
            option, which contacts the repository and adds information
 @@ -813,8 +834,10 @@
            server changes on <filename>README</filename> before you
            commit, or the repository will reject your commit for being
            out-of-date.  (More on this subject later.)</para>
 +        <!-- how about a link to the section where this is discussed,
 +          instead of simply saying "later"? -->

 -          <para><command>svn status</command> displays much more
 +          <para><command>svn status</command> can display much more
              information about the files and directories in your
              working copy than we've shown here—for an exhaustive
              description of svn status and its output, see <xref
 @@ -830,8 +853,8 @@
            <command>svn diff</command> command.  You can find out
            <emphasis>exactly</emphasis> how you've modified things by
            running <command>svn diff</command> with no arguments, which
 -          prints out file changes in unified diff
 -          format:</para>
 +          prints out file changes in <firstterm>unified diff
 +          format</firstterm>:</para>

  $ svn diff
 @@ -881,11 +904,19 @@
            addition are displayed as all added-text, and files
            scheduled for deletion are displayed as all deleted
 +        <!-- shouldn't we then ensure that we have a scheduled-add file,
 +          and a scheduled-delete file, in the above example?  If we
 +          already have one, and I'm overlooking it, then say something
 +          like "... files scheduled for deletion, like stuff/fish.c,
 +          are displayed ..."-->

 -        <para>Output is displayed in <firstterm>unified diff
 -          format</firstterm>.  That is, removed lines are prefaced
 -          with a <literal>-</literal> and added lines are prefaced
 -          with a <literal>+</literal>.  <command>svn diff</command>
 +        <para>Output is displayed in unified diff
 +          format.  That is, removed lines are prefaced
 +          <!-- I deleted the word "a" in two places because I fear
 +          that it will be confused with the "A" output by "svn st",
 +          which we just described. -->
 +          with <literal>-</literal> and added lines are prefaced
 +          with <literal>+</literal>.  <command>svn diff</command>
            also prints filename and offset information useful to the
            <command>patch</command> program, so you can generate
            <quote>patches</quote> by redirecting the diff output to a
 @@ -955,7 +986,7 @@
  ?      foo

 -      <note>
 +      <warning>
          <para><command>svn revert</command>
            <replaceable>ITEM</replaceable> has exactly the same
            effect as deleting <replaceable>ITEM</replaceable> from
 @@ -965,7 +996,7 @@
            has one very noticeable difference—it doesn't have
            to communicate with the repository to restore your
 -      </note>
 +      </warning>

        <para>Or perhaps you mistakenly removed a file from version
 @@ -1015,7 +1046,7 @@

        <para>But the <computeroutput>C</computeroutput> stands for
 -        conflict.  This means that the changes from the server overlapped
 +        <computeroutput>c</computeroutput>onflict.  This means that the
 changes from the server overlapped
          with your own, and now you have to manually choose between

 @@ -1359,7 +1390,7 @@
            decide that you want to cancel your commit, you can just
            quit your editor without saving changes.  If you've already
            saved your commit message, simply delete the text, save
 -          again, then quit.</para>
 +          again, then abort.</para>

  $ svn commit
 @@ -1379,6 +1410,17 @@
          that, the entire commit will fail with a message informing you
          that one or more of your files is out-of-date:</para>

 +      <!-- frustratingly (and surprisingly), the "out of date" message
 +      depends on the access method.  The one in the example below is
 +      for http:// access, but file:// access yields this instead:
 +        ../svn-live/subversion/libsvn_client/commit.c:867:
 +        svn: Commit failed (details follow):
 +        ../svn-live/subversion/libsvn_repos/commit.c:127:
 +        svn: Out of date: 'yow' in transaction '2-1'
 +      So we should probably note that the text of the message might
 +      vary somewhat :-| -->
  $ svn commit -m "Add another rule"
  Sending        rules.txt
 @@ -1396,7 +1438,7 @@
          to manage your repository and working copy, but most of your
          day-to-day use of Subversion will involve only the commands
          that we've discussed so far in this chapter.  We will,
 -        however, cover a few more commands that you'll use just fairly
 +        however, cover a few more commands that you'll use fairly

 @@ -1443,8 +1485,8 @@
            <term><command>svn cat</command></term>
 -            <para>This is used to retrieve any file as it existed in a
 -              particular revision number and display it on your
 +            <para>Retrieves a file as it existed in a
 +              particular revision number, and displays it on your
 @@ -1591,15 +1633,15 @@

 -          <para>Examine local changes</para>
 +          <para>Examining local changes</para>

 -          <para>Compare your working copy to the repository</para>
 +          <para>Comparing your working copy to the repository</para>

 -          <para>Compare repository to repository</para>
 +          <para>Comparing repository to repository</para>

 @@ -1640,6 +1682,12 @@
            working copy is compared to the specified revision in the

 +        <!-- might this example be a tad more illuminating if we were
 +        to pass some revision _other_ than 3?  So that it yields
 +        different output than the above example?  If not, why not
 +        mumble something about "note how the output is the same as
 +        above, since the revision we specified is the same as that
 +        chosen by default in the above"-->
  $ svn diff -r 3 rules.txt
  Index: rules.txt
 @@ -1700,13 +1748,9 @@

 -        <para>Not only can you use <command>svn diff</command> to
 -          compare files in your working copy to the repository, but if
 -          you supply a URL argument, you can examine the differences
 -          between items in the repository without even having a
 -          working copy.  This is especially useful if you wish to
 -          inspect changes in a file when you don't have a working copy
 -          on your local machine:</para>
 +        <para>Lastly, you can compare repository revisions even when
 +          you don't have a working copy on your local machine, just by
 +          including the appropriate URL on the command line:</para>

  $ svn diff -c 5 http://svn.example.com/repos/example/trunk/text/rules.txt
 @@ -1813,7 +1857,7 @@

 -      <warning>
 +      <tip>
          <para>Many Subversion newcomers attempt to use the above
            <command>svn update</command> example to <quote>undo</quote>
            committed changes, but this won't work as you can't commit
 @@ -1821,12 +1865,12 @@
            the changed files have newer revisions.  See <xref
            linkend="svn.branchmerge.commonuses.resurrect"/> for a
            description of how to <quote>undo</quote> a commit.</para>
 -          </warning>
 +          </tip>

        <para>Lastly, if you're building a release and wish to bundle up
 -        your files from Subversion but don't want those pesky .svn
 -        directories in the way, then you can use svn export to create
 -        a local copy of all or part of your repository sans .svn
 +        your files from Subversion but don't want those pesky
 +        directories in the way, then you can use <command>svn
 export</command> to create
 +        a local copy of all or part of your repository sans
          directories.  As with <command>svn update</command> and
          <command>svn checkout</command>, you can also pass the
          <option>--revision</option> switch to <command>svn
 @@ -1849,7 +1893,7 @@
    <!-- =================================================================
    <!-- =================================================================
    <sect1 id="svn.tour.cleanup">
 -    <title>Sometimes You Just Need to Cleanup</title>
 +    <title>Sometimes You Just Need to Clean Up</title>

      <para>When Subversion modifies your working copy (or any
        information within <filename>.svn</filename>), it tries to do
 @@ -1857,7 +1901,7 @@
        Subversion writes its intentions to a log file.  Next it
        executes the commands in the log file to apply the requested
        change, holding a lock on the relevant part of the working
 -      copy while it works — to prevent other Subversion clients
 +      copy while it works—to prevent other Subversion clients
        from accessing the working copy in mid-change.  Finally,
        Subversion removes the log file.  Architecturally, this is
        similar to a journaled filesystem.  If a Subversion operation

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

More information about the svnbook-dev mailing list