diff docs/obs-concept.rst @ 357:b398e9c2dbd1 stable

doc: English proofreading

--- a/docs/obs-concept.rst	Fri Jul 06 18:43:25 2012 +0200
+++ b/docs/obs-concept.rst	Wed Jul 11 13:59:06 2012 -0400
@@ -2,9 +2,10 @@
 Why Do We Need a New Concept
 -----------------------------------------------------------
 
-Current DVCS are great tools to forge a series of flawless changeset on your own.
-But they perform poorly when it comes to **sharing** some work in progress and
-**collaborating** on such work in progress.
+Current DVCSes are great tools for forging a series of flawless
+changesets on your own. But they perform poorly when it comes to
+**sharing** some work in progress and **collaborating** on such work
+in progress.
 
 When people forge a new version of a changeset they actually create a
 new changeset and get rid of the original changeset. Difficulties to
@@ -18,14 +19,14 @@
 your repository is *visible* and *meaningful*. To delete old
 (rewritten) changesets, mercurial removes them from the repository
 storage with an operation called *strip*. After the *stripping*, the
-repository looks like if the changeset never existed.
+repository looks as if the changeset never existed.
 
 This approach is simple and effective except for one big
 drawback: you can remove changesets from **your repository only**. If
 a stripped changeset exists in another repository it touches, it will
 show up again. This is because a shared changeset becomes
 part of a shared global history. Stripping a changeset from all
-repositories is at best impractical and in most case impossible!
+repositories is at best impractical and in most case impossible.
 
 As consequence, **you can not rewrite something once you exchange it with
 others**. The old version will still exist along side the new one [#]_.
@@ -40,7 +41,9 @@
 interaction with the outer world, which is very unfortunate for a
 *Distributed* VCS.
 
-.. [#] various work around exists but they require their own workflows which are distinct from the very elegant basic workflow of Mercurial.
+.. [#] various work around exists but they require their own workflows
+   which are distinct from the very elegant basic workflow of
+   Mercurial.
 
 Git Approach: Overwrite Reference
 -----------------------------------------------------
@@ -68,20 +71,21 @@
 
 This approach goes a bit further but still has a major drawback:
 
-Because you **overwrite** the git-branch, you have no conflict resolution. The last
-to act wins. This makes collaboration on multiple changesets difficult because
-you can't merge concurrent updates on a changeset.
+Because you **overwrite** the git-branch, you have no conflict
+resolution. The last to act wins. This makes collaboration on multiple
+changesets difficult because you can't merge concurrent updates on a
+changeset.
 
-Every overwrite is a forced operation where the operator says "Yes I want this to
-replace that. In highly distributed environments, a user may end up with conflicting
-references and no proper way to choose.
+Every overwrite is a forced operation where the operator says, "yes I
+want this to replace that". In highly distributed environments, a user
+may end up with conflicting references and no proper way to choose.
 
 Because of this way to visualize a repository, git-branches are a core
 part of git, which makes the user interface more complicated and
 constrains moving through history.
 
-Finally, even if all older changesets still exist in the repository, accesing them
-is still painful.
+Finally, even if all older changesets still exist in the repository,
+accesing them is still painful.
 
 
 -----------------------------------------------------
@@ -89,9 +93,9 @@
 -----------------------------------------------------
 
 
-As None of the concepts was powerful enough to fulfill the need of safely
-rewriting history, including easy sharing and collaborating on mutable history,
-we needed another one. 
+As none of the concepts was powerful enough to fulfill the need of
+safely rewriting history, including easy sharing and collaboration on
+mutable history, we needed another one.
 
 Basic concept
 -----------------------------------------------------
@@ -146,8 +150,9 @@
 Basic Usage
 -----------------------------------------------------
 
-Obsolete markers create a perpendicular history: **a versioned changeset graph**. This means that offers the same features we have for
-versioned files but applied to changeset:
+Obsolete markers create a perpendicular history: **a versioned
+changeset graph**. This means that offers the same features we have
+for versioned files but applied to changeset:
 
 First: we can display a **coherent view** of the history graph in which only a
 single version of your changesets is displayed by the UI.
@@ -195,9 +200,9 @@
 
     Rebasing `B` and `C` on `A` (as `B'`, `C'`)
 
-    This rebase operation added two obsolete markers from new changesets to old
-    changesets. These two old changesets are now part of the *obsolete* part of the
-    history.
+    This rebase operation added two obsolete markers from new
+    changesets to old changesets. These two old changesets are now
+    part of the *obsolete* part of the history.
 
 In most cases, the obsolete set will be fully hidden to both the UI and
 discovery, hence users do not have to care about them unless they want to
@@ -206,9 +211,9 @@
 Unstable changesets
 ```````````````````
 
-While exploring the possibilities of the obsolete marker a bit further, you may end up with
-*obsolete* changesets which have *non-obsolete* children. There is two common ways to
-achieve this:
+While exploring the possibilities of the obsolete marker a bit
+further, you may end up with *obsolete* changesets which have
+*non-obsolete* children. There is two common ways to achieve this:
 
 * Pull a changeset based of an old version of a changeset [#]_.
 
@@ -221,17 +226,18 @@
 
     Amend `A` into `A'` leaving `B` behind.
 
-    In this situation we can not consider `B` as *obsolete*.  But we have all
-    necessary data to detect `B` as an *unstable* branch of the history because
-    its parent `A` is *obsolete*. In addition, we have enough data to
-    automatically resolve this instability: we know that the new version of `B`
-    parent (`A`) is `A'`, We can deduce that we should rebase `B` on `A'` to get
-    a stable history again.
+    In this situation we cannot consider `B` as *obsolete*. But we
+    have all the necessary data to detect `B` as an *unstable* branch
+    of the history because its parent `A` is *obsolete*. In addition,
+    we have enough data to automatically resolve this instability: we
+    know that the new version of `B` parent (`A`) is `A'`. We can
+    deduce that we should rebase `B` on `A'` to get a stable history
+    again.
 
 Proper warnings should be issued when part of the history becomes
 unstable. The UI will be able to use the obsolete marker to
 automatically suggest a resolution to the user of even carry them out
-for him.
+for them.
 
 
 XXX details on automatic resolution for
@@ -266,10 +272,10 @@
     `B` is *unstable* as before.
 
 
-Because nothing outside the obsolete set default on *extinct* changesets, they
-can be safely hidden in the UI and even garbage collected. *Suspended* changesets
-have to stay visible and available until their unstable descendant are rewritten
-into stable version.
+Because nothing outside the obsolete set default on *extinct*
+changesets, they can be safely hidden in the UI and even garbage
+collected. *Suspended* changesets have to stay visible and available
+until their unstable descendant are rewritten into stable version.
 
 
 Conflicting rewrites
@@ -300,20 +306,21 @@
 Reliable history
 ``````````````````````
 
-Obsolete marker help to smooth rewriting operation process. However they
-do not change the fact that **you should only rewrite the mutable part of the
-history**. The phase concept enforces this rule by explicitly defining a
-public immutable set of changesets. Rewriting operations refuse to work on
-public changesets, but there are still some corner cases where previously rewritten changesets
-are made public.
+Obsolete markers help to smooth rewriting operation process. However
+they do not change the fact that **you should only rewrite the mutable
+part of the history**. The phase concept enforces this rule by
+explicitly defining a public immutable set of changesets. Rewriting
+operations refuse to work on public changesets, but there are still
+some corner cases where previously rewritten changesets are made
+public.
 
 Special rules apply for obsolete markers pointing to public changesets:
 
 * Public changesets are excluded from the obsolete set (public
   changesets are never hidden or candidate to garbage collection)
 
-* *newer* version of a public changeset are called **latecomer** and highlighted as
-  an error case.
+* *newer* version of a public changeset are called **latecomer** and
+  highlighted as an error case.
 
 Solving such an error is easy. Because we know what changeset a
 *latecomer* tries to rewrite, we can easily compute a smaller
@@ -343,7 +350,7 @@
 
 - gracefully handling history rewriting conflicts,
 
-- various history rewriting UI’s collaborating with an underlying common API.
+- various history rewriting UI's collaborating with an underlying common API.
 
 .. list-table:: Comparison on solution [#]_
    :header-rows: 1