[MERGE] Copy-edit docs

Sat Mar 14 00:11:26 GMT 2009

My first merge attempt -- a trivial one to give me a feel for the
procedure.

This just does some copy-editing of doc/developers/overview.txt.
It is intended that it make *no* semantic changes.

Procedural question for doc edits:  Is it preferred that one
re-line-wrap the changed text (which makes it harder to review
the changes), or not (which leaves the final file in a messier
state)?

  - Eric
-------------- next part --------------
# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: pub08 at davor.org-20090313230934-q7u6xpzdxhs0ok0o
# target_branch: file:///home/erics/p/bzr/dev/1-local/eks-master/
# testament_sha1: 7c027ff5bceef2c0f8639a352ab41c5713593196
# timestamp: 2009-03-13 19:50:11 -0400
# message: Some copy editing of doc/developers/overview.txt.
# base_revision_id: pqm at pqm.ubuntu.com-20090313062142-ndr3o27uwgysx9dv
# 
# Begin patch
=== modified file 'doc/developers/overview.txt'

--- doc/developers/overview.txt	2008-09-04 05:35:16 +0000
+++ doc/developers/overview.txt	2009-03-13 23:09:34 +0000
@@ -3,12 +3,12 @@
 =============================
 
 This document describes the key classes and concepts within Bazaar.  It is
-intended to be useful to be useful to people working on the Bazaar
-codebase, or to people writing plugins.
+intended to be useful to people working on the Bazaar codebase, or to
+people writing plugins.
 
-If you have any questions or something seems to be incorrect, unclear or
-missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write to
-the Bazaar mailing list.  To propose a correction or addition to this
+If you have any questions, or if something seems to be incorrect, unclear
+or missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write
+to the Bazaar mailing list.  To propose a correction or addition to this
 document, send a merge request or new text to the mailing list.
 
 The current version of this document is available in the file
@@ -17,8 +17,8 @@
 
 See also:
 
- * `Bazaar Developer Documentation Catalog <../../developers/index.html>`_.
- * `Bazaar Developer Guide <../../en/developer-guide/HACKING.html>`_
+ * `Bazaar Developer Documentation Catalog <../developers/index.html>`_.
+ * `Bazaar Developer Guide <../en/developer-guide/HACKING.html>`_
    (particularly the *Coding Style Guidelines* section.)
 
 .. contents::
@@ -43,23 +43,23 @@
 #########
 
 The ``Transport`` layer handles access to local or remote directories.
-Each Transport object acts like a logical connection to a particular
+Each Transport object acts as a logical connection to a particular
 directory, and it allows various operations on files within it.  You can
 *clone* a transport to get a new Transport connected to a subdirectory or
 parent directory.
 
 Transports are not used for access to the working tree.  At present
 working trees are always local and they are accessed through the regular
-Python file io mechanisms.
+Python file I/O mechanisms.
 
 Filenames vs URLs
 =================
 
-Transports work in URLs.  Take note that URLs are by definition only
-ASCII - the decision of how to encode a Unicode string into a URL must be
-taken at a higher level, typically in the Store.  (Note that Stores also
-escape filenames which cannot be safely stored on all filesystems, but
-this is a different level.)
+Transports work in terms of URLs.  Take note that URLs are by definition
+only ASCII - the decision of how to encode a Unicode string into a URL
+must be taken at a higher level, typically in the Store.  (Note that
+Stores also escape filenames which cannot be safely stored on all
+filesystems, but this is a different level.)
 
 The main reason for this is that it's not possible to safely roundtrip a
 URL into Unicode and then back into the same URL.  The URL standard
@@ -67,26 +67,27 @@
 doesn't say how those bytes represent non-ASCII characters.  (They're not
 guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
 
-For example if the user enters the url ``http://example/%e0`` there's no
+For example, if the user enters the URL ``http://example/%e0``, there's no
 way to tell whether that character represents "latin small letter a with
-grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
-or malformed UTF-8.  So we can't convert their URL to Unicode reliably.
-
-Equally problematic if we're given a url-like string containing non-ascii
-characters (such as the accented a) we can't be sure how to convert that
-to the correct URL, because we don't know what encoding the server expects
-for those characters.  (Although this is not totally reliable we might still
-accept these and assume they should be put into UTF-8.)
-
-A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
+grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2,
+or malformed UTF-8.  So we can't convert the URL to Unicode reliably.
+
+Equally problematic is if we're given a URL-like string containing
+(unescaped) non-ASCII characters (such as the accented a).  We can't be
+sure how to convert that to a valid (i.e. ASCII-only) URL, because we
+don't know what encoding the server expects for those characters.
+(Although it is not totally reliable, we might still accept these and
+assume that they should be put into UTF-8.)
+
+A similar edge case is that the URL ``http://foo/sweet%2Fsour`` contains
 one directory component whose name is "sweet/sour".  The escaped slash is
-not a directory separator.  If we try to convert URLs to regular Unicode
-paths this information will be lost.
+not a directory separator, but if we try to convert the URL to a regular
+Unicode path, this information will be lost.
 
-This implies that Transports must natively deal with URLs; for simplicity
-they *only* deal with URLs and conversion of other strings to URLs is done
-elsewhere.  Information they return, such as from ``list_dir``, is also in
-the form of URL components.
+This implies that Transports must natively deal with URLs.  For simplicity
+they *only* deal with URLs; conversion of other strings to URLs is done
+elsewhere.  Information that Transports return, such as from ``list_dir``,
+is also in the form of URL components.
 
 
 Repository
@@ -98,25 +99,25 @@
 Stacked Repositories
 ====================
 
-Repositories can be configured to refer to a list of "fallback"
+A repository can be configured to refer to a list of "fallback"
 repositories.  If a particular revision is not present in the original
 repository, it refers the query to the fallbacks.
 
 Compression deltas don't span physical repository boundaries.  So the
-first commit to a new empty repository with fallback repositories will
+first commit to a new, empty repository with fallback repositories will
 store a full text of the inventory, and of every new file text.
 
 At runtime, repository stacking is actually configured by the branch, not
 the repository.  So doing ``a_bzrdir.open_repository()`` 
 gets you just the single physical repository, while 
 ``a_bzrdir.open_branch().repository`` gets one configured with a stacking. 
-Therefore to permanently change the fallback repository stored on disk,
+Therefore, to permanently change the fallback repository stored on disk,
 you must use ``Branch.set_stacked_on_url``.  
 
-Changing away from an existing stacked on url will copy across any
+Changing away from an existing stacked-on URL will copy across any
 necessary history so that the repository remains usable.
 
-A repository opened from an hpss server is never stacked on the server
+A repository opened from an HPSS server is never stacked on the server
 side, because this could cause complexity or security problems with the
 server acting as a proxy for the client.  Instead, the branch on the
 server exposes the stacked-on URL and the client can open that.

# Begin bundle
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
JFOFCQAKem3A
