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
