@@ -218,8 +218,10 @@ def buildfunc(exp, context):
return (runfilter, (args[0][0], args[0][1], f))
raise error.ParseError(_("unknown function '%s'") % n)
def date(context, mapping, args):
+ """:date(date[, fmt]): Format a date. See :hg:`help dates` for formatting
+ strings."""
if not (1 <= len(args) <= 2):
# i18n: "date" is a keyword
raise error.ParseError(_("date expects one or two arguments"))
@@ -229,8 +231,10 @@ def date(context, mapping, args):
return util.datestr(date, fmt)
return util.datestr(date)
def diff(context, mapping, args):
+ """:diff([includepattern [, excludepattern]]): Show a diff, optionally
+ specifying files to include or exclude."""
if len(args) > 2:
# i18n: "diff" is a keyword
raise error.ParseError(_("diff expects one, two or no arguments"))
@@ -246,8 +250,10 @@ def diff(context, mapping, args):
return ''.join(chunks)
def fill(context, mapping, args):
+ """:fill(text[, width[, initialident[, hangindent]]]): Fill many
+ paragraphs with optional indentation. See the "fill" filter."""
if not (1 <= len(args) <= 4):
# i18n: "fill" is a keyword
raise error.ParseError(_("fill expects one to four arguments"))
@@ -269,10 +275,10 @@ def fill(context, mapping, args):
return templatefilters.fill(text, width, initindent, hangindent)
def pad(context, mapping, args):
- """usage: pad(text, width, fillchar=' ', right=False)
- """
+ """:pad(text, width[, fillchar=' '[, right=False]]): Pad text with a
+ fill character."""
if not (2 <= len(args) <= 4):
# i18n: "pad" is a keyword
raise error.ParseError(_("pad() expects two to four arguments"))
@@ -295,8 +301,11 @@ def pad(context, mapping, args):
else:
return text.ljust(width, fillchar)
def get(context, mapping, args):
+ """:get(dict, key): Get an attribute/key from an object. Some keywords
+ are complex types. This function allows you to obtain the value of an
+ attribute on these type."""
if len(args) != 2:
# i18n: "get" is a keyword
raise error.ParseError(_("get() expects two arguments"))
@@ -316,8 +325,10 @@ def _evalifliteral(arg, context, mapping
else:
yield t
def if_(context, mapping, args):
+ """:if(expr, then[, else]): Conditionally execute based on the result of
+ an expression."""
if not (2 <= len(args) <= 3):
# i18n: "if" is a keyword
raise error.ParseError(_("if expects two or three arguments"))
@@ -327,8 +338,10 @@ def if_(context, mapping, args):
elif len(args) == 3:
yield _evalifliteral(args[2], context, mapping)
def ifcontains(context, mapping, args):
+ """:ifcontains(search, thing, then[, else]): Conditionally execute based
+ on whether the item "search" is in "thing"."""
if not (3 <= len(args) <= 4):
# i18n: "ifcontains" is a keyword
raise error.ParseError(_("ifcontains expects three or four arguments"))
@@ -340,8 +353,10 @@ def ifcontains(context, mapping, args):
elif len(args) == 4:
yield _evalifliteral(args[3], context, mapping)
def ifeq(context, mapping, args):
+ """:ifeq(expr1, expr2, then[, else]): Conditionally execute based on
+ whether 2 items are equivalent."""
if not (3 <= len(args) <= 4):
# i18n: "ifeq" is a keyword
raise error.ParseError(_("ifeq expects three or four arguments"))
@@ -352,8 +367,9 @@ def ifeq(context, mapping, args):
elif len(args) == 4:
yield _evalifliteral(args[3], context, mapping)
def join(context, mapping, args):
+ """:join(list, sep): Join items in a list with a delimiter."""
if not (1 <= len(args) <= 2):
# i18n: "join" is a keyword
raise error.ParseError(_("join expects one or two arguments"))
@@ -374,18 +390,21 @@ def join(context, mapping, args):
yield joiner
yield x
def label(context, mapping, args):
+ """:label(label, expr): Apply a label to generated content. Content with
+ a label applied can result in additional post-processing, such as
+ automatic colorization."""
if len(args) != 2:
# i18n: "label" is a keyword
raise error.ParseError(_("label expects two arguments"))
# ignore args[0] (the label string) since this is supposed to be a a no-op
yield _evalifliteral(args[1], context, mapping)
def revset(context, mapping, args):
- """usage: revset(query[, formatargs...])
- """
+ """:revset(query[, formatargs...]): Execute a revision set query. See
+ :hg:`help revset`."""
if not len(args) > 0:
# i18n: "revset" is a keyword
raise error.ParseError(_("revset expects one or more arguments"))
@@ -412,8 +431,9 @@ def revset(context, mapping, args):
return templatekw.showlist("revision", revs, **mapping)
def rstdoc(context, mapping, args):
+ """:rstdoc(text, style): Format ReStructuredText."""
if len(args) != 2:
# i18n: "rstdoc" is a keyword
raise error.ParseError(_("rstdoc expects two arguments"))
@@ -422,10 +442,10 @@ def rstdoc(context, mapping, args):
return minirst.format(text, style=style, keep=['verbose'])
def shortest(context, mapping, args):
- """usage: shortest(node, minlength=4)
- """
+ """:shortest(node, minlength=4): Obtain the shortest representation of
+ a node."""
if not (1 <= len(args) <= 2):
# i18n: "shortest" is a keyword
raise error.ParseError(_("shortest() expects one or two arguments"))
@@ -474,8 +494,9 @@ def shortest(context, mapping, args):
if len(shortest) <= length:
return shortest
def strip(context, mapping, args):
+ """:strip(text[, chars]): Strip characters from a string."""
if not (1 <= len(args) <= 2):
# i18n: "strip" is a keyword
raise error.ParseError(_("strip expects one or two arguments"))
@@ -485,8 +506,10 @@ def strip(context, mapping, args):
return text.strip(chars)
return text.strip()
def sub(context, mapping, args):
+ """:sub(pattern, replacement, expression): Perform text substitution
+ using regular expressions."""
if len(args) != 3:
# i18n: "sub" is a keyword
raise error.ParseError(_("sub expects three arguments"))
@@ -495,8 +518,10 @@ def sub(context, mapping, args):
src = stringify(_evalifliteral(args[2], context, mapping))
yield re.sub(pat, rpl, src)
def startswith(context, mapping, args):
+ """:startswith(pattern, text): Returns the value from the "text" argument
+ if it begins with the content from the "pattern" argument."""
if len(args) != 2:
# i18n: "startswith" is a keyword
raise error.ParseError(_("startswith expects two arguments"))
@@ -507,9 +532,9 @@ def startswith(context, mapping, args):
return ''
def word(context, mapping, args):
- """return nth word from a string"""
+ """:word(number, text[, separator]): Return the nth word from a string."""
if not (2 <= len(args) <= 3):
# i18n: "word" is a keyword
raise error.ParseError(_("word expects two or three arguments, got %d")
% len(args))