[PATCH] update templates doc to better explain the default style

[Haszlakiewicz, Eric]

> -----Original Message-----
> From: Matt Mackall [mailto:mpm at selenic.com]
> On Mon, 2011-10-03 at 18:00 +0000, Haszlakiewicz, Eric wrote:
> > hmm... maybe "... are located in the
> > mercurial/templates/map-cmdline.<style> file, which can be found
> > wherever the python files for mercurial get installed on your
> > system" ?
> 
> I'm not confident that'll be helpful to Windows users, who may not even
> be aware that there's an entire copy of Python hidden inside hg.exe.

hmm.. and I just noticed that with TortoiseHG the templates directory isn't even inside a directory called mercurial, so how about an even simpler note of:

The pre-installed styles are named "map-cmdline.<style>" and are located in the "templates" directory, which will be somewhere within your Mercurial installation location.

> It implies that somewhere in the source there's something that looks
> like the template named 'default'. Which is not at all how it works:
> 
> http://www.selenic.com/hg/file/fccd350acf79/mercurial/cmdutil.py#l622
> 
> It's a completely different code path that just does what amounts to
> hard-coded print statements. It's not a "template" in anything like the
> sense we're using here.

Oh, I see.  Thanks for the link to the code.

> Fair enough. How about:
> 

diff --git a/mercurial/help/templates.txt b/mercurial/help/templates.txt
--- mercurial/help/templates.txt
+++ mercurial/help/templates.txt
@@ -13,6 +13,15 @@

     $ hg log -r1 --style changelog

+The --style option can specify an explicit filename, or the name of
+a pre-installed style.  The pre-installed styles are named
+"map-cmdline.<style>" and are located in the "templates" directory,
+ which will be somewhere within your Mercurial installation location.
+
+Note:: a copy of the built-in format is provided as map-cmdline.default
+but modifying it won't affect the default output.  You can force the
+map-cmdline.default file to be used by specifying --style default.
+
 A template is a piece of text, with markup to invoke variable
 expansion::

> I see. I would rather arrange for the man pages to mention that they
> are
> simply generated from the built-in help rather than making the built-in
> help paradoxical (it can't be more up-to-date than itself).

I'm not familiar with how the man pages are built, but if this can be done easily, then that would be great.

eric
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 474 bytes
Desc: not available
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20111003/5604a9c8/attachment.pgp>