Hi Pádraig, 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. 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. --- 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. --- --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. --- It feels weird to me that individual options have their links — from which of course it's easy to navigate to the top of the documentation — but there's no direct link to the top. Maybe some piece of text near the very beginning of --help's output (e.g. the progname "ls" itself) could be a link there (and maybe also boldened)? --- There are a few https: links, as well as an implicit mailto:, at the bottom of --help's output. They could be OSC8'ified. Advantages would be: the link would still work - if the window is made narrower and the terminals chops off the data there, - if a terminal falsely believes that the trailing '>' is also part of the URL, - if a terminal doesn't autodetect URLs at all, (I'm not sure which terminals belong to the above categories, maybe some categories are empty or negligible), - if displayed with "less -R" in a narrow window, and part of the URL is scrolled out (either horizontally or vertically). --- One more thing. And I think it was originally my mistake in the first versions of the "hyperlinks in terminals" doc, as well as probably the initial PoC "ls" patch that I sent here: Officially, OSC escape sequences are terminated with ST (ESC \). This is the only terminator mentioned in at least ECMA-48, DEC STD 070, and EK-VT520-RM. Terminating with BEL, to my best knowledge, originates from xterm, and due to its heavy use out there it was copied by presumably all the graphical terminals. So, while BEL works de facto, ST would be the de jure correct choice. Both for the file listing with the existing "ls --hyperlink" feature, as well as this new one. VTE's main developer is an advocate of using the correct form, to the extent that in some newer OSC features he outright refused to accept BEL (which I disagree with, but I joined him in pushing folks to using the official form). --- Feel free to ignore / reject any of these or schedule them for a later release; I think --help and --version pointing to the wrong place is the only one that shoud really be fixed before the release. thanks a lot, egmont On Sat, Jan 17, 2026 at 8:23 PM Pádraig Brady <[email protected]> wrote: > On 20/12/2025 20:04, Pádraig Brady wrote: > > tl;dr with the attached you can follow links from: src/ls --help > > > > Most users don't use the info reader, > > but we do have a comprehensive 100K word manual > > that is accessible in any web browser. > > > > There is always the balance of not overwhelming users with too much info > > in --help / man pages, but ideally --help should also be > > an index to the more complete info online. > > > > The <command>-<option> combo is a perfect index into this full manual, > > and I've recently prepared the full online manual to support > > indexing to the appropriate part by appending a #<command>-<option> > > to any of the manual URLs. > > > > To complete the connection, I've attached here an adjustment, > > for now just to ls for illustration / discussion. > > With this you should be able to click or ctrl-click > > on each of the --options to get further detail online. > > I.e. you can following links from: src/ls --help > > > > Notes: > > > > We can configure this to access a local manual through file://... urls > > I've tested this and it works fine. > > > > Having each --option hyperlinked also gives a visual distinction > > between the --option text and description, which makes --help > > quite a bit easier to read IMHO. > > > > We only output --option links if stdout is a tty currently, > > though it would be nice to support piping to e.g., less -R. > > Perhaps keying on stdin would be better then, or maybe support > --help[=WHEN], > > though options on --help do seem like overkill. > > > > hyperlinks are very well supported in terminals now, > > and if not, the fallback of just showing the link text is fine. > > > > This will result in each option being translated separately. > > That seems better anyway, and is something we've already been > > gradually adjusting to over the last few years. > > Many of the existing translations will not need to change. > > > > I've not looked into propagating these URLs to man pages. > > It would be useful if man pages did support it, but after a very > > quick search it seems that they might not, which is fine but a pity. > > > > This is just a quick patch for discussion, and not yet ready for merging. > > The full patch set is now ready for merging > which I intend to do before the release next week. > > It's large and mostly boring, so I made it available at: > https://github.com/coreutils/coreutils/compare/master...pixelb:help-markup > > The main change from the above discussion is that the hyperlinks > are now propagated through to the man pages, and there are a > set of patches to our vendored help2man to support that. > > If you want to inspect it locally you can do: > > git clone -b help-markup https://github.com/pixelb/coreutils.git > > If you want to test a build, the easiest is to use: > > wget https://pixelbeat.org/cu/coreutils-9.9.221-05e42.tar.xz > tar -xf coreutils-9.9.221-05e42.tar.xz > cd coreutils-9.9.221-05e42 > ./configure --quiet && make -j $(nproc) > > Then the following should show clickable links: > > src/ls --help > man man/ls.1 > > Note the previously marked up HTML is already on gnu.org > so the default links should work fine. > If you want to test against local only html, you can: > > ./configure --quiet > --enable-manual-url=file://$PWD/doc/manual/coreutils.html > make > make web-manual > > cheers, > Padraig >
