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

Matt Mackall mpm at selenic.com
Mon Oct 3 14:00:35 CDT 2011


On Mon, 2011-10-03 at 18:00 +0000, Haszlakiewicz, Eric wrote:
> > -----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" ?

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.

(Aside: I frankly consider it a bug in distutils that _applications_
have their components dumped into the _library_ namespace. No Mercurial
user should really need to be aware that Python is involved and
shouldn't have to go digging around in their arbitrarily-messy Python
install to find Mercurial components.)

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

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.

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

Fair enough. How about:

Note:: a copy of the built-in format is provided as ... but modifying it
won't affect the default output.

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

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

-- 
Mathematics is the supreme nostalgia of our time.




More information about the Mercurial-devel mailing list