help: add topic rewriting hooks stable

help: add topic rewriting hooks

They are useful when updating help topics dynamically from extensions.

--- a/mercurial/help.py	Sat Oct 23 17:30:08 2010 +0200
+++ b/mercurial/help.py	Sat Oct 23 19:21:49 2010 +0200
@@ -79,7 +79,11 @@
                 break
 
         path = os.path.join(docdir, topic + ".txt")
-        return gettext(open(path).read())
+        doc = gettext(open(path).read())
+        for rewriter in helphooks.get(topic, []):
+            doc = rewriter(topic, doc)
+        return doc
+
     return loader
 
 helptable = [
@@ -102,3 +106,11 @@
     (["hgweb"], _("Configuring hgweb"), loaddoc('hgweb')),
     (["glossary"], _("Glossary"), loaddoc('glossary')),
 ]
+
+# Map topics to lists of callable taking the current topic help and
+# returning the updated version
+helphooks = {
+}
+
+def addtopichook(topic, rewriter):
+    helphooks.setdefault(topic, []).append(rewriter)

--- a/tests/test-help.t	Sat Oct 23 17:30:08 2010 +0200
+++ b/tests/test-help.t	Sat Oct 23 19:21:49 2010 +0200
@@ -756,3 +756,30 @@
       The reserved name "." indicates the working directory parent. If no
       working directory is checked out, it is equivalent to null. If an
       uncommitted merge is in progress, "." is the revision of the first parent.
+
+Test help hooks
+
+  $ cat > helphook1.py <<EOF
+  > from mercurial import help
+  > 
+  > def rewrite(topic, doc):
+  >     return doc + '\nhelphook1\n'
+  > 
+  > def extsetup(ui):
+  >     help.addtopichook('revsets', rewrite)
+  > EOF
+  $ cat > helphook2.py <<EOF
+  > from mercurial import help
+  > 
+  > def rewrite(topic, doc):
+  >     return doc + '\nhelphook2\n'
+  > 
+  > def extsetup(ui):
+  >     help.addtopichook('revsets', rewrite)
+  > EOF
+  $ echo '[extensions]' >> $HGRCPATH
+  $ echo "helphook1 = `pwd`/helphook1.py" >> $HGRCPATH
+  $ echo "helphook2 = `pwd`/helphook2.py" >> $HGRCPATH
+  $ hg help revsets | grep helphook
+      helphook1
+      helphook2