changeset 51390:92c7765931e0

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!
author Jordi Gutiérrez Hermoso <jordigh@octave.org>
date Wed, 14 Feb 2024 15:21:44 -0500
parents 0e063a9b764a
children a96ed440450e
files mercurial/helptext/color.txt mercurial/templatefuncs.py
diffstat 2 files changed, 9 insertions(+), 7 deletions(-) [+]
line wrap: on
line diff
--- 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"))