On 18/01/2026 03:34, Collin Funk wrote:
Hi Egmont,
Thank you very much for the detailed reviews in this thread, including
this one.
Egmont Koblinger <[email protected]> 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.
Linking to the web is the most general though, so I thought it the best default.
If we can't keep a static web site available then the project is dead anyway
IMHO.
I'm optimistic though, given there are many solutions to this separate issue.
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.
I'll think about the hostname a bit more.
The main reason for adding the hostname in the file:// url
for `ls --hyper` output, is so that if you click on it from
a remote ssh session for example, you're given an error
"could not open address" etc. so that you're not inadvertently
opening local files.
However here the case is different.
Often the html file might exist locally as the html file would
be in a standard location, especially if ssh'ing among
similar systems. Also there is no harm in opening
a wrong file here, apart from possibly out of date info.
If the file doesn't exist locally, you'll still get the error.
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);
}
My thinking on linking of --help and --version
was to link to the most info possible.
I.e. the single node for that command.
I'm not sure it's that useful to link to common options here.
I'll think about it.
Anyway the main thing with these was to keep the markup consistent with other
options.
I don't know enough about terminals to comment on the rest of your
message, sorry. :)
I'll probably change to the more standarised URL delimiters (ST rather than
BEL).
I've already supported that in help2man anyway.
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.
Mentioned in another mail I'll probably use HELP_NO_MARKUP.
thanks!
Padraig
