[svnbook commit] r2586 - branches/ora-2e-reorg/src/en/book
sussman
noreply at red-bean.com
Mon Jan 1 21:53:09 CST 2007
Author: sussman
Date: Mon Jan 1 21:53:07 2007
New Revision: 2586
Modified:
branches/ora-2e-reorg/src/en/book/book.xml
branches/ora-2e-reorg/src/en/book/ch-preface.xml
Log:
Ben's fixing-up of the Preface, for our Jan. 5 deadline.
* book.xml: update copyright, and also say it's a 1.4 book, not 1.3.
(My understanding is that we're upgrading the book to
cover both 1.3 and 1.4 at a minimum, right? Possibly even 1.5
if it gets finished in the next few months?)
* ch-preface.xml
- add two new starting quotes we can choose from.
- rephrase intro to make CVS sound like it "used" to be the
big standard, but no more. :-)
- Do NOT recommend cygwin to windows users.
- Remove mention of CVS from a number of places, so we stop
sounding like we're constantly migrating CVS users.
- Fix some brokenness in the list of chapter descriptions.
- Add some more names to our huge acknowledgement list.
- Update my own 'thank yous'.
- List svnsync as an installed component.
- Lots of cleanup and rephrasings here and there.
Modified: branches/ora-2e-reorg/src/en/book/book.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/book.xml (original)
+++ branches/ora-2e-reorg/src/en/book/book.xml Mon Jan 1 21:53:07 2007
@@ -26,7 +26,7 @@
<bookinfo>
- <subtitle>For Subversion 1.3</subtitle>
+ <subtitle>For Subversion 1.4</subtitle>
<!-- Using revnumber would be more appropriate, but our stylesheets -->
<!-- don't seem to render it. -->
@@ -67,6 +67,7 @@
<year>2004</year>
<year>2005</year>
<year>2006</year>
+ <year>2007</year>
<holder>Ben Collins-Sussman</holder>
<holder>Brian W. Fitzpatrick</holder>
<holder>C. Michael Pilato</holder>
Modified: branches/ora-2e-reorg/src/en/book/ch-preface.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-preface.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-preface.xml Mon Jan 1 21:53:07 2007
@@ -1,42 +1,61 @@
<preface id="svn.preface">
<title>Preface</title>
-
+
+ <!-- ### TODO(sussman): I replaced our rope-quote with some cool
+ quotes that (to me) demonstrate some core truths about subversion's
+ design philosophy. We probably don't want to keep both of them in
+ there forever... remove one at some point, after we discuss. -->
+
<blockquote>
- <attribution>Brian W. Fitzpatrick</attribution>
- <para><quote>If C gives you enough rope to hang yourself, think
- of Subversion as a sort of rope storage facility.</quote></para>
+ <attribution>Greg Hudson</attribution>
+ <para><quote>Unnecessary optimization is the root of all evil.
+ (Okay, 65% of all evil.)</quote></para>
</blockquote>
- <para>In the world of open-source software, the Concurrent
- Versions System (CVS) has long been the tool of choice for
- version control. And rightly so. CVS itself is free software,
- and its non-restrictive <foreignphrase>modus
- operandi</foreignphrase> and support for networked
- operation—which allow dozens of geographically dispersed
- programmers to share their work—fits the collaborative
- nature of the open-source world very well. CVS and its
- semi-chaotic development model have become cornerstones of
- open-source culture.
+ <blockquote>
+ <attribution>Greg Hudson</attribution>
+ <para><quote>It is important not to let the perfect become the
+ enemy of the good, even when you can agree on what perfect is.
+ Doubly so when you can't. As unpleasant as it is to be trapped by
+ past mistakes, you can't make any progress by being afraid of your
+ own shadow during design.
+</quote></para>
+ </blockquote>
+
+ <!-- ### NOTE: I've rephrased this section to make CVS sound like
+ it "used" to be the big standard, but no more. :-) -->
+
+ <para>In the world of open-source software, the Concurrent Versions
+ System (CVS) was the tool of choice for version control for many
+ years. And rightly so. CVS was open-source software itself, and
+ its non-restrictive <foreignphrase>modus operandi</foreignphrase>
+ and support for networked operation allowed dozens of
+ geographically dispersed programmers to share their work. It fit
+ the collaborative nature of the open-source world very well. CVS
+ and its semi-chaotic development model have since become
+ cornerstones of open-source culture.
</para>
- <para>But like many tools, CVS is starting to show its age.
- Subversion is a relatively new version control system designed
- to be the successor to CVS. The designers set out to win the
- hearts of CVS users in two ways: by creating an open-source
- system with a design (and <quote>look and feel</quote>) similar
- to CVS, and by attempting to fix most of CVS's noticeable flaws.
- While the result isn't necessarily the next great evolution in
- version control design, Subversion <emphasis>is</emphasis> very
- powerful, very usable, and very flexible.
+ <para>But like many tools, CVS began to show its age, and Subversion
+ entered the picture. Subversion was originally designed as a
+ successor to CVS. The designers set out to win the hearts of CVS
+ users in two ways: by creating an open-source system with a design
+ (and <quote>look and feel</quote>) similar to CVS, and by
+ attempting to fix most of CVS's noticeable flaws. While the
+ result isn't necessarily the next great evolution in version
+ control design, Subversion <emphasis>is</emphasis> very powerful,
+ very usable, and very flexible. And for the most part, almost all
+ newly-started open-source projects now choose Subversion instead
+ of CVS.
</para>
- <para>This book is written to document the 1.3 series of the
- Subversion version control system. We have made every attempt to be
- thorough in our coverage. However, Subversion has a thriving
- and energetic development community, so there are already a
- number of features and improvements planned for future versions
- of Subversion that may change some of the commands and specific
- notes in this book.
+ <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
+ and energetic development community, so there are already a number
+ of features and improvements planned for future versions of
+ Subversion that may change some of the commands and specific notes
+ in this book.
</para>
@@ -62,9 +81,7 @@
(<literal>\</literal>) instead of forward slashes
(<literal>/</literal>) for path separators, the input to and
output from this tool when run on Windows are identical to its
- Unix counterpart. However, Windows users may find more success
- by running the examples inside the Cygwin Unix emulation
- environment.</para>
+ Unix counterpart.</para>
<para>Most readers are probably programmers or system
administrators who need to track changes to source code. This
@@ -76,10 +93,11 @@
<para>While this book is written with the assumption that the
reader has never used version control, we've also tried to make
- it easy for users of CVS to make a painless leap into
- Subversion. Special sidebars may discuss CVS from time to time,
- and a special appendix summarizes most of the differences
- between CVS and Subversion.</para>
+ it easy for users of CVS (and other systems) to make a painless
+ leap into Subversion. Special sidebars may mention other
+ version control systems from time to time, and a special
+ appendix summarizes many of the differences between CVS and
+ Subversion.</para>
<para>Note also that the source code examples used throughout the
book are only examples. While they will compile with the proper
@@ -107,15 +125,16 @@
<varlistentry>
<term>Experienced System Administrators</term>
<listitem>
- <para>The assumption here is that you've probably used CVS
- before, and are dying to get a Subversion server up and
- running ASAP. <xref linkend="svn.reposadmin"/> and <xref
- linkend="svn.serverconfig"/> will show you how to create
- your first repository and make it available over the
- network. After that's done, <xref linkend="svn.tour"/> and
+ <para>The assumption here is that you've probably used
+ version control before before, and are dying to get a
+ Subversion server up and running ASAP.
+ <xref linkend="svn.reposadmin"/> and
+ <xref linkend="svn.serverconfig"/> will show you how to
+ create your first repository and make it available over
+ the network. After that's done,
+ <xref linkend="svn.tour"/> and
<xref linkend="svn.forcvs"/> are the fastest routes to
- learning the Subversion client while drawing on your CVS
- experience.</para>
+ learning the Subversion client.</para>
</listitem>
</varlistentry>
@@ -124,11 +143,10 @@
<listitem>
<para>Your administrator has probably set up Subversion
already, and you need to learn how to use the client. If
- you've never used a version control system (like CVS),
- then <xref linkend="svn.basic"/> and <xref
- linkend="svn.tour"/> are a vital introduction. If you're
- already an old hand at CVS, chapter 3 and appendix A are
- the best place to start.</para>
+ you've never used a version control system, then
+ <xref linkend="svn.basic"/> is a vital introduction to the
+ ideas behind version control. <xref linkend="svn.tour"/>
+ is a guided tour of the Subversion client.</para>
</listitem>
</varlistentry>
@@ -142,7 +160,7 @@
linkend="svn.branchmerge"/>), how to use Subversion's
property support, how to configure runtime options (<xref
linkend="svn.advanced"/>), and other things. These two
- chapters aren't vital at first, but be sure to read them
+ chapters aren't critical at first, but be sure to read them
once you're comfortable with the basics.</para>
</listitem>
</varlistentry>
@@ -240,11 +258,10 @@
<variablelist>
<varlistentry>
- <term><xref linkend="svn.intro"/></term>
+ <term><xref linkend="svn.preface"/></term>
<listitem>
<para>Covers the history of Subversion as well as its
- features, architecture, components, and install
- methods. Also includes a quick-start guide.</para>
+ features, architecture, and components.</para>
</listitem>
</varlistentry>
@@ -300,7 +317,7 @@
<para>Explains how to configure your Subversion server and
the three ways to access your repository:
<literal>HTTP</literal>, the <literal>svn</literal>
- protocol, and local access. It also covers the details
+ protocol, and local disk access. It also covers the details
of authentication, authorization and anonymous
access.</para>
</listitem>
@@ -338,6 +355,15 @@
</varlistentry>
<varlistentry>
+ <term><xref linkend="svn.intro"/></term>
+ <listitem>
+ <para>For the impatient, a whirlwind explanation of how to
+ install Subversion and start using it immediately. You
+ have been warned.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><xref linkend="svn.forcvs"/></term>
<listitem>
<para>Covers the similarities and differences between
@@ -394,11 +420,12 @@
</listitem>
<listitem>
- <para>You can distribute and make changes to this book however
- you wish—it's under a free license. Of course,
- rather than distribute your own private version of this
- book, we'd much rather you send feedback and patches to the
- Subversion developer community.</para>
+ <para>You can make changes to this book and redistribute it
+ however you wish—it's under a free license. Your only
+ obligation is to maintain proper attribution to the original
+ authors. Of course, rather than distribute your own private
+ version of this book, we'd much rather you send feedback and
+ patches to the Subversion developer community.</para>
</listitem>
</itemizedlist>
@@ -434,25 +461,27 @@
<para>Finally, we thank the countless people who contributed to
this book with informal reviews, suggestions, and fixes: While
this is undoubtedly not a complete list, this book would be
- incomplete and incorrect without the help of: Jani Averbach,
- Ryan Barrett, Francois Beausoleil, Jennifer Bevan, Matt Blais,
- Zack Brown, Martin Buchholz, Brane Cibej, John R. Daily, Peter
- Davis, Olivier Davy, Robert P. J. Day, Mo DeJong, Brian Denny,
- Joe Drew, Nick Duffek, Ben Elliston, Justin Erenkrantz, Shlomi
- Fish, Julian Foad, Chris Foote, Martin Furter, Dave Gilbert,
- Eric Gillespie, Matthew Gregan, Art Haas, Greg Hudson, Alexis
- Huxley, Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark
- Benedetto King, Andreas J. Koenig, Nuutti Kotivuori, Matt Kraai,
- Scott Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier,
- Bruce A. Mah, Philip Martin, Feliciano Matias, Patrick Mayweg,
- Gareth McCaughan, Jon Middleton, Tim Moloney, Mats Nilsson, Joe
- Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy Popkov,
- Michael Price, Mark Proctor, Steffen Prohaska, Daniel Rall,
- Tobias Ringstrom, Garrett Rooney, Joel Rosdahl, Christian Sauer,
- Larry Shatzer, Russell Steicke, Sander Striker, Erik Sjoelund,
- Johan Sundstroem, John Szakmeister, Mason Thomas, Eric
- Wadsworth, Colin Watson, Alex Waugh, Chad Whitacre, Josef Wolf,
- Blair Zajac, and the entire Subversion community.</para>
+ incomplete and incorrect without the help of: David Anderson,
+ Jani Averbach, Ryan Barrett, Francois Beausoleil, Jennifer
+ Bevan, Matt Blais, Zack Brown, Martin Buchholz, Brane Cibej,
+ John R. Daily, Peter Davis, Olivier Davy, Robert P. J. Day, Mo
+ DeJong, Brian Denny, Joe Drew, Nick Duffek, Ben Elliston, Justin
+ Erenkrantz, Shlomi Fish, Julian Foad, Chris Foote, Martin
+ Furter, Dave Gilbert, Eric Gillespie, David Glasser, Matthew
+ Gregan, Art Haas, Eric Hanchrow, Greg Hudson, Alexis Huxley,
+ Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark Benedetto
+ King, Andreas J. Koenig, Nuutti Kotivuori, Matt Kraai, Scott
+ Lamb, Vincent Lefevre, Morten Ludvigsen, Paul Lussier, Bruce
+ A. Mah, Philip Martin, Feliciano Matias, Patrick Mayweg, Gareth
+ McCaughan, Jon Middleton, Tim Moloney, Christopher Ness, Mats
+ Nilsson, Joe Orton, Amy Lyn Pilato, Kevin Pilch-Bisson, Dmitriy
+ Popkov, Michael Price, Mark Proctor, Steffen Prohaska, Daniel
+ Rall, Jack Repenning, Tobias Ringstrom, Garrett Rooney, Joel
+ Rosdahl, Christian Sauer, Larry Shatzer, Russell Steicke, Sander
+ Striker, Erik Sjoelund, Johan Sundstroem, John Szakmeister,
+ Mason Thomas, Eric Wadsworth, Colin Watson, Alex Waugh, Chad
+ Whitacre, Josef Wolf, Blair Zajac, and the entire Subversion
+ community.</para>
<!-- =============================================================== -->
<sect2 id="svn.preface.acks.sussman">
@@ -463,22 +492,28 @@
rather than the usual, <quote>But honey, I'm still doing
email.</quote> I don't know where she gets all that patience!
She's my perfect counterbalance.</para>
-
- <para>Thanks to my extended family for their sincere
+
+ <para>Thanks to my extended family and friends for their sincere
encouragement, despite having no actual interest in the
- subject. (You know, the ones who say, <quote>Ooh, you're
- writing a book?</quote>, and then when you tell them it's a
- computer book, sort of glaze over.)</para>
+ subject. (You know, the ones who say, <quote>Ooh, you wrote a
+ book?</quote>, and then when you tell them it's a computer
+ book, sort of glaze over.)</para>
<para>Thanks to all my close friends, who make me a rich, rich man.
Don't look at me that way—you know who you are.</para>
+ <para>Thanks to my parents for the perfect low-level formatting,
+ and being unbelievable role models. Thanks to my son for the
+ opportunity to pass that on.</para>
+
</sect2>
<!-- =============================================================== -->
<sect2 id="svn.preface.acks.fitz">
<title>From Brian W. Fitzpatrick</title>
+ <!-- ### TODO(fitz): update this? -->
+
<para>Huge thanks to my wife Marie for being incredibly
understanding, supportive, and most of all, patient. Thank
you to my brother Eric who first introduced me to UNIX
@@ -505,6 +540,8 @@
<sect2 id="svn.preface.acks.cmpilato">
<title>From C. Michael Pilato</title>
+ <!-- ### TODO(cmpilato): update this? -->
+
<para>Special thanks to my wife, Amy, for her love and patient
support, for putting up with late nights, and for even
reviewing entire sections of this book—you always go the
@@ -657,7 +694,7 @@
And if you're not familiar with version control at all, your
eyes may glaze over unless you first read <xref
linkend="svn.basic"/>, in which we provide a gentle introduction
- to version control in general.</para>
+ to version control.</para>
<para>Subversion provides:</para>
@@ -774,8 +811,8 @@
<title>Subversion's Architecture</title>
- <para><xref linkend="svn.intro.architecture.dia-1"/> illustrates what one might
- call a <quote>mile-high</quote> view of Subversion's
+ <para><xref linkend="svn.intro.architecture.dia-1"/> illustrates
+ a <quote>mile-high</quote> view of Subversion's
design.</para>
<figure id="svn.intro.architecture.dia-1">
@@ -825,7 +862,7 @@
<varlistentry>
<term>svnlook</term>
<listitem>
- <para>A tool for inspecting a Subversion repository.</para>
+ <para>A tool for directly inspecting a Subversion repository.</para>
</listitem>
</varlistentry>
@@ -862,6 +899,15 @@
your repository available to others over a network.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>svnsync</term>
+ <listitem>
+ <para>A program for incrementally mirroring one
+ repository to another over a network.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
<para>Assuming you have Subversion installed correctly, you should
More information about the svnbook-dev
mailing list