diff mercurial/help.py @ 7678:b19850c7908a

help: some improvements for the templating topic

--- a/mercurial/help.py	Thu Jan 22 14:18:08 2009 +0100
+++ b/mercurial/help.py	Thu Jan 22 14:19:29 2009 +0100
@@ -248,29 +248,28 @@
     [diff] section of your hgrc. You do not need to set this option when
     importing diffs in this format or using them in the mq extension.
     ''')),
-    (['templating'], _('Usage of templates'),
+    (['templating'], _('Template Usage'),
      _(r'''
     Mercurial allows you to customize output of commands through
-    templates. There is command line option for that and additionally
-    styles, which are simply precanned templates that someone wrote.
+    templates. You can either pass in a template from the command line,
+    via the --template option, or select an existing template-style (--style).
 
-    You can customize output for any "log-like" command, which currently
-    are: log, outgoing, incoming, tip, parents, heads and glog (if you have
-    graphlog extension enabled).
+    You can customize output for any "log-like" command: log, outgoing,
+    incoming, tip, parents, heads and glog are all template-enabled.
 
-    There is three styles packaged with Mercurial: default (which is
-    naturally what you see by default), compact and changelog. Usage:
-
-        > hg log -r1 --style changelog
+    Three styles are packaged with Mercurial: default (the style used
+    when no explicit preference is passed), compact and changelog. Usage:
 
-    Template is a piece of text, where parts marked with special syntax
-    are expanded, for example:
+        $ hg log -r1 --style changelog
 
-        > hg log -r1 --template "{node}\n"
+    A template is a piece of text, with markup to invoke variable expansion:
+
+        $ hg log -r1 --template "{node}\n"
         b56ce7b07c52de7d5fd79fb89701ea538af65746
 
-    Strings in curly brackets are called keywords and that's their
-    current list:
+    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:
 
     - author: String. The unmodified author of the changeset.
     - branches: String. The name of the branch on which the changeset
@@ -280,6 +279,7 @@
     - files: List of strings. All files modified, added, or removed by
           this changeset.
     - file_adds: List of strings. Files added by this changeset.
+    - file_mods: List of strings. Files modified by this changeset.
     - file_dels: List of strings. Files removed by this changeset.
     - node: String. The changeset identification hash, as a 40-character
           hexadecimal string.
@@ -287,48 +287,48 @@
     - rev: Integer. The repository-local changeset revision number.
     - tags: List of strings. Any tags associated with the changeset.
 
-    But "date" keyword does not produce human-readable output, what
-    means that you should use a filter to process it. Filter is a
-    function which modifies the result of expanding a keyword and
-    Mercurial lets you specify a chain of filters:
+    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.
+    You can also use a chain of filters to get the wanted output:
 
-       > hg tip --template "{date|isodate}\n"
+       $ hg tip --template "{date|isodate}\n"
        2008-08-21 18:22 +0000
 
     List of filters:
 
-    - addbreaks: Any text. Add an XHTML "<br/>" tag before the end of
+    - addbreaks: Any text. Add an XHTML "<br />" tag before the end of
           every line except the last.
-    - age: Date. Render the age of the date.
-    - basename: Any text. Treat the text as a path, and return the
+    - age: Date. Returns a human-readable age for the given date.
+    - basename: Any text. Treats the text as a path, and returns the
           basename. For example, "foo/bar/baz" becomes "baz".
-    - date: Date. Render a date in a Unix date command format, but with
-          timezone included: "Mon Sep 04 15:13:13 2006 0700".
+    - date: Date. Returns a date in a Unix date command format, including
+          the timezone: "Mon Sep 04 15:13:13 2006 0700".
     - domain: Any text. Finds the first string that looks like an email
-          address, and extract just the domain component.
-    - email: Any text. Extract the first string that looks like an email
+          address, and extracts just the domain component.
+    - email: Any text. Extracts the first string that looks like an email
           address.
-    - escape: Any text. Replace the special XML/XHTML characters "&",
+    - escape: Any text. Replaces the special XML/XHTML characters "&",
           "<" and ">" with XML entities.
-    - fill68: Any text. Wrap the text to fit in 68 columns.
-    - fill76: Any text. Wrap the text to fit in 76 columns.
-    - firstline: Any text. Yield the first line of text.
-    - hgdate: Date. Render the date as a pair of readable numbers:
-          "1157407993 25200".
-    - isodate: Date. Render the date in ISO 8601 format.
-    - obfuscate: Any text. Yield the input text rendered as a sequence
+    - fill68: Any text. Wraps the text to fit in 68 columns.
+    - fill76: Any text. Wraps the text to fit in 76 columns.
+    - firstline: Any text. Returns the first line of text.
+    - hgdate: Date. Returns the date as a pair of numbers:
+          "1157407993 25200" (Unix timestamp, timezone offset).
+    - isodate: Date. Returns the date in ISO 8601 format.
+    - obfuscate: Any text. Returns the input text rendered as a sequence
           of XML entities.
-    - person: Any text. Yield the text before an email address.
-    - rfc822date: date keyword. Render a date using the same format used
+    - person: Any text. Returns the text before an email address.
+    - rfc822date: Date. Returns a date using the same format used
           in email headers.
-    - short: Changeset hash. Yield the short form of a changeset hash,
+    - short: Changeset hash. Returns the short form of a changeset hash,
           i.e. a 12-byte hexadecimal string.
-    - shortdate: Date. Render date like "2006-09-04".
-    - strip: Any text. Strip all leading and trailing whitespace.
-    - tabindent: Any text. Yield the text, with every line except the
+    - shortdate: Date. Returns a date like "2006-09-04".
+    - strip: Any text. Strips all leading and trailing whitespace.
+    - tabindent: Any text. Returns the text, with every line except the
           first starting with a tab character.
-    - urlescape: Any text. Escape all "special" characters. For example,
-          foo bar becomes foo%20bar.
-    - user: Any text. Return the "user" portion of an email address.
+    - urlescape: Any text. Escapes all "special" characters. For example,
+          "foo bar" becomes "foo%20bar".
+    - user: Any text. Returns the user portion of an email address.
     ''')),
 )