docs/obs-terms.rst
branchstable
changeset 368 c2f3cdd5a2a2
parent 363 5280e7ce026d
child 369 f348088d3b3f
--- a/docs/obs-terms.rst	Sun Jul 15 14:42:21 2012 +0200
+++ b/docs/obs-terms.rst	Sun Jul 15 16:19:02 2012 +0200
@@ -2,83 +2,83 @@
 Terminology of the obsolete concept
 -----------------------------------------------------------
 
-Obsolete marker them self
+Obsolete markers
 ---------------------------------
 
-The mutable concept is based on the creation of **obsolete marker**. An obsolete
-marker register a relation between the old obsoleted changeset and its newer
+The mutable concept is based on **obsolete markers**. Creating an obsolete
+marker registers a relation between an old obsoleted changeset and its newer
 version.
 
-The old changesets is called **precursors**. Its newer version are called
-*successors*. A marker always register a single *precursors* but can refer
-to:
+Old changesets are called **precursors** while their new versions are called
+**successors**. A marker always registers a single *precursor* to:
+
+- no *successor*: the *precursor* is just discarded.
+- one *successor*: the *precursor* has been rewritten
+- multiple *successors*: the *precursor* has been splitted in multiple
+  changesets.
 
-- No *successors* at all if the *precursors* if just discarded.
-- One *successor* at all if the *precursors* have been rewritten
-- Multiple *successors* if the *precursors* have been splitted in myltiple
-  changeset.
+.. The *precursors* and *successors* terms can be used on changeset directy:
 
-The **precursors** and **successors** terms can be used on changeset directy:
+.. :precursors: of a changeset `A` are changesets used as *precursors* by
+..              obsolete marker using changeset `A` as *successors*
 
-:precursors: of a changeset `A` are changesets used as *precursors* by
-             obsolete marker using changeset `A` as *successors*
-
-:successors: of a changeset `B` are changesets used as *successors* by
-             obsolete marker using changeset `B` as *precursors*
+.. :successors: of a changeset `B` are changesets used as *successors* by
+..              obsolete marker using changeset `B` as *precursors*
 
-*Precursors* and *successors* directly related within the same marker are called
-**direct precursors** and **direct successors** in ambiguous situation.
+Chainning obsolete markers is allowed to rewrite a changeset that is already a
+*successor*. This is a kind of *second order version control*.
+To clarify ambiguous situtations one can use **direct precursors** or
+**direct successors** to name changesets that are directly related.
 
-The set of all *obsolete markers* create a direct acyclic graph the same way
-standard *parent* and *children* relation do. In this graph we have:
+The set of all **bsolete markers* forms a direct acyclic graph the same way
+standard *parents*/*children* relation does. In this graph we have:
 
-:any precursors: of a `A` are transitive precursors of `A`. (*direct
-                 precursors* of `A` and *precursors*  of *precursors*)
+:any precursors: are transitive precursors of a changeset: *direct precursors*
+                 and *precursors* of *precursors*.
 
-:any successors: of a `A` are transitive successors of `A`. (*direct
-                 successors* of `A` and *precursors*  of *precursors*)
+:any successors: are transitive successors of a changeset: *direct successors*
+                 and *precursors*  of *precursors*)
 
-Obsolete markers may revert to changesets that are not known locally. *Direct
-precursors* of a changeset may be unknown locally. This is why we usually focus
-on the **first known precursors**  of changeset
+Obsolete markers may refer changesets that are not known locally.
+So, *direct precursors* of a changeset may be unknown locally.
+This is why we usually focus on the **first known precursors**  of the rewritten
+changeset. The same apply for *successors*.
 
-(The same apply for successors)
-
-Item in *Any successors* which are not *obsolete* are called **newest
-successors** 
+Changeset in *any successors* which are not **precursor**[#] are called
+**newest successors**.
 
 .. note:: I'm not very happy with this naming scheme and I'm looking for a
-          better distinction between direct-successors, any-successors.
+          better distinction between *direct successors* and **any successors*.
 
 Possible changesets "type"
 ---------------------------------
 
-The following table describe name and behavior of changesets affected by
-obsolete marker. Left column describe generic category and right column are
-about sub-category.
+The following table describes names and behaviors of changesets affected by
+obsolete markers. Thge left column describes generic categories and the right
+columns are about sub-categories.
 
 
 +---------------------+--------------------------+-----------------------------+
 | **mutable**         | **obsolete**             | **extinct**                 |
 |                     |                          |                             |
-| Changeset in either | Obsolete changesets are  | Extinct changesets are      |
-| *draft* or *secret* | mutable changeset used   | obsolete one with obsolete  |
-| phases.             | as a precursors.         | only descendants.           |
+| Changeset in either | Obsolete changeset is    | *extinct* changeset is      |
+| *draft* or *secret* | *mutable* used as a      | *obsolete* which has only   |
+| phase.              | *precursor*.             | *obsolete* descendants.     |
 |                     |                          |                             |
-|                     | A changeset is used as   | They can be safely:         |
-|                     | a precursors when at     |                             |
+|                     | A changeset is used as   | They can safely be:         |
+|                     | a *precursor* when at    |                             |
 |                     | least one obsolete       | - hidden in the UI,         |
-|                     | refer to it in the       | - silently excluded from pp |
-|                     | precursors field.        |   pull and push,t operation |
-|                     |                          | - ignored by most operation |
-|                     |                          | - garbage collected.        |
+|                     | marker refers to it.     | - silently excluded from    |
+|                     |                          |   pull and push operations  |
+|                     |                          | - mostly ignored            |
+|                     |                          | - garbage collected         |
 |                     |                          |                             |
 |                     |                          +-----------------------------+
 |                     |                          |                             |
 |                     |                          | **suspended**               |
 |                     |                          |                             |
-|                     |                          | Suspended changesets are    |
-|                     |                          | obsolete one with at least  |
+|                     |                          | *suspended* changeset is    |
+|                     |                          | *obsolete* with at least    |
 |                     |                          | one non-obsolete descendant |
 |                     |                          |                             |
 |                     |                          | Thoses descendants prevent  |
@@ -91,54 +91,52 @@
 |                     |                          |                             |
 |                     | **troublesome**          | **unstable**                |
 |                     |                          |                             |
-|                     | Troublesome commit have  | Unstable changesets are     |
-|                     | unresolved issue caused  | changesets with obsolete    |
-|                     | by obsolete relations.   | ancestors.                  |
+|                     | *troublesome* has        | *unstable* is a changeset   |
+|                     | unresolved issue caused  | with obsolete ancestors.    |
+|                     | by *obsolete* relations. |                             |
 |                     |                          |                             |
-|                     | Possible issues are      | They must be rebased on a   |
-|                     | listed in the next       | better base to solve the    |
-|                     | column. It is possible   | situation.                  |
-|                     | for troublesome          |                             |
+|                     | Possible issues are      | It must be rebased on a     |
+|                     | listed in the next       | non *troublesome* base to   |
+|                     | column. It is possible   | solve the problem.          |
+|                     | for *troublesome*        |                             |
 |                     | changeset to combine     | (possible alternative name: |
 |                     | multiple issue at once.  | precarious)                 |
-|                     | (eg: conflicting and     |                             |
+|                     | (a.k.a. conflicting and  |                             |
 |                     | unstable)                +-----------------------------+
 |                     |                          |                             |
 |                     | (possible alternative    | **latecomer**               |
-|                     | name: unsettled,         |                             |
-|                     | troubled)                | Latecomer changesets are    |
-|                     |                          | changesets that try to      |
-|                     |                          | be successors of public     |
-|                     |                          | changesets.                 |
+|                     | names: unsettled,        |                             |
+|                     | troubled)                | *latecomer* is a changeset  |
+|                     |                          | that tries to be successor  |
+|                     |                          | of  public changesets.      |
 |                     |                          |                             |
 |                     |                          | Public changeset can't      |
-|                     |                          | be obsolete. Latecomer      |
-|                     |                          | changeset need to be        |
-|                     |                          | rewritten as an overlay     |
-|                     |                          | to this public changeset.   |
+|                     |                          | be *precursor*. *latecomer* |
+|                     |                          | need to be converted into   |
+|                     |                          | an overlay to this public   |
+|                     |                          | changeset.                  |
 |                     |                          |                             |
-|                     |                          | (possible alternative names |
+|                     |                          | (possible alternative names:|
 |                     |                          | mislead, naive, unaware,    |
 |                     |                          | mindless, disenchanting)    |
 |                     |                          |                             |
 |                     |                          +-----------------------------+
 |                     |                          | **conflicting**             |
 |                     |                          |                             |
-|                     |                          | Conflicting changesets      |
-|                     |                          | happen when multiple        |
+|                     |                          | *conflicting* is changeset  |
+|                     |                          | that appears when multiple  |
 |                     |                          | changesets are successors   |
-|                     |                          | of the same obsolete        |
-|                     |                          | changeset.                  |
+|                     |                          | of the same precursor.      |
 |                     |                          |                             |
-|                     |                          | Conflicting changesets are  |
-|                     |                          | resolve through a three     |
-|                     |                          | ways merging between the    |
-|                     |                          | two conflicting changesets, |
+|                     |                          | *conflicting* are solved    |
+|                     |                          | through a three ways merge  |
+|                     |                          | between the two             |
+|                     |                          | *conflictings*,             |
 |                     |                          | using the last "obsolete-   |
 |                     |                          | -common-ancestor" as the    |
 |                     |                          | base.                       |
 |                     |                          |                             |
-|                     |                          | (Changeset splitting is     |
+|                     |                          | (*splitting* is             |
 |                     |                          | properly not detected as a  |
 |                     |                          | conflict)                   |
 |                     |                          |                             |
@@ -163,14 +161,13 @@
 | Rewriting operation refuse to work on immutable changeset.                   |
 |                                                                              |
 | Obsolete markers that refer an immutable changeset as precursors have        |
-| no effect on the precussors changeset (but may have effect on the            |
-| successors)                                                                  |
+| no effect on the precussors but may have effect on the successors.           |
 |                                                                              |
-| When a mutable changeset becomes immutable its is just *immutable* and loose |
-| any property of it's former state.                                           |
+| When a *mutable* changeset becomes *immutable* (changing its phase from draft|
+| to public) it is just *immutable* and loose any property of it's former      |
+| state.                                                                       |
 |                                                                              |
-| By phase property, once a changeset becomes a public immutable changeset,    |
-| you can expect it to remain as such forever.                                 |
+| The phase properties says that public changesets stay as *immutable* forever.|
 |                                                                              |
 +------------------------------------------------------------------------------+
 
@@ -190,60 +187,58 @@
 Existing terms
 ``````````````
 
-Mercurial already use the following terms:
+Mercurial already uses the following terms:
 
-:amend: rewrite a changeset
-:graft: copy a changeset
-:rebase: move a changeset
+:amend: to rewrite a changeset
+:graft: to copy a changeset
+:rebase: to move a changeset
 
 
 Uncommit
 `````````````
 
-remove files from a commit (and leave them as dirty in the working directory)
+Remove files from a commit (and leave them as dirty in the working directory)
 
-The evolve extension have an `uncommit` command that aims to replace most
+The *evolve* extension have an `uncommit` command that aims to replace most
 `rollback` usage.
 
 Fold
 ``````````
 
-Collapse multiple changeset into one
+Collapse multiple changesets into a uniq one.
 
-The evolve extensions *will* have a `fold` commands
+The *evolve* extension will have a `fold` command.
 
 Prune
 ``````````
 
 Make a changeset obsolete without successors.
 
-This an important operation as it should replace strip in 95% of the case.
+This an important operation as it should mostly replace *strip*.
 
-alternative name:
+Alternative names:
 
-- kill: nice name for effect when you forget the "hg" in front on "hg kill".
-- obsolete: too vague, long and generic.
+- kill: shall has funny effects when you forget "hg" in front of ``hg kill``.
+- obsolete: too vague, too long and too generic.
 
 Stabilize
 ```````````````
 
-Automatically resolve troublesome changesets
-(unstable, latecomer and conflicting)
+Automatically resolve *troublesome* changesets
+(*unstable*, *latecomer* and *conflicting*)
 
-This is an important name as hg pull/pussh will suggest it the same way it
+This is an important name as hg pull/push will suggest it the same way it
 suggest merging when you add heads.
 
 I do not like stabilize much.
 
-alternative name:
+alternative names:
 
 - solve (too generic ?)
 - evolve (too vague)
 
 
 
-
-
 .. note:: I'm not very happy with the naming of:
 
           - "ok" changeset