doc: pretty-formats: separate parameters from placeholders
Commit a57523428b4 (pretty: support padding placeholders, %< %> and %><, 2013-04-19) introduced columnated place holders. These placeholders can be confusing as they contain `<` and `>` characters as part of their placeholders adjacent to the `<N>` parameters. Add spaces either side of the `<N>` parameters in the title line. The code (strtol) will consume any spaces around the number values (assuming they are passed as a quoted string with spaces). Note that the spaces are optional. Subsequent commits will clarify other confusions. Signed-off-by: Philip Oakley <philipoakley@iee.email> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Philip Oakley committed
Jan 19, 2023 at 18:18 UTC
d664a7ad20f9cb013f4c53654b76973612a89991
1 file changed
+9
-6
Documentation/pretty-formats.txt
+9
-6
@@ -146,24 +146,27 @@ The placeholders are:
146
'%m':: left (`<`), right (`>`) or boundary (`-`) mark
147
'%w([<w>[,<i1>[,<i2>]]])':: switch line wrapping, like the -w option of
148
linkgit:git-shortlog[1].
149
-'%<(<N>[,trunc|ltrunc|mtrunc])':: make the next placeholder take at
149
+'%<( <N> [,trunc|ltrunc|mtrunc])':: make the next placeholder take at
150
least N columns, padding spaces on
151
the right if necessary. Optionally
152
truncate at the beginning (ltrunc),
153
the middle (mtrunc) or the end
154
(trunc) if the output is longer than
155
- N columns. Note that truncating
155
+ N columns.
156
+ Note 1: that truncating
157
only works correctly with N >= 2.
157
-'%<|(<N>)':: make the next placeholder take at least until Nth
158
+ Note 2: spaces around the N
159
+ values are optional.
160
+'%<|( <N> )':: make the next placeholder take at least until Nth
161
columns, padding spaces on the right if necessary
159
-'%>(<N>)', '%>|(<N>)':: similar to '%<(<N>)', '%<|(<N>)' respectively,
162
+'%>( <N> )', '%>|( <N> )':: similar to '%<( <N> )', '%<|( <N> )' respectively,
163
but padding spaces on the left
161
-'%>>(<N>)', '%>>|(<N>)':: similar to '%>(<N>)', '%>|(<N>)'
164
+'%>>( <N> )', '%>>|( <N> )':: similar to '%>( <N> )', '%>|( <N> )'
165
respectively, except that if the next
166
placeholder takes more spaces than given and
167
there are spaces on its left, use those
168
spaces
166
-'%><(<N>)', '%><|(<N>)':: similar to '%<(<N>)', '%<|(<N>)'
169
+'%><( <N> )', '%><|( <N> )':: similar to '%<( <N> )', '%<|( <N> )'
170
respectively, but padding both sides
171
(i.e. the text is centered)
172