Rev 4171: Copy-edits to developer docs (Eric Siegerman) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri Mar 20 02:55:38 GMT 2009
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 4171
revision-id: pqm at pqm.ubuntu.com-20090320025535-havsm27xdtwnpl42
parent: pqm at pqm.ubuntu.com-20090319192139-7y3mlqumxy7aqtdh
parent: ian.clatworthy at canonical.com-20090320020823-1dxuhd9mvqgs7a3u
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2009-03-20 02:55:35 +0000
message:
Copy-edits to developer docs (Eric Siegerman)
modified:
doc/developers/overview.txt overview.txt-20080904022501-ww2ggomrs5elxfm0-1
------------------------------------------------------------
revno: 4170.1.1
revision-id: ian.clatworthy at canonical.com-20090320020823-1dxuhd9mvqgs7a3u
parent: pqm at pqm.ubuntu.com-20090319192139-7y3mlqumxy7aqtdh
parent: pub08 at davor.org-20090313230934-q7u6xpzdxhs0ok0o
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: ianc-integration
timestamp: Fri 2009-03-20 12:08:23 +1000
message:
Copy-edits to developer docs (Eric Siegerman)
modified:
doc/developers/overview.txt overview.txt-20080904022501-ww2ggomrs5elxfm0-1
------------------------------------------------------------
revno: 4144.4.4
revision-id: pub08 at davor.org-20090313230934-q7u6xpzdxhs0ok0o
parent: pub08 at davor.org-20090313230728-49hvh19i3cwfr3ru
committer: Eric Siegerman <pub08 at davor.org>
branch nick: minor-doc-updates
timestamp: Fri 2009-03-13 19:09:34 -0400
message:
Line-wrap changed paragraphs.
modified:
doc/developers/overview.txt overview.txt-20080904022501-ww2ggomrs5elxfm0-1
------------------------------------------------------------
revno: 4144.4.3
revision-id: pub08 at davor.org-20090313230728-49hvh19i3cwfr3ru
parent: pub08 at davor.org-20090313220442-i3ucbvovfen22dlv
committer: Eric Siegerman <pub08 at davor.org>
branch nick: minor-doc-updates
timestamp: Fri 2009-03-13 19:07:28 -0400
message:
Copy editing.
modified:
doc/developers/overview.txt overview.txt-20080904022501-ww2ggomrs5elxfm0-1
------------------------------------------------------------
revno: 4144.4.2
revision-id: pub08 at davor.org-20090313220442-i3ucbvovfen22dlv
parent: pub08 at davor.org-20090313215738-byp22o9j7fubha2g
committer: Eric Siegerman <pub08 at davor.org>
branch nick: minor-doc-updates
timestamp: Fri 2009-03-13 18:04:42 -0400
message:
Uppercase acronyms.
modified:
doc/developers/overview.txt overview.txt-20080904022501-ww2ggomrs5elxfm0-1
------------------------------------------------------------
revno: 4144.4.1
revision-id: pub08 at davor.org-20090313215738-byp22o9j7fubha2g
parent: pqm at pqm.ubuntu.com-20090313062142-ndr3o27uwgysx9dv
committer: Eric Siegerman <pub08 at davor.org>
branch nick: minor-doc-updates
timestamp: Fri 2009-03-13 17:57:38 -0400
message:
Fix a couple of relative URLs (too many ../'s).
modified:
doc/developers/overview.txt overview.txt-20080904022501-ww2ggomrs5elxfm0-1
=== modified file 'doc/developers/overview.txt'
--- a/doc/developers/overview.txt 2009-03-19 04:54:59 +0000
+++ b/doc/developers/overview.txt 2009-03-20 02:08:23 +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
@@ -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.
More information about the bazaar-commits
mailing list