# HG changeset patch
# User Patrick Mezard <pmezard@gmail.com>
# Date 1287854509 -7200
# Node ID 0edc0aa7432d5fb7b71e1a0374c32d302672b771
# Parent  5082e2f3f8e02d73ca05b6ab989c49d5be73f50f
help: add topic rewriting hooks

They are useful when updating help topics dynamically from extensions.

diff -r 5082e2f3f8e0 -r 0edc0aa7432d mercurial/help.py
--- 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)
diff -r 5082e2f3f8e0 -r 0edc0aa7432d tests/test-help.t
--- 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