[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 16:14 +0000, Haszlakiewicz, Eric wrote:
> > +The --style option can specify an explicit filename, or the name of
> > +a pre-installed style.  The pre-installed styles are located in
> > +<install-dir>/lib/python<version>/site-
> packages/mercurial/templates/map-cmdline.<style>
> 
> Except when it's not. Which is probably the case on Windows. And on
> systems with lib64, and /usr/shared/pyshared, and when there are
> multiple copies installed, etc..
> 
> I think we should have some way of reporting where Mercurial thinks the
> templates are and then document it here.

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" ?

> > +However, for performance reasons the map-cmdline.default style file
> is only
> > +present for reference, as a compiled in default is used when --style
> is not
> > +specified.  You can force the non-compiled-in default to be used by
> specifying
> > +--style default.
> 
> Well, that's not strictly correct. When no style is specified, we don't
> use a template at all.

eh?  There must be *some* kind of template, right?  If there isn't some kind of pattern that hg follows how can it output anything?  I don't understand the point you're making.

> But you're right, the 'default' style is apparently just as, well, a
> template, and tweaking it won't actually change the default appearance.
> This might be better addressed with a comment in that file.

Sure, a comment in the default style file sounds great, but that won't help someone that does a cp map-cmdline.foo map-cmdline.default, so including some mention that map-cmdline.default in the main documentation seems like it would be a good idea.

> > @@ -22,6 +31,7 @@
> >  Strings in curly braces are called keywords. The availability of
> >  keywords depends on the exact context of the templater. These
> >  keywords are usually available for templating a log-like command:
> > +(See the output of "hg help templates" for a more up-to-date list.)
> 
> ??
> 
> This -is- the output of 'hg help templates'?

It might be the output of hg help templates, but it's *also* what ends up in the hg.1 man page, and that's what you find when you do a web search.  Pointing the way to the best place to look for the docs seems like it would be quite helpful for people that aren't hg experts and don't yet know that a "hg help templates" command even exists.

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/77c4d196/attachment.pgp>