doc: document that labels must have a dot in them to have an effect
I noticed that the `hg topics` template has a bare `topic` label with
no dot, and that makes it useless, as such a label will never receive
any effect by the colour extension.
This dot has been required for a long time, at least since 2011, but
we never formally documented it!
--- a/mercurial/helptext/color.txt Wed Feb 14 22:55:11 2024 -0500
+++ b/mercurial/helptext/color.txt Wed Feb 14 15:21:44 2024 -0500
@@ -63,10 +63,11 @@
Text receives color effects depending on the labels that it has. Many
default Mercurial commands emit labelled text. You can also define
your own labels in templates using the label function, see :hg:`help
-templates`. A single portion of text may have more than one label. In
-that case, effects given to the last label will override any other
-effects. This includes the special "none" effect, which nullifies
-other effects.
+templates`. In order to receive effects, labels must have a dot, such
+as `log.secret` or `branch.active`. A single portion of text may have
+more than one label. In that case, effects given to the last label
+will override any other effects. This includes the special "none"
+effect, which nullifies other effects.
Labels are normally invisible. In order to see these labels and their
position in the text, use the global --color=debug option. The same
--- a/mercurial/templatefuncs.py Wed Feb 14 22:55:11 2024 -0500
+++ b/mercurial/templatefuncs.py Wed Feb 14 15:21:44 2024 -0500
@@ -439,9 +439,10 @@
@templatefunc(b'label(label, expr)', requires={b'ui'})
def label(context, mapping, args):
- """Apply a label to generated content. Content with
- a label applied can result in additional post-processing, such as
- automatic colorization."""
+ """Apply a label to generated content. Content with a label
+ applied can result in additional post-processing, such as
+ automatic colorization. In order to receive effects, labels must
+ have a dot, such as `log.secret` or `branch.active`."""
if len(args) != 2:
# i18n: "label" is a keyword
raise error.ParseError(_(b"label expects two arguments"))