Re: RFC: Adding hyperlinks from --help to the full manual
From:
Collin Funk
Subject:
Re: RFC: Adding hyperlinks from --help to the full manual
Date:
Sat, 17 Jan 2026 19:34:04 -0800
User-agent:
Gnus/5.13 (Gnus v5.13)
Hi Egmont,
Thank you very much for the detailed reviews in this thread, including
this one.
Egmont Koblinger <egmont@gmail.com> writes:
> Thanks a lot for your work! I'm truly curious how people will like this
> option, and if other tools will follow.
>
> Some random feedback (by checking the behavior; not planning to look at the
> patches):
>
> ---
>
> Back to the file: vs. https: discussion for a sec. Disadvantage of https:,
> as we've already stated, is that the network might be down. Also, the
> version on the web might be newer than the running version, but that's
> unlikely to cause problems.
That is my largest worry, since gnu.org is down quite frequently.
> We haven't pointed out issues with file: though. It's fine locally, but
> troublesome across ssh.
>
> The "hyperlink in terminals" doc strongly recommends to fill in the
> hostname (((well, at one place it "requests" and then later it tells what
> to do if it's not there; it's not a formal documentation with RFC 2119-like
> "MUST" etc. wording or formal ABNF spec or alike))), which "ls" does for
> the actual file listing, but not for --help. This means that across ssh,
> if the two systems happen to use the same doc dir, the local counterpart
> could be loaded as a false positive match. Which could be convenient, but
> could easily point to an _older_ version of the manual, which is more
> likely to be confusing (e.g. missing option, broken anchor) than pointing
> to a _newer_ doc (as it can happen with https:).
>
> If "ls" filled out the hostname, such false positives couldn't happen,
> meaning that across ssh you'd never be able to access the doc.
>
> I don't have a conclusion here. Each possible approach (https:, file:
> without hostname, file: with hostname) have their pros and cons here; none
> of them are perfect. So I'm just leaving this here as an FYI.
Good point, I didn't consider it in an ssh session. I assume using
gethostname, like 'ls --hyperlinks' does, would be fine here.
> ---
>
> The html docs weren't built for me and I couldn't quickly figure out why.
> I haven't spent more than a minute investigating. If you happen to have a
> guess which software might be missing, which line of ./configure's output I
> should look at, I'd appreciate that. Anyway, it's probably just a user
> error on my side, not an actionable feedback.
>
> ---
I think I see what went wrong here. I'll push a patch for that soon.
>
> --help and --version don't point to the page describing those options.
>
> I think the first version didn't suffer from this problem, IIRC there they
> were treated as exceptions, now they follow the same link pattern than all
> other options.
>
> ---
Good catch, I think we should cleanup the hrefs on the "Common Options"
page [1], then adjust this snippet of code to not use the program name:
if (STREQ_LEN (option_text, "--help", 6)
|| STREQ_LEN (option_text, "--version", 9))
{
printf ("\033]8;;%s%s#%s%.*s", PACKAGE_URL,
url_program, url_program, (int) anchor_len, option_text);
}
I don't know enough about terminals to comment on the rest of your
message, sorry. :)
Anyways, one more thing I'm curious about. Should HELP_NO_SGR be named
to something a bit more friendly? I did not know what SGR meant until I
looked it up. Or was it strictly meant for internal use, e.g., when
parsing --help is needed? If not, I was thinking a name like
HELP_NO_LINKS or similar would be more self-explanatory.
Collin
[1]
https://www.gnu.org/software/coreutils/manual/html_node/index.html#toc-Common-options