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

[Matt Mackall]

On Mon, 2011-10-03 at 19:19 +0000, Haszlakiewicz, Eric wrote:
> > -----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.

Again, I think we should just provide a way to -ask Mercurial where it
thinks the templates are-. Like this:

$ hg debuginstall
Checking encoding (UTF-8)...
Checking installed modules (/home/mpm/hg/mercurial)...
Checking templates (/home/mpm/hg/mercurial/templates)...
Checking commit editor...
Checking username...

This is infinitely more reliable than any manual procedure we could
document. I'll go ahead and push the patch I wrote to add this little
feature.

> > 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.

This file is a thin, static skeleton:

http://www.selenic.com/hg/file/fccd350acf79/doc/hg.1.txt#l48

and the hg.1.gendoc.txt is the auto-generated content.

-- 
Mathematics is the supreme nostalgia of our time.