# HG changeset patch
# User Jordi Gutiérrez Hermoso <jordigh@octave.org>
# Date 1707942104 18000
# Node ID 92c7765931e09903cbc91a4d0c9546ace80f64a9
# Parent  0e063a9b764abae9d6b9d481b48286a7316051eb
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!

diff -r 0e063a9b764a -r 92c7765931e0 mercurial/helptext/color.txt
--- 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
diff -r 0e063a9b764a -r 92c7765931e0 mercurial/templatefuncs.py
--- 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"))