On 09/10/2026 12:57, Pádraig Brady wrote:
On 09/10/2026 08:52, Collin Funk wrote:
Eli Schwartz <[email protected]> writes:
to disable bold/underline/links in help text, but I think the underlying
principle is the same and I don't really know that I understand the
rationale for assuming by default that it will be read by less or, more
pertinently, that users have configured less to get output that doesn't
look like this:
I think the assumption was that people typically be outputting to a
terminal, even if the program was piped. E.g., the following:
$ chroot --help | grep -F userspec
Would emit the option with the link included.
Also the more general point that one generally doesn't
want to programmatically process --help output,
apart from piping to a pager.
Yes, because of that and the other reports, I think something like this
is best:
diff --git a/src/system.h b/src/system.h
index 84be742ff..5646754b5 100644
--- a/src/system.h
+++ b/src/system.h
@@ -592,10 +592,11 @@ oputs_ (MAYBE_UNUSED char const *program, char const
*option)
#endif
if (help_no_sgr == -1)
{
- /* Note we don't consult isatty() since usually you
- would want markup when piping to grep/less etc. */
- char const *term = getenv ("TERM");
- help_no_sgr = (!term || !*term || streq (term, "dumb"));
+ char const *term;
+ help_no_sgr = (isatty (STDOUT_FILENO)
+ ? (!(term = getenv ("TERM")) || !*term
+ || streq (term, "dumb"))
+ : !getenv ("IN_HELP2MAN"));
}
if (help_no_sgr)
{
But lets see what Pádraig thinks.
Ok fair enough. Let's be more conservative here.
Users won't get links if using a pager.
Leave it with me, and I'll come up with something along the lines of the above.
I'll apply the attached later.
thanks,
Padraig
From e74007118af3b09a71cabe2945a1ab6e9b2d5dfd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Sat, 10 Oct 2026 11:33:58 +0100
Subject: [PATCH] all: only markup --help when outputting to tty
Since v9.10 (Feb 2026) --help always outputs bold and hyperlinks
even when output was not a tty, as this was thought more useful
with pagers and grep etc. This change makes the more conservative
choice of only outputting markup to tty so that users who do not
have less setup to display color (-R), or users who enable color
by default in grep, get improved output (though without URLs etc.)
* src/system.h (oputs_): Call isatty() when not
forcing markup with $IN_HELP2MAN. Also reverse the
double negatives to a more natural form.
* man/local.mk: Remove redundant assignment of $TERM.
* doc/coreutils.texi (common options): Mention that --help markup
requires output to be a tty, and that $IN_HELP2MAN overrides that.
* NEWS: Mention the change in behavior.
---
NEWS | 4 ++++
doc/coreutils.texi | 9 ++++++---
man/local.mk | 2 +-
src/system.h | 22 ++++++++++++----------
4 files changed, 23 insertions(+), 14 deletions(-)
diff --git a/NEWS b/NEWS
index 2d7d9b3c9..028c6589f 100644
--- a/NEWS
+++ b/NEWS
@@ -50,6 +50,10 @@ GNU coreutils NEWS -*- outline -*-
** Changes in behavior
+ command --help output will no longer be marked up with bold or hyperlinks
+ when output is not a tty. E.g. paged --help output will no longer
+ contain URLs to the full online manual.
+
'env' and 'printenv' now quote printed environment variables only when
outputting to a terminal. The previous release enabled this for all
outputs by default, requiring setting QUOTING_STYLE=literal to disable.
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 2eb57d4b0..b774a4217 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -765,11 +765,14 @@ these programs, abbreviations of the long options are not always recognized.
@item --help
@opindex --help
@vindex TERM
+@vindex IN_HELP2MAN
@cindex help, online
Print a usage message listing all available options, then exit successfully.
-Help output may be marked up with terminal codes for formatting or
-hyperlinks, which can be disabled by unsetting the @env{TERM} environment
-variable, or setting it to the value @samp{dumb}.
+When outputting to a tty @option{--help} output may be marked up with
+terminal codes for formatting or hyperlinks, which can be disabled by
+unsetting the @env{TERM} environment variable, or setting it to the value
+@samp{dumb}. To force the use of markup when output is not a tty,
+e.g. when piping to a pager, set the @env{IN_HELP2MAN} environment variable.
@item --version
@opindex --version
diff --git a/man/local.mk b/man/local.mk
index 156b0e18c..00d24acc5 100644
--- a/man/local.mk
+++ b/man/local.mk
@@ -27,7 +27,7 @@ if HAVE_PERL
if BOLD_MAN_REFS
help2man_OPTS=--bold-refs
endif
-run_help2man = env IN_HELP2MAN=1 TERM=not_dumb $(PERL) -- \
+run_help2man = env IN_HELP2MAN=1 $(PERL) -- \
$(srcdir)/man/help2man --loose-indent $(help2man_OPTS)
else
run_help2man = $(SHELL) $(srcdir)/man/dummy-man
diff --git a/src/system.h b/src/system.h
index 84be742ff..bbe8f09a8 100644
--- a/src/system.h
+++ b/src/system.h
@@ -584,20 +584,22 @@ is_nul (void const *buf, size_t length)
static inline void
oputs_ (MAYBE_UNUSED char const *program, char const *option)
{
- static int help_no_sgr =
-#if ! defined MANUAL_URL && ! defined BOLD_MAN_REFS
- 1; /* Disable. */
-#else
+ static int help_markup =
+#if defined MANUAL_URL || defined BOLD_MAN_REFS
-1; /* Lookup. */
+#else
+ 0; /* Disable. */
#endif
- if (help_no_sgr == -1)
+ if (help_markup == -1)
{
- /* Note we don't consult isatty() since usually you
- would want markup when piping to grep/less etc. */
- char const *term = getenv ("TERM");
- help_no_sgr = (!term || !*term || streq (term, "dumb"));
+ /* Note one generally would want markup when piping to grep/less etc.
+ but we're conservative here for now, and only markup to tty. */
+ char const *te;
+ help_markup = (isatty (STDOUT_FILENO)
+ ? ((te = getenv ("TERM")) && *te && !streq (te, "dumb"))
+ : getenv ("IN_HELP2MAN") != NULL);
}
- if (help_no_sgr)
+ if (! help_markup)
{
fputs (option, stdout);
return;
--
2.55.0
