← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/overview.txt

  • Committer: Eric Siegerman
  • Date: 2009-03-13 23:09:34 UTC
  • mto: (4170.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 4171.
  • Revision ID: pub08@davor.org-20090313230934-q7u6xpzdxhs0ok0o
Line-wrap changed paragraphs.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/overview.txt
3
3
=============================
4
4
 
5
5
This document describes the key classes and concepts within Bazaar.  It is
6
 
intended to be useful to people working on the Bazaar
7
 
codebase, or to people writing plugins.
 
6
intended to be useful to people working on the Bazaar codebase, or to
 
7
people writing plugins.
8
8
 
9
 
If you have any questions, or if something seems to be incorrect, unclear or
10
 
missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write to
11
 
the Bazaar mailing list.  To propose a correction or addition to this
 
9
If you have any questions, or if something seems to be incorrect, unclear
 
10
or missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write
 
11
to the Bazaar mailing list.  To propose a correction or addition to this
12
12
document, send a merge request or new text to the mailing list.
13
13
 
14
14
The current version of this document is available in the file
55
55
Filenames vs URLs
56
56
=================
57
57
 
58
 
Transports work in terms of URLs.  Take note that URLs are by definition only
59
 
ASCII - the decision of how to encode a Unicode string into a URL must be
60
 
taken at a higher level, typically in the Store.  (Note that Stores also
61
 
escape filenames which cannot be safely stored on all filesystems, but
62
 
this is a different level.)
 
58
Transports work in terms of URLs.  Take note that URLs are by definition
 
59
only ASCII - the decision of how to encode a Unicode string into a URL
 
60
must be taken at a higher level, typically in the Store.  (Note that
 
61
Stores also escape filenames which cannot be safely stored on all
 
62
filesystems, but this is a different level.)
63
63
 
64
64
The main reason for this is that it's not possible to safely roundtrip a
65
65
URL into Unicode and then back into the same URL.  The URL standard
72
72
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2,
73
73
or malformed UTF-8.  So we can't convert the URL to Unicode reliably.
74
74
 
75
 
Equally problematic is if we're given a URL-like string containing (unescaped) non-ASCII
76
 
characters (such as the accented a).  We can't be sure how to convert that
77
 
to a valid (i.e. ASCII-only) URL, because we don't know what encoding the server expects
78
 
for those characters.  (Although it is not totally reliable, we might still
79
 
accept these and assume that they should be put into UTF-8.)
 
75
Equally problematic is if we're given a URL-like string containing
 
76
(unescaped) non-ASCII characters (such as the accented a).  We can't be
 
77
sure how to convert that to a valid (i.e. ASCII-only) URL, because we
 
78
don't know what encoding the server expects for those characters.
 
79
(Although it is not totally reliable, we might still accept these and
 
80
assume that they should be put into UTF-8.)
80
81
 
81
82
A similar edge case is that the URL ``http://foo/sweet%2Fsour`` contains
82
83
one directory component whose name is "sweet/sour".  The escaped slash is
83
 
not a directory separator, but if we try to convert the URL to a regular Unicode
84
 
path, this information will be lost.
 
84
not a directory separator, but if we try to convert the URL to a regular
 
85
Unicode path, this information will be lost.
85
86
 
86
87
This implies that Transports must natively deal with URLs.  For simplicity
87
88
they *only* deal with URLs; conversion of other strings to URLs is done
88
 
elsewhere.  Information that Transports return, such as from ``list_dir``, is also in
89
 
the form of URL components.
 
89
elsewhere.  Information that Transports return, such as from ``list_dir``,
 
90
is also in the form of URL components.
90
91
 
91
92
 
92
93
Repository