[svnbook commit] r2576 - in branches/ora-2e-reorg/src: en en/book tools
cmpilato
noreply at red-bean.com
Thu Dec 21 00:01:51 CST 2006
Author: cmpilato
Date: Thu Dec 21 00:01:49 2006
New Revision: 2576
Modified:
branches/ora-2e-reorg/src/en/Makefile
branches/ora-2e-reorg/src/en/README
branches/ora-2e-reorg/src/en/book/app-quickstart.xml
branches/ora-2e-reorg/src/en/book/app-svn-for-cvs-users.xml
branches/ora-2e-reorg/src/en/book/app-third-party-tools.xml
branches/ora-2e-reorg/src/en/book/app-webdav.xml
branches/ora-2e-reorg/src/en/book/book.xml
branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml
branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml
branches/ora-2e-reorg/src/en/book/ch-branching-and-merging.xml
branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml
branches/ora-2e-reorg/src/en/book/ch-developer-info.xml
branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml
branches/ora-2e-reorg/src/en/book/ch-preface.xml
branches/ora-2e-reorg/src/en/book/ch-reference.xml
branches/ora-2e-reorg/src/en/book/ch-repository-admin.xml
branches/ora-2e-reorg/src/en/book/ch-server-configuration.xml
branches/ora-2e-reorg/src/en/book/copyright.xml
branches/ora-2e-reorg/src/en/book/foreword.xml
branches/ora-2e-reorg/src/en/book/styles.css
branches/ora-2e-reorg/src/tools/Makefile.base-rules
Log:
Branch: ora-2e-reorg
Upgrade the book sources to DocBook 4.4 (from DocBook Lite). We are,
of course, not making use of the full DTD, but we certainly can.
* src/en/book/app-quickstart.xml
* src/en/book/app-svn-for-cvs-users.xml
* src/en/book/app-third-party-tools.xml
* src/en/book/app-webdav.xml
* src/en/book/ch-advanced-topics.xml
* src/en/book/ch-basic-usage.xml
* src/en/book/ch-branching-and-merging.xml
* src/en/book/ch-customizing-svn.xml
* src/en/book/ch-developer-info.xml
* src/en/book/ch-fundamental-concepts.xml
* src/en/book/ch-preface.xml
* src/en/book/ch-reference.xml
* src/en/book/ch-repository-admin.xml
* src/en/book/ch-server-configuration.xml
* src/en/book/copyright.xml
* src/en/book/foreword.xml
Minor, mostly-non-content tweaks for DocBook 4.4 compliance.
* src/en/book/book.xml
Tweak this for DocBook 4.4 compliance. Update the edition and
editor blobs, and unset the ISBN number.
* src/tools/Makefile.base-rules
(version): Reduce the svn.version entity definition to *just* the
output from svnversion. Add new svn.l10n_revision and svn.date
entity definitions.
* src/en/Makefile
(L10N_REVISION): Override the default value of "Revision" with just "r".
* src/en/README
Note the fact that we are using DocBook 4.4 instead of DocBook Lite,
and provide a URL to an online reference.
* src/en/book/styles.css
Fix the way authors and publication dates are rendered.
Modified: branches/ora-2e-reorg/src/en/Makefile
==============================================================================
--- branches/ora-2e-reorg/src/en/Makefile (original)
+++ branches/ora-2e-reorg/src/en/Makefile Thu Dec 21 00:01:49 2006
@@ -1 +1,2 @@
include ../tools/Makefile.base
+L10N_REVISION = r
Modified: branches/ora-2e-reorg/src/en/README
==============================================================================
--- branches/ora-2e-reorg/src/en/README (original)
+++ branches/ora-2e-reorg/src/en/README Thu Dec 21 00:01:49 2006
@@ -1,8 +1,7 @@
HOW-TO: Compiling the Subversion Book
======================================
-This Subversion Book is written in DocBook Lite, a scaled-down version
-of the DocBook DTD, used by O'Reilly & Associates.
+This Subversion Book is written in DocBook 4.4.
The goal of this document is to give simple instructions to anyone who
wants to compile this book into a useful format, like HTML or PDF. It
@@ -173,8 +172,7 @@
$ make valid
-3. Read about the DocBook lite tags.
+3. Read about DocBook.
- The tools area contains the readme-dblite.html file which describes
- how to write with DocBook Lite. Familiarize yourself with these
- tags before changing the docs.
+ You'll want to get real intimate with a DocBook reference, such as
+ can be found at: http://www.docbook.org/tdg/en/html/index.html
\ No newline at end of file
Modified: branches/ora-2e-reorg/src/en/book/app-quickstart.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/app-quickstart.xml (original)
+++ branches/ora-2e-reorg/src/en/book/app-quickstart.xml Thu Dec 21 00:01:49 2006
@@ -2,23 +2,21 @@
<title>Subversion Quick-Start Guide</title>
- <simplesect>
- <para>Some people have trouble absorbing a new technology by
- reading the sort of <quote>top down</quote> approach provided by
- this book. This appendix contains a very short introduction to
- Subversion, and is designed to give <quote>bottom up</quote>
- learners a fighting chance. If you prefer to learn by
- experimentation, the following demonstration will get you up and
- running. Along the way, we give links to the relevant chapters
- of this book.</para>
-
- <para>If you're new to the entire concept of version control or to
- the <quote>copy-modify-merge</quote> model used by both CVS and
- Subversion, then you should read <xref linkend="svn.basic"/>
- before going any further.</para>
+ <para>Some people have trouble absorbing a new technology by
+ reading the sort of <quote>top down</quote> approach provided by
+ this book. This appendix contains a very short introduction to
+ Subversion, and is designed to give <quote>bottom up</quote>
+ learners a fighting chance. If you prefer to learn by
+ experimentation, the following demonstration will get you up and
+ running. Along the way, we give links to the relevant chapters
+ of this book.</para>
+
+ <para>If you're new to the entire concept of version control or to
+ the <quote>copy-modify-merge</quote> model used by both CVS and
+ Subversion, then you should read <xref linkend="svn.basic"/>
+ before going any further.</para>
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
Modified: branches/ora-2e-reorg/src/en/book/app-svn-for-cvs-users.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/app-svn-for-cvs-users.xml (original)
+++ branches/ora-2e-reorg/src/en/book/app-svn-for-cvs-users.xml Thu Dec 21 00:01:49 2006
@@ -1,22 +1,19 @@
<appendix id="svn.forcvs">
<title>Subversion for CVS Users</title>
- <simplesect>
+ <para>This appendix is a guide for CVS users new to Subversion.
+ It's essentially a list of differences between the two systems
+ as <quote>viewed from 10,000 feet</quote>. For each section, we
+ provide backreferences to relevant chapters when
+ possible.</para>
+
+ <para>Although the goal of Subversion is to take over the current
+ and future CVS user base, some new features and design changes
+ were required to fix certain <quote>broken</quote> behaviors
+ that CVS had. This means that, as a CVS user, you may need to
+ break habits—ones that you forgot were odd to begin
+ with.</para>
- <para>This appendix is a guide for CVS users new to Subversion.
- It's essentially a list of differences between the two systems
- as <quote>viewed from 10,000 feet</quote>. For each section, we
- provide backreferences to relevant chapters when
- possible.</para>
-
- <para>Although the goal of Subversion is to take over the current
- and future CVS user base, some new features and design changes
- were required to fix certain <quote>broken</quote> behaviors
- that CVS had. This means that, as a CVS user, you may need to
- break habits—ones that you forgot were odd to begin
- with.</para>
-
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
Modified: branches/ora-2e-reorg/src/en/book/app-third-party-tools.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/app-third-party-tools.xml (original)
+++ branches/ora-2e-reorg/src/en/book/app-third-party-tools.xml Thu Dec 21 00:01:49 2006
@@ -1,19 +1,15 @@
<appendix id="svn.3rdparty">
<title>Third Party Tools</title>
- <simplesect>
-
- <para>Subversion's modular design (covered in <xref
- linkend="svn.developer.layerlib"/>) and the availability of
- language bindings (as described in <xref
- linkend="svn.developer.usingapi.otherlangs"/>) make it a likely
- candidate for use as an extension or backend to other pieces of
- software. For a listing of many third-party tools that are using
- Subversion functionality under-the-hood, check out the Links page on the
- Subversion website (<ulink
- url="http://subversion.tigris.org/project_links.html"/>).</para>
-
- </simplesect>
+ <para>Subversion's modular design (covered in <xref
+ linkend="svn.developer.layerlib"/>) and the availability of
+ language bindings (as described in <xref
+ linkend="svn.developer.usingapi.otherlangs"/>) make it a likely
+ candidate for use as an extension or backend to other pieces of
+ software. For a listing of many third-party tools that are using
+ Subversion functionality under-the-hood, check out the Links page on the
+ Subversion website (<ulink
+ url="http://subversion.tigris.org/project_links.html"/>).</para>
</appendix>
Modified: branches/ora-2e-reorg/src/en/book/app-webdav.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/app-webdav.xml (original)
+++ branches/ora-2e-reorg/src/en/book/app-webdav.xml Thu Dec 21 00:01:49 2006
@@ -1,21 +1,18 @@
<appendix id="svn.webdav">
<title>WebDAV and Autoversioning</title>
- <simplesect>
+ <para>WebDAV is an extension to HTTP, and is growing more and more
+ popular as a standard for file-sharing. Today's operating systems
+ are becoming extremely Web-aware, and many now have built-in
+ support for mounting <quote>shares</quote> exported by WebDAV
+ servers.</para>
+
+ <para>If you use Apache/mod_dav_svn as your Subversion network
+ server, then to some extent, you are also running a WebDAV server.
+ This appendix gives some background on the nature of this
+ protocol, how Subversion uses it, and how well Subversion
+ interoperates with other software that is WebDAV-aware.</para>
- <para>WebDAV is an extension to HTTP, and is growing more and more
- popular as a standard for file-sharing. Today's operating
- systems are becoming extremely Web-aware, and many now have
- built-in support for mounting <quote>shares</quote> exported by
- WebDAV servers.</para>
-
- <para>If you use Apache/mod_dav_svn as your Subversion network
- server, then to some extent, you are also running a WebDAV
- server. This appendix gives some background on the nature of
- this protocol, how Subversion uses it, and how well Subversion
- interoperates with other software that is WebDAV-aware.</para>
-
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
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 Thu Dec 21 00:01:49 2006
@@ -1,5 +1,5 @@
<?xml version="1.0"?>
-<!DOCTYPE book SYSTEM "../../tools/dtd/dblite.dtd"
+<!DOCTYPE book SYSTEM "../../tools/dtd/docbook-4.4/docbookx.dtd"
[
<!ENTITY % vers SYSTEM "version.xml">
%vers;
@@ -24,15 +24,16 @@
<book id="svn">
<title>Version Control with Subversion</title>
- <!-- Using revnumber would be more appropriate, but our stylesheets -->
- <!-- don't seem to render it. -->
- <subtitle>For Subversion 1.3</subtitle>
- <subtitle>(book compiled from &svn.version;)</subtitle>
-
<bookinfo>
- <edition>First</edition>
- <isbn>0-59600-448-6</isbn>
+ <subtitle>For Subversion 1.3</subtitle>
+
+ <!-- Using revnumber would be more appropriate, but our stylesheets -->
+ <!-- don't seem to render it. -->
+ <subtitle>(Compiled from &svn.l10n_revision;&svn.version;)</subtitle>
+
+ <edition>Second</edition>
+ <isbn>?-?????-???-?</isbn>
<authorgroup>
<author>
@@ -53,8 +54,8 @@
</authorgroup>
<editor>
- <firstname>Linda</firstname>
- <surname>Mui</surname>
+ <firstname>Tatiana</firstname>
+ <surname>Apandi</surname>
</editor>
<pagenums>350 pages (est.)</pagenums>
Modified: branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml Thu Dec 21 00:01:49 2006
@@ -1,43 +1,40 @@
<chapter id="svn.advanced">
<title>Advanced Topics</title>
- <simplesect>
+ <para>If you've been reading this book chapter by chapter, from
+ start to finish, you should by now have acquired enough
+ knowledge to use the Subversion client to perform the most
+ common version control operations. You understand how to
+ checkout a working copy from a Subversion repository. You are
+ comfortable with submitting and receiving changes using the
+ <command>svn commit</command> and <command>svn update</command>
+ functions. You've probably even developed a reflex which causes
+ you to run the <command>svn status</command> command almost
+ unconsciously. For all intents and purposes, you are ready to
+ use Subversion in a typical environment.</para>
+
+ <para>But the Subversion feature set doesn't stop at <quote>common
+ version control operations</quote>.</para>
+
+ <para>This chapter highlights some of Subversion's features that
+ aren't quite so regularly used. In it, we will discuss
+ Subversion's property (or <quote>metadata</quote>) support, and
+ how to modify Subversion's default behaviors by tweaking its
+ run-time configuration area. We will describe how you can use
+ externals definitions to instruct Subversion to pull data from
+ multiple repositories. We'll cover in detail some of the
+ additional client- and server-side tools that are part of the
+ Subversion distribution.</para>
+
+ <para>Before reading this chapter, you should be familiar with the
+ basic file and directory versioning capabilities of Subversion.
+ If you haven't already read about those, or if you need a
+ refresher, we recommend that you check out <xref
+ linkend="svn.basic" /> and <xref linkend="svn.tour" />. Once
+ you've mastered the basics and consumed this chapter, you'll be
+ a Subversion power-user!
+ </para>
- <para>If you've been reading this book chapter by chapter, from
- start to finish, you should by now have acquired enough
- knowledge to use the Subversion client to perform the most
- common version control operations. You understand how to
- checkout a working copy from a Subversion repository. You are
- comfortable with submitting and receiving changes using the
- <command>svn commit</command> and <command>svn update</command>
- functions. You've probably even developed a reflex which causes
- you to run the <command>svn status</command> command almost
- unconsciously. For all intents and purposes, you are ready to
- use Subversion in a typical environment.</para>
-
- <para>But the Subversion feature set doesn't stop at <quote>common
- version control operations</quote>.</para>
-
- <para>This chapter highlights some of Subversion's features that
- aren't quite so regularly used. In it, we will discuss
- Subversion's property (or <quote>metadata</quote>) support, and
- how to modify Subversion's default behaviors by tweaking its
- run-time configuration area. We will describe how you can use
- externals definitions to instruct Subversion to pull data from
- multiple repositories. We'll cover in detail some of the
- additional client- and server-side tools that are part of the
- Subversion distribution.</para>
-
- <para>Before reading this chapter, you should be familiar with the
- basic file and directory versioning capabilities of Subversion.
- If you haven't already read about those, or if you need a
- refresher, we recommend that you check out <xref
- linkend="svn.basic" /> and <xref linkend="svn.tour" />. Once
- you've mastered the basics and consumed this chapter, you'll be
- a Subversion power-user!
- </para>
-
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
Modified: branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-basic-usage.xml Thu Dec 21 00:01:49 2006
@@ -1,26 +1,23 @@
<chapter id="svn.tour">
<title>Basic Usage</title>
- <simplesect>
+ <para>Now we will go into the details of using Subversion. By the
+ time you reach the end of this chapter, you will be able to
+ perform almost all the tasks you need to use Subversion in a
+ normal day's work. You'll start with an initial checkout of
+ your code, and walk through making changes and examining those
+ changes. You'll also see how to bring changes made by others
+ into your working copy, examine them, and work through any
+ conflicts that might arise.</para>
+
+ <para>Note that this chapter is not meant to be an exhaustive list
+ of all Subversion's commands—rather, it's a conversational
+ introduction to the most common Subversion tasks you'll
+ encounter. This chapter assumes that you've read and understood
+ <xref linkend="svn.basic"/> and are familiar with the general
+ model of Subversion. For a complete reference of all commands,
+ see <xref linkend="svn.ref"/>.</para>
- <para>Now we will go into the details of using Subversion. By the
- time you reach the end of this chapter, you will be able to
- perform almost all the tasks you need to use Subversion in a
- normal day's work. You'll start with an initial checkout of
- your code, and walk through making changes and examining those
- changes. You'll also see how to bring changes made by others
- into your working copy, examine them, and work through any
- conflicts that might arise.</para>
-
- <para>Note that this chapter is not meant to be an exhaustive list
- of all Subversion's commands—rather, it's a conversational
- introduction to the most common Subversion tasks you'll
- encounter. This chapter assumes that you've read and understood
- <xref linkend="svn.basic"/> and are familiar with the general
- model of Subversion. For a complete reference of all commands,
- see <xref linkend="svn.ref"/>.</para>
-
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -809,7 +806,7 @@
two commands to find out what files have changed in your
working copy, and then perhaps the third to revert some (or
all) of those changes.</para>
-
+
<!-- pll - Fri 07 Feb 2003 12:55:07 -->
<!-- I find this following paragraph a little unclear. Mostly for -->
<!-- the same reasons as I found the sidebar above unclear. There -->
@@ -817,6 +814,37 @@
<!-- therefore, nothing has been clearly stated wrt the fact that the -->
<!-- repository may not be local. -->
+ <sidebar>
+ <title>Look Ma! No Network!</title>
+
+ <para>All three of these commands (<command>svn
+ status</command>, <command>svn diff</command>, and
+ <command>svn revert</command>) can be used without any
+ network access. 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.</para>
+
+ <para>Subversion does this by keeping private caches of
+ pristine versions of each versioned file inside of the
+ <filename>.svn</filename> administrative areas. This allows
+ Subversion to report—and revert—local
+ modifications to those files <emphasis>without network
+ access</emphasis>. This cache (called the
+ <quote>text-base</quote>) also allows Subversion to send the
+ user's local modifications during a commit to the server as
+ a compressed <firstterm>delta</firstterm> (or
+ <quote>difference</quote>) against the pristine version.
+ Having this cache is a tremendous benefit—even if you
+ have a fast net connection, it's much faster to send only a
+ file's changes rather than the whole file to the server. At
+ first glance, this might not seem that important, but
+ imagine the repercussions if you try to commit a one line
+ change to a 400MB file and have to send the whole file to
+ the server!</para>
+
+ </sidebar>
+
<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
@@ -1291,36 +1319,6 @@
</sect3>
- <sidebar>
- <title>Look Ma! No Network!</title>
-
- <para>All three of these commands (<command>svn
- status</command>, <command>svn diff</command>, and
- <command>svn revert</command>) can be used without any
- network access. 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.</para>
-
- <para>Subversion does this by keeping private caches of
- pristine versions of each versioned file inside of the
- <filename>.svn</filename> administrative areas. This allows
- Subversion to report—and revert—local
- modifications to those files <emphasis>without network
- access</emphasis>. This cache (called the
- <quote>text-base</quote>) also allows Subversion to send the
- user's local modifications during a commit to the server as
- a compressed <firstterm>delta</firstterm> (or
- <quote>difference</quote>) against the pristine version.
- Having this cache is a tremendous benefit—even if you
- have a fast net connection, it's much faster to send only a
- file's changes rather than the whole file to the server. At
- first glance, this might not seem that important, but
- imagine the repercussions if you try to commit a one line
- change to a 400MB file and have to send the whole file to
- the server!</para>
- </sidebar>
-
</sect2>
<!-- =============================================================== -->
@@ -1587,12 +1585,20 @@
$ svn commit -m "Go ahead and use my sandwich, discarding Sally's edits."
</screen>
- <para>Remember, if you ever get confused while editing the
- conflicted file, you can always consult the three files that
- Subversion creates for you in your working
- copy—including your file as it was before you updated.
- You can even use a third-party interactive merging tool to
- examine those three files.</para>
+ <para>Note that <command>svn resolved</command>, unlike most
+ of the other commands we deal with in this chapter, requires
+ an argument. In any case, you want to be careful and only
+ run <command>svn resolved</command> when you're certain that
+ you've fixed the conflict in your file—once the
+ temporary files are removed, Subversion will let you commit
+ the file even if it still contains conflict markers.</para>
+
+ <para>If you ever get confused while editing the conflicted
+ file, you can always consult the three files that Subversion
+ creates for you in your working copy—including your
+ file as it was before you updated. You can even use a
+ third-party interactive merging tool to examine those three
+ files.</para>
</sect3>
@@ -1635,15 +1641,6 @@
</sect3>
- <para>Now you're ready to check in your changes. Note that
- <command>svn resolved</command>, unlike most of the other
- commands we've dealt with in this chapter, requires an
- argument. In any case, you want to be careful and only run
- <command>svn resolved</command> when you're certain that you've
- fixed the conflict in your file—once the temporary files
- are removed, Subversion will let you commit the file even if
- it still contains conflict markers.</para>
-
</sect2>
<!-- =============================================================== -->
Modified: branches/ora-2e-reorg/src/en/book/ch-branching-and-merging.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-branching-and-merging.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-branching-and-merging.xml Thu Dec 21 00:01:49 2006
@@ -1,21 +1,18 @@
<chapter id="svn.branchmerge">
<title>Branching and Merging</title>
- <simplesect>
+ <para>Branching, tagging, and merging are concepts common to
+ almost all version control systems. If you're not familiar with
+ these ideas, we provide a good introduction in this chapter. If
+ you are familiar, then hopefully you'll find it interesting to
+ see how Subversion implements these ideas.</para>
+
+ <para>Branching is a fundamental part of version control. If
+ you're going to allow Subversion to manage your data, then this
+ is a feature you'll eventually come to depend on. This chapter
+ assumes that you're already familiar with Subversion's basic
+ concepts (<xref linkend="svn.basic"/>).</para>
- <para>Branching, tagging, and merging are concepts common to
- almost all version control systems. If you're not familiar with
- these ideas, we provide a good introduction in this chapter. If
- you are familiar, then hopefully you'll find it interesting to
- see how Subversion implements these ideas.</para>
-
- <para>Branching is a fundamental part of version control. If
- you're going to allow Subversion to manage your data, then this
- is a feature you'll eventually come to depend on. This chapter
- assumes that you're already familiar with Subversion's basic
- concepts (<xref linkend="svn.basic"/>).</para>
-
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -862,39 +859,6 @@
</sect3>
- <sidebar>
- <title>Subversion and Changesets</title>
-
- <para>Everyone seems to have a slightly different definition
- of <quote>changeset</quote>, or at least a different
- expectation of what it means for a version control system to
- have <quote>changeset features</quote>. For our purpose,
- let's say that a changeset is just a collection of changes
- with a unique name. The changes might include textual edits
- to file contents, modifications to tree structure, or tweaks
- to metadata. In more common speak, a changeset is just a
- patch with a name you can refer to.</para>
-
- <para>In Subversion, a global revision number N names a tree
- in the repository: it's the way the repository looked after
- the Nth commit. It's also the name of an implicit
- changeset: if you compare tree N with tree N-1, you can
- derive the exact patch that was committed. For this reason,
- it's easy to think of <quote>revision N</quote> as not just
- a tree, but a changeset as well. If you use an issue
- tracker to manage bugs, you can use the revision numbers to
- refer to particular patches that fix bugs—for example,
- <quote>this issue was fixed by revision 9238.</quote>.
- Somebody can then run <command>svn log -r9238</command> to
- read about the exact changeset which fixed the bug, and run
- <command>svn diff -r9237:9238</command> to see the patch
- itself. And Subversion's <literal>merge</literal> command
- also uses revision numbers. You can merge specific changesets
- from one branch to another by naming them in the merge
- arguments: <command>svn merge -r9237:9238</command> would
- merge changeset #9238 into your working copy.</para>
- </sidebar>
-
<sect3 id="svn.branchmerge.copychanges.bestprac.merge">
<title>Merge Conflicts</title>
@@ -1276,6 +1240,39 @@
changeset #303 to our working copy
<emphasis>backwards</emphasis>.</para>
+ <sidebar>
+ <title>Subversion and Changesets</title>
+
+ <para>Everyone seems to have a slightly different definition
+ of <quote>changeset</quote>, or at least a different
+ expectation of what it means for a version control system to
+ have <quote>changeset features</quote>. For our purpose,
+ let's say that a changeset is just a collection of changes
+ with a unique name. The changes might include textual edits
+ to file contents, modifications to tree structure, or tweaks
+ to metadata. In more common speak, a changeset is just a
+ patch with a name you can refer to.</para>
+
+ <para>In Subversion, a global revision number N names a tree
+ in the repository: it's the way the repository looked after
+ the Nth commit. It's also the name of an implicit
+ changeset: if you compare tree N with tree N-1, you can
+ derive the exact patch that was committed. For this reason,
+ it's easy to think of <quote>revision N</quote> as not just
+ a tree, but a changeset as well. If you use an issue
+ tracker to manage bugs, you can use the revision numbers to
+ refer to particular patches that fix bugs—for example,
+ <quote>this issue was fixed by revision 9238.</quote>.
+ Somebody can then run <command>svn log -r9238</command> to
+ read about the exact changeset which fixed the bug, and run
+ <command>svn diff -r9237:9238</command> to see the patch
+ itself. And Subversion's <literal>merge</literal> command
+ also uses revision numbers. You can merge specific changesets
+ from one branch to another by naming them in the merge
+ arguments: <command>svn merge -r9237:9238</command> would
+ merge changeset #9238 into your working copy.</para>
+ </sidebar>
+
<para>Keep in mind that rolling back a change like this is just
like any other <command>svn merge</command> operation, so you
should use <command>svn status</command> and <command>svn
Modified: branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-customizing-svn.xml Thu Dec 21 00:01:49 2006
@@ -1,11 +1,8 @@
<chapter id="svn.customization">
<title>Customizing Your Subversion Experience</title>
- <simplesect>
+ <para>### TODO ###</para>
- <para>### TODO ###</para>
-
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
Modified: branches/ora-2e-reorg/src/en/book/ch-developer-info.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-developer-info.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-developer-info.xml Thu Dec 21 00:01:49 2006
@@ -1,29 +1,26 @@
<chapter id="svn.developer">
<title>Developer Information</title>
- <simplesect>
+ <para>Subversion has a modular design, implemented as a collection
+ of C libraries. Each library has a well-defined purpose and
+ interface, and those interfaces are available not only for
+ Subversion itself to use, but for any software that wishes to
+ embed or otherwise programmatically control Subversion. Most of
+ those interfaces are available not only in C, but also in
+ higher-level languages such as Python or Java.</para>
+
+ <para>This chapter is for those who wish to interact with
+ Subversion through its public Application Programming Interface
+ (API) or various language bindings. If you wish to write robust
+ wrapper scripts around Subversion functionality to simplify your
+ own life, are trying to develop more complex integrations
+ between Subversion and other pieces of software, or just have an
+ interest in Subversion's various library modules and what they
+ offer, this chapter is for you. If, however, you don't foresee
+ yourself participating with Subversion at such a level, feel
+ free to skip this chapter with the confidence that your
+ experience as a Subversion user will not be affected.</para>
- <para>Subversion has a modular design, implemented as a collection
- of C libraries. Each library has a well-defined purpose and
- interface, and those interfaces are available not only for
- Subversion itself to use, but for any software that wishes to
- embed or otherwise programmatically control Subversion. Most of
- those interfaces are available not only in C, but also in
- higher-level languages such as Python or Java.</para>
-
- <para>This chapter is for those who wish to interact with
- Subversion through its public Application Programming Interface
- (API) or various language bindings. If you wish to write robust
- wrapper scripts around Subversion functionality to simplify your
- own life, are trying to develop more complex integrations
- between Subversion and other pieces of software, or just have an
- interest in Subversion's various library modules and what they
- offer, this chapter is for you. If, however, you don't foresee
- yourself participating with Subversion at such a level, feel
- free to skip this chapter with the confidence that your
- experience as a Subversion user will not be affected.</para>
-
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -911,17 +908,14 @@
used by any program to do these conversions.</para>
<para>Also, Subversion APIs require all URL parameters to be
- properly URI-encoded. So, instead of passing <systemitem
- class="url">file:///home/username/My File.txt</systemitem> as
- the URL of a file named <literal>My File.txt</literal>, you
- need to pass <systemitem
- class="url">file:///home/username/My%20File.txt</systemitem>.
- Again, Subversion supplies helper functions that your
- application can
+ properly URI-encoded. So, instead of passing
+ <uri>file:///home/username/My File.txt</uri> as the URL of a
+ file named <literal>My File.txt</literal>, you need to pass
+ <uri>file:///home/username/My%20File.txt</uri>. Again,
+ Subversion supplies helper functions that your application can
use—<function>svn_path_uri_encode()</function> and
- <function>svn_path_uri_decode()</function>, for URI encoding and
- decoding, respectively.</para>
- </sect2>
+ <function>svn_path_uri_decode()</function>, for URI encoding
+ and decoding, respectively.</para> </sect2>
<!-- =============================================================== -->
<sect2 id="svn.developer.usingapi.otherlangs">
Modified: branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-fundamental-concepts.xml Thu Dec 21 00:01:49 2006
@@ -1,19 +1,17 @@
<chapter id="svn.basic">
<title>Fundamental Concepts</title>
- <simplesect>
- <para>This chapter is a short, casual introduction to Subversion.
- If you're new to version control, this chapter is definitely for
- you. We begin with a discussion of general version control
- concepts, work our way into the specific ideas behind
- Subversion, and show some simple examples of Subversion in
- use.</para>
-
- <para>Even though the examples in this chapter show people sharing
- collections of program source code, keep in mind that Subversion
- can manage any sort of file collection—it's not limited to
- helping computer programmers.</para>
- </simplesect>
+ <para>This chapter is a short, casual introduction to Subversion.
+ If you're new to version control, this chapter is definitely for
+ you. We begin with a discussion of general version control
+ concepts, work our way into the specific ideas behind
+ Subversion, and show some simple examples of Subversion in
+ use.</para>
+
+ <para>Even though the examples in this chapter show people sharing
+ collections of program source code, keep in mind that Subversion
+ can manage any sort of file collection—it's not limited to
+ helping computer programmers.</para>
<!-- ================================================================= -->
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 Thu Dec 21 00:01:49 2006
@@ -1,47 +1,43 @@
<preface id="svn.preface">
<title>Preface</title>
- <simplesect>
-
- <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>
- </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.
- </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>
-
- <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>
-
- </simplesect>
+ <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>
+ </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.
+ </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>
+
+ <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>
<!-- ================================================================= -->
@@ -85,6 +81,12 @@
and a special appendix summarizes most 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
+ compiler incantations, they are intended to illustrate a
+ particular scenario, not necessarily serve as examples of good
+ programming style or practices.</para>
+
</sect1>
<!-- ================================================================= -->
@@ -224,12 +226,6 @@
</warning>
</sect2>
- <para>Note that the source code examples are just
- that—examples. While they will compile with the proper
- compiler incantations, they are intended to illustrate the
- problem at hand, not necessarily serve as examples of good
- programming style.</para>
-
</sect1>
<!-- ================================================================= -->
Modified: branches/ora-2e-reorg/src/en/book/ch-reference.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-reference.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-reference.xml Thu Dec 21 00:01:49 2006
@@ -1,14 +1,13 @@
<chapter id="svn.ref">
<title>Subversion Complete Reference</title>
- <simplesect>
- <para>This chapter is intended to be a complete reference to using
- Subversion. This includes the command line client
- (<command>svn</command>) and all its subcommands, as well as the
- repository administration programs (<command>svnadmin</command>
- and <command>svnlook</command>) and their respective
- subcommands.</para>
- </simplesect>
+ <para>This chapter is intended to be a complete reference to using
+ Subversion. This includes the command line client
+ (<command>svn</command>) and all its subcommands, as well as the
+ repository administration programs (<command>svnadmin</command>
+ and <command>svnlook</command>) and their respective
+ subcommands.</para>
+
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -4481,7 +4480,7 @@
<refentry id="svn.ref.svnadmin.c.help">
<refnamediv>
- <refname>svnadmin help</refname>
+ <refname>svnadmin help</refname> <refpurpose>Help!</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
@@ -5410,7 +5409,7 @@
<refentry id="svn.ref.svnlook.c.help">
<refnamediv>
- <refname>svnlook help</refname>
+ <refname>svnlook help</refname> <refpurpose>Help!</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
Modified: branches/ora-2e-reorg/src/en/book/ch-repository-admin.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-repository-admin.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-repository-admin.xml Thu Dec 21 00:01:49 2006
@@ -1,40 +1,37 @@
<chapter id="svn.reposadmin">
<title>Repository Administration</title>
- <simplesect>
+ <para>### TODO: Heavy (re-)construction will be happenin' here! ###</para>
- <para>### TODO: Heavy (re-)construction will be happenin' here! ###</para>
+ <para>The Subversion repository is the central storehouse of
+ versioned data for any number of projects. As such, it becomes
+ an obvious candidate for all the love and attention an
+ administrator can offer. While the repository is generally a
+ low-maintenance item, it is important to understand how to
+ properly configure and care for it so that potential problems
+ are avoided, and actual problems are safely resolved.</para>
+
+ <para>In this chapter, we'll discuss how to create and configure
+ a Subversion repository. We'll also talk about repository
+ maintenance, including the use of the <command>svnlook</command>
+ and <command>svnadmin</command> tools (which are provided with
+ Subversion). We'll address some common questions and mistakes,
+ and give some suggestions on how to arrange the data in the
+ repository.</para>
+
+ <para>If you plan to access a Subversion repository only in the
+ role of a user whose data is under version control (that is, via
+ a Subversion client), you can skip this chapter altogether.
+ However, if you are, or wish to become, a Subversion repository
+ administrator,
+ <footnote>
+ <para>This may sound really prestigious and lofty, but we're
+ just talking about anyone who is interested in that
+ mysterious realm beyond the working copy where everyone's
+ data hangs out.</para>
+ </footnote>
+ you should definitely pay attention to this chapter.</para>
- <para>The Subversion repository is the central storehouse of
- versioned data for any number of projects. As such, it becomes
- an obvious candidate for all the love and attention an
- administrator can offer. While the repository is generally a
- low-maintenance item, it is important to understand how to
- properly configure and care for it so that potential problems
- are avoided, and actual problems are safely resolved.</para>
-
- <para>In this chapter, we'll discuss how to create and configure
- a Subversion repository. We'll also talk about repository
- maintenance, including the use of the <command>svnlook</command>
- and <command>svnadmin</command> tools (which are provided with
- Subversion). We'll address some common questions and mistakes,
- and give some suggestions on how to arrange the data in the
- repository.</para>
-
- <para>If you plan to access a Subversion repository only in the
- role of a user whose data is under version control (that is, via
- a Subversion client), you can skip this chapter altogether.
- However, if you are, or wish to become, a Subversion repository
- administrator,
- <footnote>
- <para>This may sound really prestigious and lofty, but we're
- just talking about anyone who is interested in that
- mysterious realm beyond the working copy where everyone's
- data hangs out.</para>
- </footnote>
- you should definitely pay attention to this chapter.</para>
-
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
Modified: branches/ora-2e-reorg/src/en/book/ch-server-configuration.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-server-configuration.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-server-configuration.xml Thu Dec 21 00:01:49 2006
@@ -1,25 +1,21 @@
<chapter id="svn.serverconfig">
<title>Server Configuration</title>
- <simplesect>
+ <para>A Subversion repository can be accessed simultaneously by
+ clients running on the same machine on which the repository
+ resides using the <literal>file:///</literal> method. But the
+ typical Subversion setup involves a single server machine being
+ accessed from clients on computers all over the office—or,
+ perhaps, all over the world.</para>
+
+ <para>This section describes how to get your Subversion repository
+ exposed outside its host machine for use by remote clients. We
+ will cover Subversion's currently available server mechanisms,
+ discussing the configuration and use of each. After reading
+ this section, you should be able to decide which networking
+ setup is right for your needs, and understand how to enable such
+ a setup on your host computer.</para>
- <para>A Subversion repository can be accessed simultaneously by
- clients running on the same machine on which the repository
- resides using the <literal>file:///</literal> method. But the
- typical Subversion setup involves a single server machine being
- accessed from clients on computers all over the office—or,
- perhaps, all over the world.</para>
-
-
- <para>This section describes how to get your Subversion repository
- exposed outside its host machine for use by remote clients. We
- will cover Subversion's currently available server mechanisms,
- discussing the configuration and use of each. After reading
- this section, you should be able to decide which networking
- setup is right for your needs, and understand how to enable such
- a setup on your host computer.</para>
-
- </simplesect>
<!-- ================================================================= -->
<!-- ================================================================= -->
@@ -538,12 +534,11 @@
<emphasis>absolute</emphasis> path in the repository URL. For
example, if a repository is located at
<filename>/usr/local/repositories/project1</filename>, then a
- client would reach it via <systemitem
- class="url">svn://host.example.com/usr/local/repositories/project1
- </systemitem>. To increase security, you can pass the
- <option>-r</option> option to <command>svnserve</command>,
- which restricts it to exporting only repositories below that
- path:</para>
+ client would reach it via
+ <uri>svn://host.example.com/usr/local/repositories/project1</uri>.
+ To increase security, you can pass the <option>-r</option>
+ option to <command>svnserve</command>, which restricts it to
+ exporting only repositories below that path:</para>
<screen>
$ svnserve -d -r /usr/local/repositories
@@ -1191,10 +1186,8 @@
common parent directory. For example, if you know you will be
creating multiple Subversion repositories in a directory
<filename>/usr/local/svn</filename> that would be accessed via
- URLs like <systemitem
- class="url">http://my.server.com/svn/repos1</systemitem>,
- <systemitem
- class="url">http://my.server.com/svn/repos2</systemitem>, and
+ URLs like <uri>http://my.server.com/svn/repos1</uri>,
+ <uri>http://my.server.com/svn/repos2</uri>, and
so on, you could use the <filename>httpd.conf</filename>
configuration syntax in the following example:</para>
Modified: branches/ora-2e-reorg/src/en/book/copyright.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/copyright.xml (original)
+++ branches/ora-2e-reorg/src/en/book/copyright.xml Thu Dec 21 00:01:49 2006
@@ -1,8 +1,7 @@
<appendix id="svn.copyright">
<title>Copyright</title>
- <simplesect>
- <programlisting>
+ <programlisting>
Copyright (c) 2002-2006
Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato.
@@ -301,7 +300,7 @@
====================================================================
</programlisting>
- </simplesect>
+
</appendix>
<!--
Modified: branches/ora-2e-reorg/src/en/book/foreword.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/foreword.xml (original)
+++ branches/ora-2e-reorg/src/en/book/foreword.xml Thu Dec 21 00:01:49 2006
@@ -4,125 +4,124 @@
ch00.xml. -->
<preface id="svn.foreword">
- <title>Foreword</title>
- <simplesect>
+ <prefaceinfo>
+ <author>
+ <firstname>Karl</firstname>
+ <surname>Fogel</surname>
+ </author>
+ <pubdate>Chicago, March 14, 2004</pubdate>
+ </prefaceinfo>
+
+ <title>Foreword</title>
- <para>A bad Frequently Asked Questions (FAQ) sheet is one that is
- composed not of the questions people actually asked, but of the
- questions the FAQ's author <emphasis>wished</emphasis> people
- had asked. Perhaps you've seen the type before:</para>
-
- <blockquote>
- <para>Q: How can I use Glorbosoft XYZ to maximize team
- productivity?</para>
- </blockquote>
-
- <blockquote>
- <para>A: Many of our customers want to know how they can
- maximize productivity through our patented office groupware
- innovations. The answer is simple: first, click on the
- <quote><literal>File</literal></quote> menu, scroll down to
- <quote><literal>Increase Productivity</literal></quote>,
- then…</para>
- </blockquote>
-
- <para>The problem with such FAQs is that they are not, in a
- literal sense, FAQs at all. No one ever called the tech support
- line and asked, <quote>How can we maximize
- productivity?</quote>. Rather, people asked highly specific
- questions, like, <quote>How can we change the calendaring system
- to send reminders two days in advance instead of one?</quote>
- and so on. But it's a lot easier to make up imaginary
- Frequently Asked Questions than it is to discover the real ones.
- Compiling a true FAQ sheet requires a sustained, organized
- effort: over the lifetime of the software, incoming questions
- must be tracked, responses monitored, and all gathered into a
- coherent, searchable whole that reflects the collective
- experience of users in the wild. It calls for the patient,
- observant attitude of a field naturalist. No grand
- hypothesizing, no visionary pronouncements here—open eyes
- and accurate note-taking are what's needed most.</para>
-
- <para>What I love about this book is that it grew out of just such
- a process, and shows it on every page. It is the direct result
- of the authors' encounters with users. It began with Ben
- Collins-Sussman's observation that people were asking the same
- basic questions over and over on the Subversion mailing lists:
- What are the standard workflows to use with Subversion? Do
- branches and tags work the same way as in other version control
- systems? How can I find out who made a particular change?</para>
-
- <para>Frustrated at seeing the same questions day after day, Ben
- worked intensely over a month in the summer of 2002 to write
- <citetitle>The Subversion Handbook</citetitle>, a sixty page
- manual that covered all the basics of using Subversion. The
- manual made no pretense of being complete, but it was
- distributed with Subversion and got users over that initial hump
- in the learning curve. When O'Reilly and Associates decided to
- publish a full-length Subversion book, the path of least
- resistance was obvious: just expand the Subversion
- handbook.</para>
-
- <para>The three co-authors of the new book were thus presented
- with an unusual opportunity. Officially, their task was to
- write a book top-down, starting from a table of contents and an
- initial draft. But they also had access to a steady
- stream—indeed, an uncontrollable geyser—of bottom-up
- source material. Subversion was already in the hands of
- thousands of early adopters, and those users were giving tons of
- feedback, not only about Subversion, but about its existing
- documentation.</para>
-
- <para>During the entire time they wrote this book, Ben, Mike, and
- Brian haunted the Subversion mailing lists and chat rooms
- incessantly, carefully noting the problems users were having in
- real-life situations. Monitoring such feedback is part of their
- job descriptions at CollabNet anyway, and it gave them a huge
- advantage when they set out to document Subversion. The book
- they produced is grounded firmly in the bedrock of experience,
- not in the shifting sands of wishful thinking; it combines the
- best aspects of user manual and FAQ sheet. This duality might
- not be noticeable on a first reading. Taken in order, front to
- back, the book is simply a straightforward description of a
- piece of software. There's the overview, the obligatory guided
- tour, the chapter on administrative configuration, some advanced
- topics, and of course a command reference and troubleshooting
- guide. Only when you come back to it later, seeking the
- solution to some specific problem, does its authenticity shine
- out: the telling details that can only result from encounters
- with the unexpected, the examples honed from genuine use cases,
- and most of all the sensitivity to the user's needs and the
- user's point of view.</para>
-
- <para>Of course, no one can promise that this book will answer
- every question you have about Subversion. Sometimes, the
- precision with which it anticipates your questions will seem
- eerily telepathic; yet occasionally, you will stumble into a
- hole in the community's knowledge, and come away empty-handed.
- When this happens, the best thing you can do is email
- <email>users at subversion.tigris.org</email> and present your
- problem. The authors are still there, still watching, and they
- include not just the three listed on the cover, but many others
- who contributed corrections and original material. From the
- community's point of view, solving your problem is merely a
- pleasant side effect of a much larger project—namely,
- slowly adjusting this book, and ultimately Subversion itself, to
- more closely match the way people actually use it. They are
- eager to hear from you not merely because they can help you, but
- because you can help them. With Subversion as with all active
- free software projects, <emphasis>you are not
- alone</emphasis>.</para>
-
- <para>Let this book be your first companion.</para>
-
- <para>—
- <author>
- <firstname>Karl</firstname>
- <surname>Fogel</surname>
- </author>, Chicago, 14 March, 2004</para>
+ <para>A bad Frequently Asked Questions (FAQ) sheet is one that is
+ composed not of the questions people actually asked, but of the
+ questions the FAQ's author <emphasis>wished</emphasis> people
+ had asked. Perhaps you've seen the type before:</para>
+
+ <blockquote>
+ <para>Q: How can I use Glorbosoft XYZ to maximize team
+ productivity?</para>
+ </blockquote>
+
+ <blockquote>
+ <para>A: Many of our customers want to know how they can
+ maximize productivity through our patented office groupware
+ innovations. The answer is simple: first, click on the
+ <quote><literal>File</literal></quote> menu, scroll down to
+ <quote><literal>Increase Productivity</literal></quote>,
+ then…</para>
+ </blockquote>
+
+ <para>The problem with such FAQs is that they are not, in a
+ literal sense, FAQs at all. No one ever called the tech support
+ line and asked, <quote>How can we maximize
+ productivity?</quote>. Rather, people asked highly specific
+ questions, like, <quote>How can we change the calendaring system
+ to send reminders two days in advance instead of one?</quote>
+ and so on. But it's a lot easier to make up imaginary
+ Frequently Asked Questions than it is to discover the real ones.
+ Compiling a true FAQ sheet requires a sustained, organized
+ effort: over the lifetime of the software, incoming questions
+ must be tracked, responses monitored, and all gathered into a
+ coherent, searchable whole that reflects the collective
+ experience of users in the wild. It calls for the patient,
+ observant attitude of a field naturalist. No grand
+ hypothesizing, no visionary pronouncements here—open eyes
+ and accurate note-taking are what's needed most.</para>
+
+ <para>What I love about this book is that it grew out of just such
+ a process, and shows it on every page. It is the direct result
+ of the authors' encounters with users. It began with Ben
+ Collins-Sussman's observation that people were asking the same
+ basic questions over and over on the Subversion mailing lists:
+ What are the standard workflows to use with Subversion? Do
+ branches and tags work the same way as in other version control
+ systems? How can I find out who made a particular change?</para>
+
+ <para>Frustrated at seeing the same questions day after day, Ben
+ worked intensely over a month in the summer of 2002 to write
+ <citetitle>The Subversion Handbook</citetitle>, a sixty page
+ manual that covered all the basics of using Subversion. The
+ manual made no pretense of being complete, but it was
+ distributed with Subversion and got users over that initial hump
+ in the learning curve. When O'Reilly and Associates decided to
+ publish a full-length Subversion book, the path of least
+ resistance was obvious: just expand the Subversion
+ handbook.</para>
+
+ <para>The three co-authors of the new book were thus presented
+ with an unusual opportunity. Officially, their task was to
+ write a book top-down, starting from a table of contents and an
+ initial draft. But they also had access to a steady
+ stream—indeed, an uncontrollable geyser—of bottom-up
+ source material. Subversion was already in the hands of
+ thousands of early adopters, and those users were giving tons of
+ feedback, not only about Subversion, but about its existing
+ documentation.</para>
+
+ <para>During the entire time they wrote this book, Ben, Mike, and
+ Brian haunted the Subversion mailing lists and chat rooms
+ incessantly, carefully noting the problems users were having in
+ real-life situations. Monitoring such feedback is part of their
+ job descriptions at CollabNet anyway, and it gave them a huge
+ advantage when they set out to document Subversion. The book
+ they produced is grounded firmly in the bedrock of experience,
+ not in the shifting sands of wishful thinking; it combines the
+ best aspects of user manual and FAQ sheet. This duality might
+ not be noticeable on a first reading. Taken in order, front to
+ back, the book is simply a straightforward description of a
+ piece of software. There's the overview, the obligatory guided
+ tour, the chapter on administrative configuration, some advanced
+ topics, and of course a command reference and troubleshooting
+ guide. Only when you come back to it later, seeking the
+ solution to some specific problem, does its authenticity shine
+ out: the telling details that can only result from encounters
+ with the unexpected, the examples honed from genuine use cases,
+ and most of all the sensitivity to the user's needs and the
+ user's point of view.</para>
+
+ <para>Of course, no one can promise that this book will answer
+ every question you have about Subversion. Sometimes, the
+ precision with which it anticipates your questions will seem
+ eerily telepathic; yet occasionally, you will stumble into a
+ hole in the community's knowledge, and come away empty-handed.
+ When this happens, the best thing you can do is email
+ <email>users at subversion.tigris.org</email> and present your
+ problem. The authors are still there, still watching, and they
+ include not just the three listed on the cover, but many others
+ who contributed corrections and original material. From the
+ community's point of view, solving your problem is merely a
+ pleasant side effect of a much larger project—namely,
+ slowly adjusting this book, and ultimately Subversion itself, to
+ more closely match the way people actually use it. They are
+ eager to hear from you not merely because they can help you, but
+ because you can help them. With Subversion as with all active
+ free software projects, <emphasis>you are not
+ alone</emphasis>.</para>
- </simplesect>
+ <para>Let this book be your first companion.</para>
</preface>
Modified: branches/ora-2e-reorg/src/en/book/styles.css
==============================================================================
--- branches/ora-2e-reorg/src/en/book/styles.css (original)
+++ branches/ora-2e-reorg/src/en/book/styles.css Thu Dec 21 00:01:49 2006
@@ -142,14 +142,20 @@
font-size: 100% !important;
}
-.author
+.author, .pubdate
{
+ margin: 0;
font-size: 100%;
font-style: italic;
font-weight: normal;
color: black;
}
+.preface div.author, .preface .pubdate
+{
+ font-size: 80%;
+}
+
.sidebar
{
border-top: dotted 1px black;
Modified: branches/ora-2e-reorg/src/tools/Makefile.base-rules
==============================================================================
--- branches/ora-2e-reorg/src/tools/Makefile.base-rules (original)
+++ branches/ora-2e-reorg/src/tools/Makefile.base-rules Thu Dec 21 00:01:49 2006
@@ -9,11 +9,15 @@
$(VERSION_SOURCE): version
version:
@if $(SVNVERSION) . > /dev/null; then \
- echo '<!ENTITY svn.version "$(L10N_REVISION) '`$(SVNVERSION) .`'">' \
+ echo '<!ENTITY svn.version "'`$(SVNVERSION) .`'">' \
> $(VERSION_SOURCE).tmp; \
+ echo '<!ENTITY svn.l10n_revision "$(L10N_REVISION)">' \
+ >> $(VERSION_SOURCE).tmp; \
else \
echo '<!ENTITY svn.version "">' > $(VERSION_SOURCE).tmp; \
+ echo '<!ENTITY svn.l10n_revision "">' > $(VERSION_SOURCE).tmp; \
fi
+ @echo '<!ENTITY svn.date "'`date`'">' >> $(VERSION_SOURCE).tmp
@if cmp -s $(VERSION_SOURCE) $(VERSION_SOURCE).tmp; then \
rm $(VERSION_SOURCE).tmp; \
else \
More information about the svnbook-dev
mailing list