help: apply the section headings from revsets to templates

Unlike filesets, there are a few distinct headings that are not shared with
revsets.  But common names are used where possible.

mercurial/help/templates.txt

@@ -1,174 +1,192 b''
 Mercurial allows you to customize output of commands through
 templates. You can either pass in a template or select an existing
 template-style from the command line, via the --template option.
 
 You can customize output for any "log-like" command: log,
 outgoing, incoming, tip, parents, and heads.
 
 Some built-in styles are packaged with Mercurial. These can be listed
 with :hg:`log --template list`. Example usage::
 
     $ hg log -r1.0::1.1 --template changelog
 
 A template is a piece of text, with markup to invoke variable
 expansion::
 
     $ hg log -r1 --template "{node}\n"
     b56ce7b07c52de7d5fd79fb89701ea538af65746
 
+Keywords
+========
+
 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:
 
 .. keywordsmarker
 
 The "date" keyword does not produce human-readable output. If you
 want to use a date in your output, you can use a filter to process
 it. Filters are functions which return a string based on the input
 variable. Be sure to use the stringify filter first when you're
 applying a string-input filter to a list-like input variable.
 You can also use a chain of filters to get the desired output::
 
    $ hg tip --template "{date|isodate}\n"
    2008-08-21 18:22 +0000
 
+Filters
+=======
+
 List of filters:
 
 .. filtersmarker
 
 Note that a filter is nothing more than a function call, i.e.
 ``expr|filter`` is equivalent to ``filter(expr)``.
 
+Functions
+=========
+
 In addition to filters, there are some basic built-in functions:
 
 .. functionsmarker
 
+Infix
+=====
+
 We provide a limited set of infix arithmetic operations on integers::
 
   + for addition
   - for subtraction
   * for multiplication
   / for floor division (division rounded to integer nearest -infinity)
 
 Division fulfils the law x = x / y + mod(x, y).
 
 Also, for any expression that returns a list, there is a list operator::
 
     expr % "{template}"
 
 As seen in the above example, ``{template}`` is interpreted as a template.
 To prevent it from being interpreted, you can use an escape character ``\{``
 or a raw string prefix, ``r'...'``.
 
+Aliases
+=======
+
 New keywords and functions can be defined in the ``templatealias`` section of
 a Mercurial configuration file::
 
   <alias> = <definition>
 
 Arguments of the form `a1`, `a2`, etc. are substituted from the alias into
 the definition.
 
 For example,
 
 ::
 
   [templatealias]
   r = rev
   rn = "{r}:{node|short}"
   leftpad(s, w) = pad(s, w, ' ', True)
 
 defines two symbol aliases, ``r`` and ``rn``, and a function alias
 ``leftpad()``.
 
 It's also possible to specify complete template strings, using the
 ``templates`` section. The syntax used is the general template string syntax.
 
 For example,
 
 ::
 
   [templates]
   nodedate = "{node|short}: {date(date, "%Y-%m-%d")}\n"
 
 defines a template, ``nodedate``, which can be called like::
 
   $ hg log -r . -Tnodedate
 
+Examples
+========
+
 Some sample command line templates:
 
 - Format lists, e.g. files::
 
    $ hg log -r 0 --template "files:\n{files % '  {file}\n'}"
 
 - Join the list of files with a ", "::
 
    $ hg log -r 0 --template "files: {join(files, ', ')}\n"
 
 - Join the list of files ending with ".py" with a ", "::
 
    $ hg log -r 0 --template "pythonfiles: {join(files('**.py'), ', ')}\n"
 
 - Separate non-empty arguments by a " "::
 
    $ hg log -r 0 --template "{separate(' ', node, bookmarks, tags}\n"
 
 - Modify each line of a commit description::
 
    $ hg log --template "{splitlines(desc) % '**** {line}\n'}"
 
 - Format date::
 
    $ hg log -r 0 --template "{date(date, '%Y')}\n"
 
 - Display date in UTC::
 
    $ hg log -r 0 --template "{localdate(date, 'UTC')|date}\n"
 
 - Output the description set to a fill-width of 30::
 
    $ hg log -r 0 --template "{fill(desc, 30)}"
 
 - Use a conditional to test for the default branch::
 
    $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch',
    'on branch {branch}')}\n"
 
 - Append a newline if not empty::
 
    $ hg tip --template "{if(author, '{author}\n')}"
 
 - Label the output for use with the color extension::
 
    $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n"
 
 - Invert the firstline filter, i.e. everything but the first line::
 
    $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n"
 
 - Display the contents of the 'extra' field, one per line::
 
    $ hg log -r 0 --template "{join(extras, '\n')}\n"
 
 - Mark the active bookmark with '*'::
 
    $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, active, '*')} '}\n"
 
 - Find the previous release candidate tag, the distance and changes since the tag::
 
    $ hg log -r . --template "{latesttag('re:^.*-rc$') % '{tag}, {changes}, {distance}'}\n"
 
 - Mark the working copy parent with '@'::
 
    $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n"
 
 - Show details of parent revisions::
 
    $ hg log --template "{revset('parents(%d)', rev) % '{desc|firstline}\n'}"
 
 - Show only commit descriptions that start with "template"::
 
    $ hg log --template "{startswith('template', firstline(desc))}\n"
 
 - Print the first word of each line of a commit message::
 
    $ hg log --template "{word(0, desc)}\n"