Mercurial > hg
annotate mercurial/help/templates.txt @ 20689:401f9b661a2d
doc: show short description of each commands in generated documents
Before this patch, short description of each commands is not shown in
generated documents (HTML file and UNIX man page). This omitting may
prevent users from understanding about commands.
This patch show it as the 1st paragraph in the help section of each
commands. This style is chosen because:
- showing it as the section title in "command - short desc" style
disallows referencing by "#command" in HTML file: in "en" locale,
hyphen concatenated title is used as the section ID in HTML file
for this style
- showing it as the 1st paragraph in "command - short desc" style
seems to be redundant: "command" appears also just before as the
section title
- showing it just after synopsis like "hg help command" seems not to
be reasonable in UNIX man page
This patch just writes short description ("d['desc'][0]") before "::",
because it should be already "strip()"-ed in "get_desc()", or empty
string for the command without description.
author | FUJIWARA Katsunori <foozy@lares.dti.ne.jp> |
---|---|
date | Tue, 11 Mar 2014 14:36:40 +0900 |
parents | 01a75c9d5b5e |
children | cce404b0c918 |
rev | line source |
---|---|
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
1 Mercurial allows you to customize output of commands through |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
2 templates. You can either pass in a template from the command |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
3 line, via the --template option, or select an existing |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
4 template-style (--style). |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
5 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
6 You can customize output for any "log-like" command: log, |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
7 outgoing, incoming, tip, parents, heads and glog. |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
8 |
19126
5c5152af0d15
log-style: add a log style that is default+phase (issue3436)
Iulian Stana <julian.stana@gmail.com>
parents:
18747
diff
changeset
|
9 Five styles are packaged with Mercurial: default (the style used |
5c5152af0d15
log-style: add a log style that is default+phase (issue3436)
Iulian Stana <julian.stana@gmail.com>
parents:
18747
diff
changeset
|
10 when no explicit preference is passed), compact, changelog, phases |
11034
3b89899934a6
log: document the new xml style
Dan Connolly <http://www.w3.org/People/Connolly/>
parents:
10759
diff
changeset
|
11 and xml. |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
12 Usage:: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
13 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
14 $ hg log -r1 --style changelog |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
15 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
16 A template is a piece of text, with markup to invoke variable |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
17 expansion:: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
18 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
19 $ hg log -r1 --template "{node}\n" |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
20 b56ce7b07c52de7d5fd79fb89701ea538af65746 |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
21 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
22 Strings in curly braces are called keywords. The availability of |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
23 keywords depends on the exact context of the templater. These |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
24 keywords are usually available for templating a log-like command: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
25 |
13585
2e80d495592a
templates: generate keyword help dynamically
Patrick Mezard <pmezard@gmail.com>
parents:
13498
diff
changeset
|
26 .. keywordsmarker |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
27 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
28 The "date" keyword does not produce human-readable output. If you |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
29 want to use a date in your output, you can use a filter to process |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
30 it. Filters are functions which return a string based on the input |
10759
9f6e30a89f11
help: point out need for stringification
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
10066
diff
changeset
|
31 variable. Be sure to use the stringify filter first when you're |
9f6e30a89f11
help: point out need for stringification
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
10066
diff
changeset
|
32 applying a string-input filter to a list-like input variable. |
9f6e30a89f11
help: point out need for stringification
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
10066
diff
changeset
|
33 You can also use a chain of filters to get the desired output:: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
34 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
35 $ hg tip --template "{date|isodate}\n" |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
36 2008-08-21 18:22 +0000 |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
37 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
38 List of filters: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
39 |
13591
264f292a0c6f
templatefilters: move doc from templates.txt to docstrings
Patrick Mezard <pmezard@gmail.com>
parents:
13585
diff
changeset
|
40 .. filtersmarker |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
41 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
42 Note that a filter is nothing more than a function call, i.e. |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
43 ``expr|filter`` is equivalent to ``filter(expr)``. |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
44 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
45 In addition to filters, there are some basic built-in functions: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
46 |
18582
ef78450c8df6
templater: add get() function to access dict element (e.g. extra)
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
18465
diff
changeset
|
47 - date(date[, fmt]) |
ef78450c8df6
templater: add get() function to access dict element (e.g. extra)
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
18465
diff
changeset
|
48 |
ef78450c8df6
templater: add get() function to access dict element (e.g. extra)
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
18465
diff
changeset
|
49 - fill(text[, width]) |
ef78450c8df6
templater: add get() function to access dict element (e.g. extra)
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
18465
diff
changeset
|
50 |
ef78450c8df6
templater: add get() function to access dict element (e.g. extra)
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
18465
diff
changeset
|
51 - get(dict, key) |
ef78450c8df6
templater: add get() function to access dict element (e.g. extra)
Benoit Boissinot <benoit.boissinot@ens-lyon.org>
parents:
18465
diff
changeset
|
52 |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
53 - if(expr, then[, else]) |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
54 |
20531
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
55 - ifcontains(expr, expr, then[, else]) |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
56 |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
57 - ifeq(expr, expr, then[, else]) |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
58 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
59 - join(list, sep) |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
60 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
61 - label(label, expr) |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
62 |
20531
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
63 - revset(query[, formatargs]) |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
64 |
18747
f5db3092790f
hgweb: generate HTML documentation
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents:
18582
diff
changeset
|
65 - rstdoc(text, style) |
f5db3092790f
hgweb: generate HTML documentation
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents:
18582
diff
changeset
|
66 |
20531
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
67 - shortest(node) |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
68 |
19390
3af3a165db18
templater: sort functions alphabetically, as filters are
Alexander Plavin <me@aplavin.ru>
parents:
19330
diff
changeset
|
69 - strip(text[, chars]) |
3af3a165db18
templater: sort functions alphabetically, as filters are
Alexander Plavin <me@aplavin.ru>
parents:
19330
diff
changeset
|
70 |
3af3a165db18
templater: sort functions alphabetically, as filters are
Alexander Plavin <me@aplavin.ru>
parents:
19330
diff
changeset
|
71 - sub(pat, repl, expr) |
19330
867b9957d895
templater: add strip function with chars as an extra argument
Alexander Plavin <me@aplavin.ru>
parents:
19126
diff
changeset
|
72 |
18465
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
73 Also, for any expression that returns a list, there is a list operator: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
74 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
75 - expr % "{template}" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
76 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
77 Some sample command line templates: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
78 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
79 - Format lists, e.g. files:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
80 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
81 $ hg log -r 0 --template "files:\n{files % ' {file}\n'}" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
82 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
83 - Join the list of files with a ", ":: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
84 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
85 $ hg log -r 0 --template "files: {join(files, ', ')}\n" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
86 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
87 - Format date:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
88 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
89 $ hg log -r 0 --template "{date(date, '%Y')}\n" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
90 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
91 - Output the description set to a fill-width of 30:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
92 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
93 $ hg log -r 0 --template "{fill(desc, '30')}" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
94 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
95 - Use a conditional to test for the default branch:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
96 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
97 $ hg log -r 0 --template "{ifeq(branch, 'default', 'on the main branch', |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
98 'on branch {branch}')}\n" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
99 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
100 - Append a newline if not empty:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
101 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
102 $ hg tip --template "{if(author, '{author}\n')}" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
103 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
104 - Label the output for use with the color extension:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
105 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
106 $ hg log -r 0 --template "{label('changeset.{phase}', node|short)}\n" |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
107 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
108 - Invert the firstline filter, i.e. everything but the first line:: |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
109 |
3aa8b4b36b64
help: add documentation for new template functions
Sean Farley <sean.michael.farley@gmail.com>
parents:
13591
diff
changeset
|
110 $ hg log -r 0 --template "{sub(r'^.*\n?\n?', '', desc)}\n" |
20016
f4b3bdc3019e
help: adding example 'extras' printing to 'hg help templates'
Matthew Turk <matthewturk@gmail.com>
parents:
19390
diff
changeset
|
111 |
f4b3bdc3019e
help: adding example 'extras' printing to 'hg help templates'
Matthew Turk <matthewturk@gmail.com>
parents:
19390
diff
changeset
|
112 - Display the contents of the 'extra' field, one per line:: |
f4b3bdc3019e
help: adding example 'extras' printing to 'hg help templates'
Matthew Turk <matthewturk@gmail.com>
parents:
19390
diff
changeset
|
113 |
20170
574f3b6e0e8b
help: fix formatting of template example
Steve Hoelzer <shoelzer@gmail.com>
parents:
20016
diff
changeset
|
114 $ hg log -r 0 --template "{join(extras, '\n')}\n" |
20531
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
115 |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
116 - Mark the current bookmark with '*':: |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
117 |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
118 $ hg log --template "{bookmarks % '{bookmark}{ifeq(bookmark, current, \"*\")} '}\n" |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
119 |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
120 - Mark the working copy parent with '@':: |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
121 |
01a75c9d5b5e
help: add ifcontains, revset, and shortest to template help
Durham Goode <durham@fb.com>
parents:
20170
diff
changeset
|
122 $ hg log --template "{ifcontains(rev, revset('.'), '@')}\n" |