[svnbook commit] r1307 - in trunk/src/nb: . book

sunny256 svnbook-dev at red-bean.com
Tue May 17 22:06:23 CDT 2005


Author: sunny256
Date: Tue May 17 22:06:21 2005
New Revision: 1307

Removed:
   trunk/src/nb/book/colo.xml
Modified:
   trunk/src/nb/LAST_UPDATED
   trunk/src/nb/TRANSLATION-STATUS
   trunk/src/nb/book/book.xml
   trunk/src/nb/book/ch00.xml
   trunk/src/nb/book/ch03.xml
   trunk/src/nb/book/ch06.xml
   trunk/src/nb/book/ch07.xml
   trunk/src/nb/book/ch09.xml
   trunk/src/nb/book/styles.css
Log:
Sync the Norwegian svnbook with the English version, r1268:1306.

* src/nb/LAST_UPDATED
  Updated by make sync as usual.

* src/nb/TRANSLATION-STATUS
  Removed the files from the list which was removed by cmpilato in 
  r1304. And colo.xml .

* src/nb/book/book.xml
  Merged and updated r1297, colo.xml is gone.

* src/nb/book/ch00.xml
  Merged and updated r1289.

* src/nb/book/ch03.xml
  Merged and updated r1287, r1288, r1295.

* src/nb/book/ch06.xml
  Merged r1277, r1278, r1302.

* src/nb/book/ch07.xml
  Merged r1281, r1283, r1284, r1285.

* src/nb/book/ch09.xml
  Merged r1291, r1292, r1299, r1305.

* src/nb/book/colo.xml
  Removed in r1297 and is history here too.

* src/nb/book/styles.css
  Merged r1303.


Modified: trunk/src/nb/LAST_UPDATED
==============================================================================
--- trunk/src/nb/LAST_UPDATED	(original)
+++ trunk/src/nb/LAST_UPDATED	Tue May 17 22:06:21 2005
@@ -1 +1 @@
-1268
+1306

Modified: trunk/src/nb/TRANSLATION-STATUS
==============================================================================
--- trunk/src/nb/TRANSLATION-STATUS	(original)
+++ trunk/src/nb/TRANSLATION-STATUS	Tue May 17 22:06:21 2005
@@ -43,8 +43,6 @@
 
     2.1.4. Untranslated
 
-      README
-      book-dist.py
       book/appb.xml
       book/appc.xml
       book/appd.xml
@@ -52,7 +50,6 @@
       book/ch07.xml
       book/ch08.xml
       book/ch09.xml
-      book/colo.xml
       book/copyright.xml
       book/images/VersioningModels.ppt
       book/images/branches.ppt
@@ -62,14 +59,7 @@
 
   2.2. Files not part of the translation at the moment
 
-    2.2.1. Probably not necessary to translate
-
-      HACKING
-      REVIEW
-      TODO
-      outline.txt
-
-    2.2.2. Contains no i18n information
+    2.2.1. Contains no i18n information
 
       book/images/DirectoryModels.ppt
       book/images/ch02dia6.png

Modified: trunk/src/nb/book/book.xml
==============================================================================
--- trunk/src/nb/book/book.xml	(original)
+++ trunk/src/nb/book/book.xml	Tue May 17 22:06:21 2005
@@ -20,7 +20,6 @@
 <!ENTITY appc     SYSTEM "appc.xml">
 <!ENTITY appd     SYSTEM "appd.xml">
 <!ENTITY license  SYSTEM "copyright.xml">
-<!ENTITY colo     SYSTEM "colo.xml">
 ]>
 @ENGLISH }}} -->
 <!DOCTYPE book SYSTEM "../../tools/dtd/dblite.dtd"
@@ -43,7 +42,6 @@
 <!ENTITY appc     SYSTEM "appc.xml">
 <!ENTITY appd     SYSTEM "appd.xml">
 <!ENTITY license  SYSTEM "copyright.xml">
-<!ENTITY colo     SYSTEM "colo.xml">
 ]>
 
 <!-- @ENGLISH {{{
@@ -153,7 +151,6 @@
   &appc;
   &appd;
   &license;
-  &colo;
 
 </book>
 <!-- vim: set ft=svnbook : -->

Modified: trunk/src/nb/book/ch00.xml
==============================================================================
--- trunk/src/nb/book/ch00.xml	(original)
+++ trunk/src/nb/book/ch00.xml	Tue May 17 22:06:21 2005
@@ -750,10 +750,10 @@
       <listitem>
         <!-- @ENGLISH {{{
         <para>You will always find the latest version of this book in
-          Subversion's own source tree.</para>
+          the book's own Subversion repository.</para>
         @ENGLISH }}} -->
         <para>Du vil alltid finne den seneste versjonen av denne boken i 
-          Subversions eget kildekodetre.</para>
+          bokens eget Subversiondepot.</para>
       </listitem>
 
       <listitem>

Modified: trunk/src/nb/book/ch03.xml
==============================================================================
--- trunk/src/nb/book/ch03.xml	(original)
+++ trunk/src/nb/book/ch03.xml	Tue May 17 22:06:21 2005
@@ -869,12 +869,12 @@
 
       <listitem>
         <!-- @ENGLISH {{{
-        <para>Merge others' changes</para>
+        <para>Merge others' changes into your working copy</para>
         @ENGLISH }}} -->
-        <para>Flett inn andres forandringer</para>
+        <para>Flett andres forandringer inn i arbeidskopien din</para>
         <itemizedlist>
           <listitem>
-            <para><command>svn merge</command></para>
+            <para><command>svn update</command></para>
           </listitem>
           <listitem>
             <para><command>svn resolved</command></para>
@@ -1160,6 +1160,28 @@
         som du vil bruke oftest for å gjøre forandringer i trestrukturen 
         (vi vil dekke <command>svn import</command> og <command>svn 
         mkdir</command> senere).</para>
+
+      <!-- @ENGLISH {{{
+      <warning>
+        <para>While you can edit your files with whatever tool you
+          like, you shouldn't change the structure of your working
+          copy without letting Subversion know what you're doing.  Use
+          the <command>svn copy</command>, <command>svn
+          delete</command>, and <command>svn move</command> commands
+          to change the structure of your working copy, and use the
+          <command>svn add</command> command to place new files and
+          directories under version control.</para> </warning>
+      @ENGLISH }}} -->
+      <warning>
+        <para>Selv om du kan redigere filene dine med hvilket verktøy du 
+          vil, bør du ikke forandre strukturen i arbeidskopien uten å la 
+          Subversion vite hva du gjør.
+          Bruk kommandoene <command>svn copy</command>, <command>svn 
+          delete</command> og <command>svn move</command> for å forandre 
+          strukturen på arbeidskopien, og bruk <command>svn 
+          add</command>-kommandoen for å legge inn nye filer og 
+          kataloger under versjonskontroll.</para>
+      </warning>
       
       <variablelist>
         
@@ -1782,14 +1804,14 @@
         <!-- @ENGLISH {{{
         <para>The second column tells the status of a file or
           directory's properties (see <xref
-          linkend="svn-ch-7-sect-2"></xref> for more information on
+          linkend="svn-ch-7-sect-2"/> for more information on
           properties).  If an <computeroutput>M</computeroutput>
           appears in the second column, then the properties have been
           modified, otherwise a whitespace will be printed.</para>
         @ENGLISH }}} -->
         <para>Den andre kolonnen forteller statusen på egenskapene til 
           en fil eller katalog (se <xref 
-          linkend="svn-ch-7-sect-2"></xref> for mer informasjon om 
+          linkend="svn-ch-7-sect-2"/> for mer informasjon om 
           egenskaper).
           Hvis en <computeroutput>M</computeroutput> viser seg i den 
           andre kolonnen, er egenskapene blitt modifisert, ellers vil et 

Modified: trunk/src/nb/book/ch06.xml
==============================================================================
--- trunk/src/nb/book/ch06.xml	(original)
+++ trunk/src/nb/book/ch06.xml	Tue May 17 22:06:21 2005
@@ -577,7 +577,8 @@
         externally authenticated via a tunnel agent, such as
         <command>SSH</command>.  In that case, the server simply
         examines the user it's running as, and uses it as the
-        authenticated username.</para>
+        authenticated username.  For more on this, see <xref
+        linkend="svn-ch-6-sect-3.4"/>.</para>
 
       <para>As you've already guessed, a repository's
         <filename>svnserve.conf</filename> file is the central
@@ -731,20 +732,45 @@
 …
 </screen>
 
-      <para>What's happening here is that the Subversion client is
-        invoking a local <command>ssh</command> process, connecting to
-        <literal>host.example.com</literal>, authenticating as the user
-        <literal>harry</literal>, then spawning a private
-        <command>svnserve</command> process on the remote machine,
+      <para>In this example, the Subversion client is invoking a local
+        <command>ssh</command> process, connecting to
+        <literal>host.example.com</literal>, authenticating as the
+        user <literal>harry</literal>, then spawning a private
+        <command>svnserve</command> process on the remote machine
         running as the user <literal>harry</literal>.  The
         <command>svnserve</command> command is being invoked in tunnel
         mode (<option>-t</option>) and its network protocol is being
         <quote>tunneled</quote> over the encrypted connection by
         <command>ssh</command>, the tunnel-agent.
-        <command>svnserve</command> is aware that it's running as the user
-        <literal>harry</literal>, and if the client performs a commit,
-        the authenticated username will be attributed as the author of
-        the new revision.</para>
+        <command>svnserve</command> is aware that it's running as the
+        user <literal>harry</literal>, and if the client performs a
+        commit, the authenticated username will be attributed as the
+        author of the new revision.</para>
+
+      <para>The important thing to understand here is that the
+        Subversion client is <emphasis>not</emphasis> connecting to a
+        running <command>svnserve</command> daemon.  This method of
+        access doesn't require a daemon, nor does it notice one if
+        present.  It relies wholly on the ability of
+        <command>ssh</command> to spawn a temporary
+        <command>svnserve</command> process, which then terminates
+        when the network connection is closed.</para>
+
+      <para>When using <literal>svn+ssh://</literal> URLs to access a
+        repository, remember that it's the <command>ssh</command>
+        program prompting for authentication, and
+        <emphasis>not</emphasis> the <command>svn</command> client
+        program.  That means there's no automatic password caching
+        going on (see <xref linkend="svn-ch-6-sect-2.2"/>).  The
+        Subversion client often makes multiple connections to the
+        repository, though users don't normally notice this due to the
+        password caching feature.  When using
+        <literal>svn+ssh://</literal> URLs, however, users may be
+        annoyed by <command>ssh</command> repeatedly asking for a
+        password for every outbound connection.  The solution is to
+        use a separate SSH password-caching tool like
+        <command>ssh-agent</command> on a Unix-like system, or
+        <command>pageant</command> on Windows.</para>
 
       <para>When running over a tunnel, authorization is primarily
         controlled by operating system permissions to the repository's
@@ -806,27 +832,139 @@
         a convenient way to override the default SSH tunnel agent.
         But if you need to have several different overrides for
         different servers, each perhaps contacting a different port or
-        passing a different set of options, you can use the mechanism
-        demonstrated in this example.  Now if we were to set the
-        <literal>JOESSH</literal> environment variable, its value
+        passing a different set of options to SSH, you can use the
+        mechanism demonstrated in this example.  Now if we were to set
+        the <literal>JOESSH</literal> environment variable, its value
         would override the entire value of the tunnel
         variable—<command>$JOESSH</command> would be executed
-        instead of <command>/opt/alternate/ssh -p 29934</command>.</para>
-
-      <para>A final note: when using <literal>svn+ssh://</literal>
-        URLs to access a repository, remember that it's the
-        <command>ssh</command> program prompting you for
-        authentication, and <emphasis>not</emphasis> the
-        <command>svn</command> program.  That means there's no
-        automatic password caching going on (see <xref
-        linkend="svn-ch-6-sect-2.2"/>).  If you want to prevent
-        <command>ssh</command> from repeatedly asking for your
-        password, you'll need to use a separate memory-caching tool
-        like <command>ssh-agent</command> on a Unix-like system, or
-        <command>pageant</command> on Windows.</para>
+        instead of <command>/opt/alternate/ssh -p
+        29934</command>.</para>
 
     </sect2>
 
+    <sect2 id="svn-ch-6-sect-3.5">
+      <title>SSH configuration tricks</title>
+
+      <para>It's not only possible to control the way in which the
+        client invokes <command>ssh</command>, but also to control
+        the behavior of <command>sshd</command> on your server
+        machine.  In this section, we'll show how to control the
+        exact <command>svnserve</command> command executed
+        by <command>sshd</command>, as well as how to have multiple
+        users share a single system account.</para>
+      
+      <sect3 id="svn-ch-6-sect-3.5.1">
+        <title>Initial setup</title>
+        
+        <para>To begin, locate the home directory of the account
+          you'll be using to launch <command>svnserve</command>.  Make
+          sure the account has an SSH public/private keypair
+          installed, and that the user can log in via public-key
+          authentication.  Password authentication will not work,
+          since all of the following SSH tricks revolve around using
+          the SSH <filename>authorized_keys</filename> file.</para>
+
+        <para>If it doesn't already exist, create the
+          <filename>authorized_keys</filename> file (on Unix,
+          typically <filename>~/.ssh/authorized_keys</filename>).
+          Each line in this file describes a public key that is
+          allowed to connect.  The lines are typically of the
+          form:</para>
+
+<screen>
+  ssh-dsa AAAABtce9euch.... user at example.com
+</screen>
+          
+        <para>The first field describes the type of key, the second
+          field is the uuencoded key itself, and the third field is a
+          comment.  However, it's a lesser known fact that the entire
+          line can be preceded by a <literal>command</literal>
+          field:</para>
+
+<screen>
+  command="program" ssh-dsa AAAABtce9euch.... user at example.com
+</screen>
+
+        <para>When the <literal>command</literal> field is set, the
+          SSH daemon will run the named program instead of the
+          typical <command>svnserve -t</command> invocation that the
+          Subversion client asks for.  This opens the door to a number
+          of server-side tricks.  In the following examples, we
+          abbreviate the lines of the file as:</para>
+
+<screen>
+  command="program" TYPE KEY COMMENT
+</screen>
+
+      </sect3>
+      
+      <sect3 id="svn-ch-6-sect-3.5.2">
+        <title>Controlling the invoked command</title>
+
+        <para>Because we can specify the executed server-side command,
+          it's easy to name a specific <command>svnserve</command>
+          binary to run and to pass it extra arguments:</para>
+        
+<screen>
+  command="/path/to/svnserve -t -r /virtual/root" TYPE KEY COMMENT
+</screen>
+
+        <para>In this example, <filename>/path/to/svnserve</filename>
+          might be a custom wrapper script
+          around <command>svnserve</command> which sets the umask (see
+          <xref linkend="svn-ch-6-sect-5"/>).  It also shows how to
+          anchor <command>svnserve</command> in a virtual root
+          directory, just as one often does when
+          running <command>svnserve</command> as a daemon process.
+          This might be done either to restrict access to parts of the
+          system, or simply to relieve the user of having to type an
+          absolute path in the <literal>svn+ssh://</literal>
+          URL.</para>
+        
+        <para>It's also possible to have multiple users share a single
+          account.  Instead of creating a separate system account for
+          each user, generate a public/private keypair for each
+          person.  Then place each public key into
+          the <filename>authorized_users</filename> file, one per
+          line, and use the <option>--tunnel-user</option>
+          option:</para>
+
+<screen>
+  command="svnserve -t --tunnel-user=harry" TYPE1 KEY1 harry at example.com
+  command="svnserve -t --tunnel-user=sally" TYPE2 KEY2 sally at example.com
+</screen>
+
+        <para>This example allows both Harry and Sally to connect to
+          the same account via public-key authentication.  Each of
+          them has a custom command that will be executed;
+          the <option>--tunnel-user</option> option 
+          tells <command>svnserve -t</command> to assume that the named
+          argument is the authenticated user.  Without
+          <option>--tunnel-user</option>, it would appear as though
+          all commits were coming from the one shared system
+          account.</para>
+
+        <para>A final word of caution: giving a user access to the
+          server via public-key in a shared account might still allow
+          other forms of SSH access, even if you've set the
+          the <literal>command</literal> value
+          in <filename>authorized_keys</filename>.  For example, the
+          user may still get shell access through SSH, or be able to
+          perform X11 or general port-forwarding through your server.
+          To give the user as little permission as possible, you may
+          want to specify a number of restrictive options immediately
+          after the <literal>command</literal>:</para>
+
+<screen>
+  command="svnserve -t --tunnel-user=harry",no-port-forwarding,\
+           no-agent-forwarding,no-X11-forwarding,no-pty \
+           TYPE1 KEY1 harry at example.com
+</screen>
+
+      </sect3>
+
+    </sect2>
+    
   </sect1>
 
 
@@ -841,10 +979,10 @@
       network server that Subversion can leverage.  Via a custom
       module, <command>httpd</command> makes Subversion repositories
       available to clients via the WebDAV/DeltaV protocol, which is an
-      extension to HTTP 1.1 (see <systemitem
-      class="url">http://www.webdav.org/</systemitem> for more
-      information.) This protocol takes the ubiquitous HTTP protocol
-      that is the core of the World Wide Web, and adds
+      extension to HTTP 1.1
+      (see <systemitem class="url">http://www.webdav.org/</systemitem>
+      for more information.) This protocol takes the ubiquitous HTTP
+      protocol that is the core of the World Wide Web, and adds
       writing—specifically, versioned
       writing—capabilities.  The result is a standardized,
       robust system that is conveniently packaged as part of the
@@ -1547,13 +1685,13 @@
         <example id="svn-ch-6-sect-4.4.2-ex-1">
           <title>A sample configuration for anonymous access.</title>
           <programlisting>
-            <Location /repos>
-              DAV svn
-              SVNParentPath /usr/local/svn
-
-              # our access control policy
-              AuthzSVNAccessFile /path/to/access/file                 
-            </Location>
+<Location /repos>
+  DAV svn
+  SVNParentPath /usr/local/svn
+
+  # our access control policy
+  AuthzSVNAccessFile /path/to/access/file                 
+</Location>
           </programlisting>
         </example>
 
@@ -1567,21 +1705,21 @@
         <example id="svn-ch-6-sect-4.4.2-ex-2">
           <title>A sample configuration for authenticated access.</title>
           <programlisting>
-            <Location /repos>
-              DAV svn
-              SVNParentPath /usr/local/svn
+<Location /repos>
+  DAV svn
+  SVNParentPath /usr/local/svn
             
-              # our access control policy
-              AuthzSVNAccessFile /path/to/access/file                 
+  # our access control policy
+  AuthzSVNAccessFile /path/to/access/file                 
             
-              # only authenticated users may access the repository
-              Require valid-user
+  # only authenticated users may access the repository
+  Require valid-user
             
-              # how to authenticate a user
-              AuthType Basic
-              AuthName "Subversion repository"
-              AuthUserFile /path/to/users/file                  
-            </Location>
+  # how to authenticate a user
+  AuthType Basic
+  AuthName "Subversion repository"
+  AuthUserFile /path/to/users/file                  
+</Location>
           </programlisting>
         </example>
 
@@ -1601,23 +1739,23 @@
           <title>A sample configuration for mixed
             authenticated/anonymous access.</title>
           <programlisting>
-            <Location /repos>
-              DAV svn
-              SVNParentPath /usr/local/svn
+<Location /repos>
+  DAV svn
+  SVNParentPath /usr/local/svn
             
-              # our access control policy
-              AuthzSVNAccessFile /path/to/access/file                 
+  # our access control policy
+  AuthzSVNAccessFile /path/to/access/file                 
             
-              # try anonymous access first, resort to real 
-              # authentication if necessary.
-              Satisfy Any
-              Require valid-user
+  # try anonymous access first, resort to real 
+  # authentication if necessary.
+  Satisfy Any
+  Require valid-user
             
-              # how to authenticate a user
-              AuthType Basic
-              AuthName "Subversion repository"
-              AuthUserFile /path/to/users/file                  
-            </Location>
+  # how to authenticate a user
+  AuthType Basic
+  AuthName "Subversion repository"
+  AuthUserFile /path/to/users/file                  
+</Location>
           </programlisting>
         </example>
         
@@ -1818,12 +1956,12 @@
         <example id="svn-ch-6-sect-4.4.3-ex-1">
           <title>Disabling path checks altogether</title>
           <programlisting>
-            <Location /repos>
-              DAV svn
-              SVNParentPath /usr/local/svn
+<Location /repos>
+  DAV svn
+  SVNParentPath /usr/local/svn
             
-              SVNPathAuthz off
-            </Location>            
+  SVNPathAuthz off
+</Location>            
           </programlisting>
         </example>
 

Modified: trunk/src/nb/book/ch07.xml
==============================================================================
--- trunk/src/nb/book/ch07.xml	(original)
+++ trunk/src/nb/book/ch07.xml	Tue May 17 22:06:21 2005
@@ -1738,6 +1738,246 @@
   </sect1>
 
   <!-- ******************************************************************* -->
+  <!-- *** SECTION 2 1/2:  ADDRESSING HISTORICAL AMBIGUITY             *** -->
+  <!-- ******************************************************************* -->
+  <sect1 id="svn-ch-7-sect-2b">
+    <title>Addressing Historical Ambiguity</title>
+
+    <para>The ability to copy, move, and rename files and directories;
+      to be able to create an object, then delete it and then add a
+      new one at the same path—those are operations which we
+      perform on files and directories on our computers all the time,
+      and operations we tend to take for granted.  And Subversion
+      would like you to think they are granted.  Subversion's file
+      management support is quite liberating, affording almost as much
+      flexibility for versioned files that you'd expect when
+      manipulating your unversioned ones.  But that flexibility means
+      that across the lifetime of your repository, a given versioned
+      resource might have many paths, and a given path might represent
+      serveral entirely different versioned resources.</para>
+
+    <para>Subversion is pretty smart about noticing when an object's
+      version history includes such <quote>changes of address</quote>.
+      For example, if you ask for all the logs of a particular file
+      that was renamed last week, Subversion happily provides all
+      those logs—the revision in which the rename itself
+      happened, plus the logs of relevant revisions both before and
+      after that rename.  So, most of the time, you don't even have to
+      think about such things.  But occasionally, Subversion needs
+      your help to clear up ambiguities.</para>
+
+    <para>The simplest example of this occurs when a directory or file
+      is deleted from version control, and then a new directory or
+      file is created with the same name and added to version control.
+      Clearly the thing you deleted and the thing you later added
+      aren't the same thing, they merely happen to have had the same
+      path, which we'll call <filename>/trunk/object</filename>.
+      What, then, does it mean to ask Subversion about the history of
+      <filename>/trunk/object</filename>?  Are you asking about the
+      thing currently at that location, or the old thing you deleted
+      from that location?  Are you asking about the operations that
+      have happened to all the objects that have lived at that path?
+      Clearly, Subversion needs a hint about what you are really
+      asking.</para>
+
+    <para>And thanks to moves, versioned resource history can get far
+      more twisted than that, even.  For example, you might have a
+      directory named <filename>concept</filename>, containing some
+      nascent software project you've been toying with.  Eventually,
+      though, that project matures to the point that the idea seems to
+      actually have some wings, so you do the unthinkable and decide
+      to give the project a name.
+      <footnote>
+        <para><quote>You're not supposed to name it.  Once you name it,
+          you start getting attached to it.</quote> — Mike
+          Wazowski</para>
+      </footnote>
+      Let's say you called your software Frabnaggilywort.  At this
+      point, it makes sense to rename the directory to reflect the
+      project's new name, so <filename>concept</filename> is renamed
+      to <filename>frabnaggilywort</filename>.  Life goes on,
+      Frabnaggilywort releases a 1.0 version, and is downloaded and
+      used daily by hordes of people aiming to improve their
+      lives.</para>
+    
+    <para>It's a nice story, really, but it doesn't end there.
+      Entrepreneur that you are, you've already got another think in
+      the tank.  So you make a new directory,
+      <filename>concept</filename>, and the cycle begins again.  In
+      fact, the cycle begins again many times over the years, each
+      time starting with that old <filename>concept</filename>
+      directory, then sometimes seeing that directory renamed as the
+      idea cures, sometimes seeing it deleted when you scrap the idea.
+      Or, to get really sick, maybe you rename
+      <filename>concept</filename> to something else for a while, but
+      later rename the thing back to <filename>concept</filename> for
+      some reason.</para>
+
+    <para>When scenarios like these occur, attempting to instruct
+      Subversion to work with these re-used paths can be a little like
+      instructing a motorist in Chicago's West Suburbs to drive east
+      down Roosevelt Road and turn left onto Main Street.  In a mere
+      twenty minutes, you can cross <quote>Main Street</quote> in
+      Wheaton, Glen Ellyn, and Lombard.  And no, they aren't the same
+      street.  Our motorist—and our Subversion—need a
+      little more detail in order to do the right thing.</para>
+
+    <para>In version 1.1, Subversion introduced a way for you to tell
+      it exactly which Main Street you meant.  It's called the
+      <firstterm>peg revision</firstterm>, and it is a revision
+      provided to Subversion for the sole purpose of identifying a
+      unique line of history.  Because at most one versioned resource
+      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 refer to 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 (-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 <firstterm>operative revision
+      range</firstterm>).  Once a particular line of history has been
+      identified using a path and peg revision, Subversion performs
+      the requested operation using the operative revision(s).  To map
+      this to our Chicagoland streets analogy, if we are told to go to
+      606 N. Main Street in Wheaton,
+      <footnote>
+        <para>606 N. Main Street, Wheaton, Illinois, is the home of
+          the Wheaton History Center.  Get it—<quote>History
+          Center</quote>?  It seemed appropriate….</para>
+      </footnote>
+      we can think of <quote>Main Street</quote> as our path and
+      <quote>Wheaton</quote> as our peg revision.  These two pieces of
+      information identify a unique path which can travelled (north or
+      south on Main Street), and will keep us from travelling up and
+      down the wrong Main Street in search of our destination.  Now we
+      throw in <quote>606 N.</quote> as our operative revision, of
+      sorts, and we know <emphasis>exactly</emphasis> where to
+      go.</para>
+
+    <!-- Drop algorithm here -->
+
+    <para>Say long ago we created our repository, and in revision 1
+      added our first <filename>concept</filename> directory, plus an
+      <filename>IDEA</filename> file in that directory talking about
+      the concept.  After several revisions in which real code was
+      added and tweaked, we, in revision 20, renamed this directory to
+      <filename>frabnaggilywort</filename>.  By revision 27, we had a
+      new concept, a new <filename>concept</filename> directory to
+      hold it, and a new <filename>IDEA</filename> file to describe
+      it.  And then five years and twenty thousand revisions flew by,
+      just like they would in any good romance story.</para>
+
+    <para>Now, years later, we wonder what the
+      <filename>IDEA</filename> file looked like back in revision 1.
+      But Subversion needs to know if we are asking about how the
+      <emphasis>current</emphasis> file looked back in revision 1, or
+      are we asking for the contents of whatever file lived at
+      <filename>concepts/IDEA</filename> in revision 1?  Certainly
+      those questions have different answers, and because of peg
+      revisions, you can ask either of them.  To find out how the
+      current <filename>IDEA</filename> file looked in that old
+      revision, you run:</para>
+
+    <screen>
+$ svn cat -r 1 concept/IDEA 
+subversion/libsvn_client/ra.c:775: (apr_err=20014)
+svn: Unable to find repository location for 'concept/IDEA' in revision 1
+</screen>
+
+    <para>Of course, in this example, the current
+      <filename>IDEA</filename> file didn't exist yet in revision 1,
+      so Subversion gives an error.  The command above is shorthand
+      for a longer notation which explicitly lists a peg revision.
+      The expanded notation is:</para>
+
+    <screen>
+$ svn cat -r 1 concept/IDEA at BASE
+subversion/libsvn_client/ra.c:775: (apr_err=20014)
+svn: Unable to find repository location for 'concept/IDEA' in revision 1
+</screen>
+
+    <para>And when executed, has the expected results.  Peg revisions
+      generally default to a value of <literal>BASE</literal> (the
+      revision currently present in the working copy) when applied to
+      working copy paths, and of <literal>HEAD</literal> when applied
+      to URLs.</para>
+
+    <para>Let's ask the other question, then—in revision 1, what
+      were the contents of whatever file occupied the address
+      <filename>concepts/IDEA</filename> at the time?  We'll use an
+      explicit peg revision to help us out.</para>
+
+    <screen>
+$ svn cat concept/IDEA at 1
+The idea behind this project is to come up with a piece of software
+that can frab a naggily wort.  Frabbing naggily worts is tricky
+business, and doing it incorrectly can have serious ramifications, so
+we need to employ over-the-top input validation and data verification
+mechanisms.
+</screen>
+
+    <para>This appears to be the right output.  The text even mentions
+      frabbing naggily worts, so this is almost certainly the file
+      which describes the software now called Frabnaggilywort.  In
+      fact, we can verify this using the combination of an explicit
+      peg revision and explicit operative revision.  We know that in
+      <literal>HEAD</literal>, the Frabnaggilywort project is located
+      in the <filename>frabnaggilywort</filename> directory.  So we
+      specify that we want to see how the line of history identified
+      in <literal>HEAD</literal> as the path
+      <filename>frabnaggilywort/IDEA</filename> looked in revision
+      1.</para>
+
+    <screen>
+$ svn cat -r 1 frabnaggilywort/IDEA at HEAD
+The idea behind this project is to come up with a piece of software
+that can frab a naggily wort.  Frabbing naggily worts is tricky
+business, and doing it incorrectly can have serious ramifications, so
+we need to employ over-the-top input validation and data verification
+mechanisms.
+</screen>
+
+    <para>And the peg and operative revisions need not be so trivial,
+      either.  For example, say <filename>frabnaggilywort</filename>
+      had beed deleted from <literal>HEAD</literal>, but we know it
+      existed in revision 20, and we want to see the diffs for its
+      <filename>IDEA</filename> file between revisions 4 and 10.  We
+      can use the peg revision 20 in conjunction with the URL that
+      would have held Frabnaggilywort's <filename>IDEA</filename> file
+      in revision 20, and then use 4 and 10 as our operative revision
+      range.</para>
+
+    <screen>
+$ svn diff -r 4:10 http://svn.red-bean.com/projects/frabnaggilywort/IDEA@20
+Index: frabnaggilywort/IDEA
+===================================================================
+--- frabnaggilywort/IDEA	(revision 4)
++++ frabnaggilywort/IDEA	(revision 10)
+@@ -1,5 +1,5 @@
+-The idea behind this project is to come up with a piece of software
+-that can frab a naggily wort.  Frabbing naggily worts is tricky
+-business, and doing it incorrectly can have serious ramifications, so
+-we need to employ over-the-top input validation and data verification
+-mechanisms.
++The idea behind this project is to come up with a piece of
++client-server software that can remotely frab a naggily wort.
++Frabbing naggily worts is tricky business, and doing it incorrectly
++can have serious ramifications, so we need to employ over-the-top
++input validation and data verification mechanisms.
+</screen>
+
+    <para>Fortunately, most folks aren't faced with such complex
+      situations.  But when you are, remember that peg revisions are
+      that extra hint Subversion needs to clear up ambiguity.</para>
+
+  </sect1>
+
+  <!-- ******************************************************************* -->
   <!-- *** SECTION 3:  EXTERNALS DEFINITIONS                           *** -->
   <!-- ******************************************************************* -->
   <sect1 id="svn-ch-7-sect-3">

Modified: trunk/src/nb/book/ch09.xml
==============================================================================
--- trunk/src/nb/book/ch09.xml	(original)
+++ trunk/src/nb/book/ch09.xml	Tue May 17 22:06:21 2005
@@ -5342,6 +5342,14 @@
         </varlistentry>
 
         <varlistentry>
+          <term><option>--version</option></term>
+          <listitem>
+            <para>Displays version information, a list of repository
+            back-end modules available, and exits.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
           <term><option>--root</option>=<replaceable>ROOT</replaceable>
           (<option>-r</option>=<replaceable>ROOT</replaceable>)</term>
           <listitem>
@@ -5532,6 +5540,139 @@
     </refentry>
   </sect1>
 
+  <!-- ================================================================= -->
+  <!-- ======================== SECTION 6 ============================== -->
+  <!-- ================================================================= -->
+  <sect1 id="svn-ch-9-sect-6">
+
+    <title><command>mod_dav_svn</command></title>
+    
+    <refentry id="svn-ch-9-sect-6.1">
+      <refnamediv>
+
+        <refname><literal>mod_dav_svn</literal> Configuration
+        Directives</refname> <refpurpose>Apache configuration
+        directives for serving Subversion repositories through Apache
+        HTTP Server.</refpurpose> 
+
+      </refnamediv>
+
+      <refsect1 id="svn-ch-9-sect-6.1.1">
+        <title>Description</title>
+
+        <para>This section briefly describes each of the Subversion
+          Apache configuration directives.  For an in-depth
+          description of configuring Apache with Subversion, see <xref
+          linkend="svn-ch-6-sect-4"/>.)</para>
+
+      </refsect1>
+
+      <refsect1 id="svn-ch-9-sect-6.1.2">
+        <title>Directives</title>
+
+        <variablelist>
+    
+          <varlistentry>
+            <term><literal>DAV svn</literal></term>
+            <listitem>
+
+              <para>This directive must be included in any
+                <literal>Directory</literal> or
+                <literal>Location</literal> block for a Subversion
+                repository.  It tells httpd to use the Subversion
+                backend for mod_dav to handle all requests.</para>
+
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal>SVNPath</literal></term>
+            <listitem>
+
+              <para>This directive specifies the location in the
+                filesystem for a Subversion repository's files.  In a
+                configuration block for a Subversion repository,
+                either this directive or
+                <literal>SVNParentPath</literal> must be present, but
+                not both.</para>
+
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal>SVNSpecialURI</literal></term>
+            <listitem>
+
+              <para>Specifies the URI component (namespace) for
+                special Subversion resources.  The default is
+                <quote><literal>!svn</literal></quote>, and most
+                administrators will never use this directive.  Only
+                set this if there is a pressing need to have a file
+                named <filename>!svn</filename> in your repository.  If
+                you change this on a server already in use, it will
+                break all of the outstanding working copies and your
+                users will hunt you down with pitchforks and flaming
+                torches.</para>
+
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal>SVNReposName</literal></term>
+            <listitem>
+
+              <para>Specifies the name of a Subversion repository for
+                use in <literal>HTTP GET</literal> requests.  This
+                value will be prepended to the title of all directory
+                listings (which are served when you navigate to a
+                Subversion repository with a web browser).  This
+                directive is optional.</para>
+
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal>SVNIndexXSLT</literal></term>
+            <listitem>
+
+              <para>Specifies the URI of an XSL transformation for
+                directory indexes.  This directive is optional.</para>
+
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal>SVNParentPath</literal></term>
+            <listitem>
+
+              <para>Specifies the location in the filesystem of a
+                parent directory whose child directories are
+                Subversion repositories.  In a configuration block for
+                a Subversion repository, either this directive or
+                <literal>SVNPath</literal> must be present, but not
+                both.</para>
+
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal>SVNPathAuthz</literal></term>
+            <listitem>
+
+              <para>Control path-based authorization by enabling or
+                disabling subrequests.  See <xref
+                linkend="svn-ch-6-sect-4.4.3"/> for details.</para>
+
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </refsect1>
+    </refentry>
+  </sect1>
+
+
+
 </chapter>
 
 <!--

Modified: trunk/src/nb/book/styles.css
==============================================================================
--- trunk/src/nb/book/styles.css	(original)
+++ trunk/src/nb/book/styles.css	Tue May 17 22:06:21 2005
@@ -112,19 +112,28 @@
 
 .table table
 {
-    border: 1px rgb(180,180,180) solid;
-    border-spacing: 0px;
+    border-width: 1px;
+    border-style: solid;
+    border-color: black;
+    border-spacing: 0;
+    background: rgb(240,240,240);
 }
 
 .table td
 {
-    border: 1px rgb(180,180,180) solid;
+    border: none;
+    border-right: 1px black solid;
+    border-bottom: 1px black solid;
+    padding: 2px;
 }
 
 .table th
 {
     background: rgb(180,180,180);
-    border: 1px rgb(180,180,180) solid;
+    border: none;
+    border-right: 1px black solid;
+    border-bottom: 1px black solid;
+    padding: 2px;
 }
 
 .table p.title, .figure p.title, .example p.title
@@ -143,16 +152,28 @@
 
 .sidebar 
 {
-    border: solid 2px rgb(180,180,180);
-    padding: 0.12in;
-    margin: 1em 0.5in;
+    border-top: dotted 1px black;
+    border-left: dotted 1px black;
+    border-right: solid 2px black;
+    border-bottom: solid 2px black;
+    background: rgb(240,220,170);
+    padding: 0 0.12in;
+    margin: 0.5in;
+}
+
+.note .programlisting, .note .screen, 
+.tip .programlisting, .tip .screen, 
+.warning .programlisting, .warning .screen, 
+.sidebar .programlisting, .sidebar .screen
+{
+    border: none;
+    background: none;
 }
 
 .sidebar p.title
 {
     text-align: center;
     font-size: 125%;
-    background: rgb(180,180,180);
 }
 
 .note
@@ -181,9 +202,6 @@
 
 .programlisting, .screen
 {
-    font-family: courier new,courier,fixed;
-    font-style: normal;
-    font-weight: normal;
     font-size: 90%;
     color: black;
     margin: 1em 0.5in;



More information about the svnbook-dev mailing list