diff docs/evolve-faq.rst @ 228:5a17c0d41a00

proof-read documentation and docstrings

--- a/docs/evolve-faq.rst	Wed May 09 13:08:46 2012 +0200
+++ b/docs/evolve-faq.rst	Wed May 09 14:24:56 2012 +0200
@@ -3,6 +3,8 @@
 Evolve How To
 ---------------------------------------------------------------------
 
+
+
 Add a changeset: ``commit``
 ------------------------------------------------------------
 
@@ -11,9 +13,10 @@
 Rewrite a changeset: ``amend``
 ------------------------------------------------------------
 
-A dedicated command ``hg amend`` is added by the extension. It writes a new
-changeset combining working-directory parent changes and parent. It will work on
-any `draft` or `secret` changeset. It will not work on `public` changesets.
+A new command ``hg amend`` is added by the extension. It writes a new
+changeset combining working-directory parent changes and parent. It
+will work on any `draft` or `secret` changeset. It will not work on
+`public` changesets.
 
 To understand what the result of amend will be I use the two following
 aliases  [#]_::
@@ -30,15 +33,13 @@
 This command can even be invoked on changesets with children (provided
 none is public) !
 
-.. note:: The amend command is very similar to mq's ``qrefresh``, a ``refresh``
+.. note:: the amend command is very similar to mq's ``qrefresh``, a ``refresh``
           alias for amend is also available. But note that contrary to
           ``qrefresh``, ``amend`` does not exclude changes on file not specified
           on the command line.
 
           XXX add idank example
 
-.. warning:: The `hg commit --amend` switch does **not** lay obsolete marker
-             down yet. You should always prefer the dedicated command.
 
 .. [#] (added by enable.sh)
 
@@ -51,13 +52,13 @@
 branches onto the current branch".
 
 The graft command has been altered to allow the creation of an
-obsolete marker between both the result cset and its source
+obsolete marker indicating both the result cset and its source
 (actually recording changeset movements).
 
 This is achieved using a new flag `-O` (or `old-obsolete`) [#]_.
 
 
-XXX Need a few examples here.
+XXX example
 
 .. warning:: when using graft --continue after conflict resolution you **MUST**
              pass `-O` or `-o` flag again because they are not saved for now
@@ -67,17 +68,13 @@
        abusive. But this was very convenient for experimental purposes.
        This will likely change in non experimental release.
 
-
 Delete a changeset: ``kill``
 ------------------------------------------------------------
 
-A new ``kill``[#]_ command allows removing a changeset.
+A new ``kill`` command allows removing a changeset.
 
 Just use ``hg kill <some-rev>``.
 
-.. [#] `kill` is a terrible name. **NEVER** forget to add `hg` in front of it
-        until we find a better name.
-
 Moving within the history: ``up`` ``gdown`` and ``gup``
 ------------------------------------------------------------
 
@@ -94,16 +91,12 @@
 Collapse changesets: ``amend``
 ------------------------------------------------------------
 
-You can use amend -c to collapse multiple changeset in a single one.
-
-
-.. note:: This is a terrible UI. `hg collapse` should be ported to obsolete
-          marker for this purpose.
+you can use amend -c to collapse multiple changeset in a single one.
 
 Split a changeset
 -----------------------
 
-There is no official command to split a changeset [#]_ . However is it easily achieved
+There is no official command to split a changeset. However is it easily achieved
 by manual operation::
 
   ### you want to split changeset A: 42
@@ -119,8 +112,6 @@
   # current changeset (.) and previous one (.^) replace A (42)
   $ hg kill --new . --new .^ 42
 
-.. [#] Yet
-
 
 Update my current work in progess after a pull
 ----------------------------------------------
@@ -128,14 +119,10 @@
 Whenever you are working on some changesets, it is more likely that a pull 
 will, eventually, import new changesets in your tree.
 
-And it is likely that you will want your work in progress changesets to be 
+And it is likely that you will want your work in progress changsets to be 
 rebased on the top of this newly imported subtree.
 
-Doing so is only a matter of rebasing. Rebase have been wrapped to lay obsolete
-marker down.
-
-
-XXX Add an example here.
+Doing so is only a matter of rebasing.
 
 
 
@@ -144,7 +131,7 @@
 
 You can still use rebase to move a whole segment of the changeset graph together.
 
-.. warning:: Beware that rebasing changesets already obsolete by others will result in
+.. warning:: Beware that rebasing obsolete changesets will result in
              conflicting versions of the changesets.
 
 Stabilize history: ``stabilize``
@@ -159,17 +146,15 @@
 newest version. This is not done automatically to avoid the
 proliferation of useless hidden changesets.
 
-.. warning::
-
-    * ``hg stabilize`` have no --continue to use after conflict
+.. warning:: ``hg stabilize`` have no --continue to use after conflict
              resolution
 
-    *  stabilization does not handle deletion yet.
+.. warning:: stabilization does not handle deletion yet.
 
-    * stabilization does not handle rewriting conflict yet.
+.. warning:: obsolete currently relies on changesets in secret phase
+              to avoid exchanging obsolete and unstable changesets.
 
-    *  obsolete currently relies on changesets in secret phase
-       to avoid exchanging extinct() changesets.
+             XXX details issue here
 
 
 Fix my history afterward: ``kill -n``
@@ -178,17 +163,18 @@
 Sometimes you need to create an obsolete marker by hand. This may happen when
 upstream has applied some of your patches for example.
 
-You can use ``hg kill --new <new-changeset> <old-changeset>`` to add obsolete
+you can use ``hg kill --new <new-changeset> <old-changeset>`` to add obsolete
 marker.
 
-Export to mq: ``qsync``
+Export to mq: ``synchronize``
 ------------------------------------------------------------
 
-Another extension allows to export mutable changeset to mq. See the
-`enable-qsync.sh` to enable it and read module documentation for details.
+Another extension allows to export.
 
-If you do not work at Logilab. You probably do not need it.
+View change to your file
+------------------------------------------------------------
 
+Another extension allows to export.
 
 View diff from the last amend
 ------------------------------------------------------------
@@ -199,9 +185,6 @@
     [alias]
     odiff = diff --rev 'limit(obsparents(.),1)' --rev .
 
-The qt viewer `hgview` displays obsolete data and allows to see diff again
-obsolete parent.
-
 View obsolete markers
 ------------------------------------------------------------
 
@@ -212,9 +195,22 @@
 
 
 
+Important Note
+=====================================================================
+
+View change to your file
+------------------------------------------------------------
+
+Extinct changesets are hidden using the *hidden* feature of mercurial.
+
+Only ``hg log`` and ``hgview`` support it. ``hg glog`` or other visual viewer don't.
 
 
 
 
 
 
+
+
+
+