# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@ens-lyon.org>
# Date 1473245123 -7200
# Node ID 9c7665e3107ba0393349c265d3d47348ea5a1447
# Parent  8464a7708f9d73de1d13c2c4e5e5b6970ea0ec62
documentation: some basic update of the documentation

So far the documentation was pretty scarce and a lot of important information
was missing.

The new content is probably not great but it is an improvement.

diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -6,10 +6,15 @@
 that it should "dissolve" upon being finished. This extension exists
 to be a sandbox for that experimentation.
 
-# usage
+# install
 
 Enable topics like any mercurial extension: download the source code to a
 local directory, and add that directory to your `.hgrc`:
 
     [extensions]
     topics=path/to/hg-topics/hgext3rd/topic/
+
+# help
+
+See 'hg help -e topic' for a generic help.
+See 'hg help topics' and 'hg help stack' for help on specific commands.
diff --git a/hgext3rd/topic/__init__.py b/hgext3rd/topic/__init__.py
--- a/hgext3rd/topic/__init__.py
+++ b/hgext3rd/topic/__init__.py
@@ -4,12 +4,42 @@
 # GNU General Public License version 2 or any later version.
 """support for topic branches
 
-Topic branches are lightweight branches which
-disappear when changes are finalized.
+Topic branches are lightweight branches which disappear when changes are
+finalized (move to the public phase).
+
+Compared to bookmark, topic is reference carried by each changesets of the
+series instead of just the single head revision.  Topic are quite similar to
+the way named branch work, except they eventualy fade away when the changeset
+becomes part of the immutable history.  Changeset can below to both a topic and
+a named branch, but as long as it is mutable, its topic identity will prevail.
+As a result, default destination for 'update', 'merge', etc...  will take topic
+into account. When a topic is active these operations will only consider other
+changesets on that topic (and, in some occurence, bare changeset on same
+branch).  When no topic is active, changeset with topic will be ignored and
+only bare one on the same branch will be taken in account.
+
+There is currently two commands to be used with that extension: 'topics' and
+'stack'.
 
-This is sort of similar to a bookmark, but it applies to a whole
-series instead of a single revision.
+The 'hg topics' command is used to set the current topic and list existing one.
+'hg topics --verbose' will list various information related to each topic.
+
+The 'stack' will show you in formation about the stack of commit belonging to
+your current topic.
+
+In addition, topic is offering your aliases reference to changeset in your
+current topic stack as 't#'. For example, 't1' refers to the root of your
+stack, 't2' to the second commits, etc. The 'hg stack' command show these
+number.
+
+Finally, the 'evolve' extension takes 'topic' into account. 'hg evolve --all'
+will evolve all changesets in the active topic. In addition, by default. 'hg
+next' and 'hg prev' will stick to the current topic.
+
+Be aware that this extension is still an experiment, commands and other features
+are likely to be change/adjusted/dropped over time as we refine the concept.
 """
+
 from __future__ import absolute_import
 
 import re
@@ -206,7 +236,9 @@
         ('l', 'list', False, 'show the stack of changeset in the topic'),
     ] + commands.formatteropts)
 def topics(ui, repo, topic='', clear=False, change=None, list=False, **opts):
-    """View current topic, set current topic, or see all topics."""
+    """View current topic, set current topic, or see all topics.
+
+    The --verbose version of this command display various information on the state of each topic."""
     if list:
         if clear or change:
             raise error.Abort(_("cannot use --clear or --change with --list"))
@@ -290,7 +322,7 @@
 
 @command('stack [TOPIC]', [] + commands.formatteropts)
 def cmdstack(ui, repo, topic='', **opts):
-    """list all changesets in a topic
+    """list all changesets in a topic and other information
 
     List the current topic by default."""
     if not topic:
diff --git a/tests/test-topic.t b/tests/test-topic.t
--- a/tests/test-topic.t
+++ b/tests/test-topic.t
@@ -17,6 +17,9 @@
   
   View current topic, set current topic, or see all topics.
   
+      The --verbose version of this command display various information on the
+      state of each topic.
+  
   options:
   
       --clear        clear active topic if any