Update the README with the text from
http://trac.edgewall.org/wiki/TracMercurial as of
Wed Jul 23 02:22:14 MDT 2008

diff -r 5b8cf9b54b67 README
--- a/README	Wed Jul 23 02:20:02 2008 -0600
+++ b/README	Wed Jul 23 02:24:32 2008 -0600
@@ -1,6 +1,6 @@
 = Mercurial Plugin for Trac (#1847) =
 
-There is an '''experimental''' plugin for Trac [milestone:0.10] 
+There is an '''experimental''' plugin for Trac [milestone:0.10] and  Trac [milestone:0.11]
 which enables [http://www.selenic.com/mercurial Mercurial] 
 to be used instead of [http://subversion.tigris.org Subversion]
 as the VersioningSystemBackend for Trac.
@@ -10,51 +10,107 @@
 
 Change Logs: 
  * log:sandbox/mercurial-plugin
- * log:sandbox/vc-refactoring
+ * log:sandbox/mercurial-plugin-0.11
+ * log:sandbox/mercurial-plugin-0.12 (for the MultipleRepositorySupport branch)
 
 == Download and Installation ==
+=== Trac ===
+==== Trac 0.10 ====
 
-==== Trac ====
-The plugin needs a slightly modified version of Trac 0.10.
-This version can be found in source:sandbox/vc-refactoring.
+The plugin [source:sandbox/mercurial-plugin] works fine with Trac 0.10.3, though it will lack the "quickjump" to a branch or tag feature (this was implemented in source:sandbox/vc-refactoring, but is only available in the mainline for 0.11).
 
-Simply do:
+See TracDownload and install Trac the usual way (see TracInstall)
+
+The plugin itself is available from source:sandbox/mercurial-plugin
+
+Check it out:
+
 {{{
-svn co -r2905 http://svn.edgewall.com/repos/trac/sandbox/vc-refactoring 
+svn co http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin 
+}}}
+and create an "egg" from there 
+{{{
+$ cd mercurial-plugin
+$ python setup.py bdist_egg
+}}}
+
+==== Trac 0.11 ====
+
+There's a newer version of the plugin  [source:sandbox/mercurial-plugin-0.11] which has been adapted to work with the trunk version of Trac ([milestone:0.11]dev) and is kept in sync with it.
+
+One of the advantage of using this version is that you won't need to install ClearSilver anymore; instead you'll need the Genshi template engine (which is Python only, and therefore straightforward to install).
+
+That version of the Mercurial plugin also supports of the new features added in 0.11 to the TracBrowser:
+ - quickjump to a tag or branch
+ - blame support
+ - custom property renderers ([source:sandbox/property-renderers-tmp], not yet in trunk)
+
+{{{
+svn co http://svn.edgewall.com/repos/trac/trunk trac
+svn co http://svn.edgewall.org/repos/genshi/trunk genshi
 }}}
 and install from there:
 {{{
-$ cd vc-refactoring 
-$ python setup.py egg_info 
+$ cd trac
+$ python setup.py install
+$ cd ..
+$ cd genshi
 $ python setup.py install
 }}}
+(for Genshi, you might prefer to use a packaged release, see Genshi:GenshiDownload, or to easy_install it)
 
-The plugin itself is available from source:sandbox/mercurial-plugin
+Then, you need the plugin itself:
+{{{
+svn co http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin-0.11 
+}}}
+create an "egg" from there:
+{{{
+$ cd mercurial-plugin-0.11
+$ python setup.py bdist_egg
+}}}
 
-Check it out, too:
-{{{
-svn co -r2905 http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin 
-}}}
-and create an "egg" from there (`cd hg-plugin; python setup.py bdist_egg`).
 Note that you'll need
-[http://peak.telecommunity.com/DevCenter/setuptools setuptools] 
->= 0.6 for that (I used setuptools-0.6a9).
+[http://peak.telecommunity.com/DevCenter/setuptools setuptools] >= 0.6 for that (I used setuptools-0.6a9).
 
-===== Releases =====
+==== Releases ====
 || '''Version''' || mercurial-plugin || Trac vc-refactoring || Compatible with hg         ||
+|| ''0.12.0.0''  || [source:sandbox/mercurial-plugin-0.12] || [source:sandbox/multirepos] ('''not''' trunk) ||  0.9.x, 1.0.x, tip  ? ||
+||'''0.11.0.4''' || [source:sandbox/mercurial-plugin-0.11] || [milestone:0.11] or [source:branches/0.11-stable] ||  0.9.x, 1.0.x, tip  ||
+|| ''0.10.0.2''  || [source:sandbox/mercurial-plugin] (0.10) || [milestone:0.10]    ||  0.7, 0.8, 0.9  ||
+||      0.2      ||    '''r3014'''   || [source:trunk@2900] ||  0.7, 0.8, tip  ||
+||      0.2      ||    '''r2905'''   ||     '''r2905'''     ||  0.7, 0.8, tip  ||
+||               ||       r2620      ||        r2620        ||  0.7, tip with 1d7d0c07    ||
 ||      0.1      ||       r2514      ||        r2511        ||  0.7, tip without 1d7d0c07 ||
-||               ||       r2620      ||        r2620        ||  0.7, tip with 1d7d0c07    ||
-||   '''0.2'''   ||    '''r2905'''   ||     '''r2905'''     ||  0.7, 0.8, tip  ||
 
+Note: 
+ - '''the ''Compatible with hg'' column above needs to be updated''' [[br]]
+   It is quite likely that some 0.9.x versions (maybe even 0.9.5) won't work anymore with the 0.11 and 0.12 versions of the plugin (i.e. those are the version actively maintained)
+ - the 0.12 version is somewhat experimental at this point ''worksforme''
+ - the original branch ([source:sandbox/mercurial-plugin]) which is only for Trac 0.10 is not actively maintained anymore (patches still accepted if you happen to fix a bug, of course)
+ - 0.9.1 was reported not to work with the 0.11 version of the plugin
+ - 0.9.4 (and probably quite a few intermediate changesets between 0.9.3 and 0.9.4) interferes badly with the TH:AccountManager plugin when using Python 2.3.5. 
+It's not unlikely that other setups can be affected by the problem, as basically any code that relies on trapping the `ImportError`, after the `mercurial.demandimport` mechanism has been activated, will fail.
 
-==== Mercurial ====
+If you happen to have this problem (`TypeError: 'unloaded module' object is not callable`}, you need at least r5766/r5767. See also [http://www.selenic.com/mercurial/bts/issue605 issue605].
+
+=== Mercurial ===
 The plugin has been tested with recent development versions of Mercurial
-(upto Changeset 1704:c2755eba8631 from http://selenic.com/hg)
+(upto Changeset 3324:34f08b8883cf from http://selenic.com/hg)
 and also with Mercurial 0.7 and 0.8.
-''It won't work with earlier versions, in particular not with 0.6x.''
+'''It won't work with earlier versions, in particular not with 0.6x.'''
+
+The plugin for 0.11 takes benefit of some new features introduced after the 0.8.2 release of Mercurial, and therefore needs at least a 0.9 version of Mercurial. 
+
+Note: as mentioned here
+[http://groups.google.com/group/trac-users/browse_thread/thread/9b1cd95621c19921/9f829e8acd958a8e]
+It *does* require mercurial-0.9.5. Mercurial 0.9.3 is confirmed to not work with plugin 0.11.
 
 You can download Mercurial itself from 
 [http://www.selenic.com/mercurial/wiki/index.cgi/Download Hg:Download].
+
+On Windows, it looks like it's possible to re-use the Mercurial library coming from the [Mercurial:BinaryPackages installer], 
+see [http://selenic.com/pipermail/mercurial/2007-July/013827.html this mail]
+(though to my knowledge, it is not possible to achieve this using PYTHONPATH and PATH: it fails with `ImportError: No module named handlers` due to library.zip coming in the sys.path before the standard library).
 
 
 == Configuration ==
@@ -70,7 +126,7 @@
 
 === Setting up the mercurial plugin ===
 
-The TracMercurial-0.2 plugin egg should be added to the `plugins` folder of the 
+The TracMercurial plugin egg should be added to the `plugins` folder of the 
 environment, or it can be globally installed (`python setup.py install`
 or a `python setup.py develop`).
 
@@ -78,14 +134,19 @@
 
 If you installed the egg globally and you're modifying an 
 existing Trac environment to use the Mercurial backend,
-then you have to explicitely ''enable'' the plugin in TracIni:
+then you have to explicitly ''enable'' the plugin in TracIni.
+
+For the 0.10 plugin, this is done like that:
 {{{
 [components]
-trac.versioncontrol.hg.* = enabled
+tracvc.hg.* = enabled
 }}}
-Note that the above will be done automatically for a new installation,
-during the `initenv` step.
 
+Since the 0.11 of the plugin, the package has been renamed to `tracext`:
+{{{
+[components]
+tracext.hg.* = enabled
+}}}
 
 === Setting up a Trac environment ===
 
@@ -94,7 +155,7 @@
 
 For general instructions, see TracInstall.
 
-Since milestone:0.10, the TracAdmin `initenv` command has 
+Since [milestone:0.10], the TracAdmin `initenv` command has 
 now a ''repository type'' argument besides ''repository directory''.
 
 For the ''repository type'', specify `hg` instead of the default `svn`.
@@ -128,6 +189,7 @@
 on the Mercurial repository itself and the performance is acceptable, 
 even if there's currently ''no'' caching in the database
 (this is what I'm going to work on next).
+Don't even think about using the plugin on a Linux-kernel-sized Mercurial repository, you'll probably burn your disk and/or CPUs ;)
 
 For those used to Subversion in general and Subversion repository browsing
 in Trac in particular, there are a few differences worth noting.
@@ -144,7 +206,7 @@
 children as well (0 to n). 
 
 Therefore, ''Previous Changeset'' is a link to the first parent, 
-and ''Next Changeset'' is a link to the first children.
+and ''Next Changeset'' is a link to the first child.
 In case there are additional parents or children, these are shown as 
 additional changeset properties (''Parents'' or ''Children''), 
 placed below the ''Author'' property and above the ''Message'' property.
@@ -160,6 +222,7 @@
 The Wiki syntax has been extended a bit, to cope with the hexadecimal
 notation of hg changesets. E.g `[8ef2]` would link to the changeset 
 8ef2ba892518c115170398ec754bd1c27cab271f ...
+Plain changeset numbers are also recognized, provided they are long enough (12 to 40).
 Also, it is possible to refer to changesets using the changeset: prefix 
 (or cset: or chgset:, for hgweb compatibility). 
 The tag: prefix can be used to refer to symbolic tags, although this is not
@@ -168,14 +231,24 @@
 the specified revision, but the head which is reachable from that revision.
 
 
-=== TracBrowser changes ===
+=== TracBrowser changes in [milestone:0.11] ===
 
 The TracBrowser ''View revision'' form has been extended with
 pulldown menus for jumping to a given tag or branch (in Mercurial, 
 a branch within a repository corresponds to a head, i.e. a 
-changeset without children): [[Image(hg-plugin-browser.png)]]
+changeset without children): 
+----
+[[Image(hg-plugin-browser.png)]]
+----
+There's also support for visual ''blame'' annotations: 
+----
+[[Image(hg-plugin-annotate.png)]]
 
-''has to be re-added''
+=== Mercurial Queue ===
+
+Since r6443, the MQ extension is supported. If you happen to have applied mq patches in your repository, Trac will show the corresponding patch names as '''Tags:''' in the changeset view.
+
+Also, with the 0.12 branch of the plugin (and the MultipleRepositorySupport branch of Trac), you can browse jointly the main repository and the repository for the associated Mercurial queue, if any (i.e. if you versioned your patch queue using `hg qinit -c` and `hg qcommit`). Furthermore, if you declare such a mercurial repository to be a MQ repository, then all the patches will be correctly rendered as patches, regardless of the patch name (see r6462 for details).
 
 == Bugs and Limitations ==
 
@@ -187,7 +260,7 @@
  * No ''path history'' mode (i.e. show all create/delete operations that 
    affected a given path)
  * Revision log ranges [xxx:yyy]
- * View arbitrary diffs
+ * ~~View arbitrary diffs~~ ''implemented in r6053''
 
 === Multi-repository support ===
 
@@ -199,8 +272,9 @@
 Trac should support this by the way of multiple repository support 
 within a single environment (see #2086).
 
-Note that the last comment on the above ticket suggests a good
-workaround for this problem.
+'''New''':
+This is now implemented.
+Use the 0.12 version of the plugin and the MultipleRepositorySupport.
 
 
 === To cache or not to cache? ===
@@ -223,6 +297,11 @@
 the revision log view. Not something as fancy as `hgk`, but nonetheless
 something that will make the changeset relationships immediately obvious.
 
+There's an existing web implementation by Alexander Schremmer:
+ http://moin.pocoo.org:8080/ (select a repo and then 'branchview' button on the top to see it in action)
+
+Also, there is [http://trac-hacks.org/wiki/RevtreePlugin RevtreePlugin].
+
 ==== Search over the source ====
 
 A search provider could do the equivalent of an `hg grep`.
@@ -234,9 +313,23 @@
 how conflicts (if any) were solved. But this can be improved by 
 specifically highlighting lines that differs from both parents.
 
+==== Repository Management ====
+
+Trac should allow for creating new repositories or clones of existing repositories. Maybe repository deletion and renaming should be supported, too.
+
+==== Some Manuals, FAQs and a Forum for this project ====
+I am a novice with Aptana/Eclipse and Mercurial. I was hoping this plugin would give me some assistance over the command line interface, but I cannot even understand how to use it from this plug in. I have an existing mercurial repository.  What do I do next to use it?  A forum might be useful, as I think there is a big audience for a GUI for mercurial, now that firefox has gone to it.
+
+==== HG Forest Support ====
+
+Support for the Forest extension for Mercurial. Forest extension allows operations on trees with nested Mercurial repositories, called forests. Those to some degree correspond to multi-project CVS/Svn/... repositories.
+
+Already got most of it working, expect that it's pretty much hacked in the Trac 0.10.3 version of the mercurial plugin.
+Since it needs a bit more flexibile templating (in regards with the lookup/url's) this is hacked around node.path at the moment. Some (small/large?) issues remain but most of it is working.
+
+ ''Note that with the MultipleRepositorySupport branch of Trac, it should be possible to implement an IRepositoryProvider component knowing about the `forest` extension and adding besides the repository for the forest itself, the managed repositories as well.''
+
 ==== ''Add your cool feature here...'' ====
-
-----
 
 == Implementation Notes ==
 
