Un-hide documentation of non-fish shell builtins

[krobelus]

When writing scripts for other shells, it can be confusing and annoying
that our man function shadows other manual pages, for example exec(1p)
from Linux man-pages. I almost never want to see the fish variant for such
contended cases (which obviuosly don't include fish-specific commands like
string, only widely-known shell builtins).

For the contented cases like exec, the POSIX documentation is more
substantial and useful, since it describes a (sub)set of languages widely
used for scripting.

Because of this I think we should stop overriding the system's man pages.
Nowadays we offer exec -h as intuitive way to show the documentation for
the fish-specific command (note that help is not a good replacement because
it uses a web browser).

Looking through the contended commands, it seems like for most of them,
the fish version is not substantially different from the system version.
A notable exception is read but I don't think it's a very important one.

So I'm saying: we can sacrifice a bit of the native fish-scripting experience
in exchange for playing nicer with the outside world. I think the latter
is more important because scripting is not our focus, the way I see it.
So maybe put our manpath at the end.

In lieu of that, we should at least have exec.rst reference the system or
POSIX variants, which is what this draft patch does, to set the stage.

[faho]

The test documentation already includes something for this:

fish-shell/doc_src/cmds/test.rst

Lines 17 to 21 in 46cde6c

	.. only:: builder_man
	NOTE: This page documents the fish builtin ``test``.
	To see the documentation on the ``test`` command you might have,
	use ``command man test``.

And I think test is a good example for where we want to have our man page first - we're not 100% pure posix (we have extensions like floating point, other posixy shells may have other extensions, we may break what posix-compatibility we have - #10365).

Other builtins that are different from posix in ways that can catch people off-guard:

• read - this is substantially different and reasonably important
• bg - the other man page goes into detail on what the output looks like
• exec - it explains how it can open/close file descriptors, which ours does not do
• echo - does not have -s
• exit - talks about trap

These are important differences that make those manpages confusing when you are inside of fish.
So I don't think we should put our manpath last - you are inside fish, if you're looking for man test that should reflect what test would do.

It's fine to add links to the other man pages, tho I would do it like test does, or at least do it consistently. Personally I also don't think the link to POSIX is useful - it's not very easy to read and describes a weird maybe-subset of what is actually on your system.

[krobelus]

Fundamentally this is a political issue. I don't think you value my use case (wanting to write sh scripts, not fish) as much and at the same time I don't really empathize with people who write fish-specific scripts (beyond the occasional multi-line commandline)

[faho]

Yup, basically.

Fundamentally I don't believe that running man foo, which is the thing to get help - the way everything teaches you to get help in unix - in a running fish should give you the sh-version.

So this is confusing to 1. new people, who have only learned that you do man test to get information on "test" and 2. people already used to fish, who know that man test in fish gets you information on fish's test.

And if I write sh scripts, I fire up bash and do a lot of line-by-line testing, so I would be running man foo in that.

I don't really empathize with people who write fish-specific scripts (beyond the occasional multi-line commandline)

I like fish scripting and want it to be used more and easier to use and viable for more things. If I didn't like fish scripting I would probably not work on fish. I have to confess I am a bit taken aback by your position here.

---

My position stays: What this currently does (add mentions of the non-fish docs) is fine, I would make it consistent with what we already have in the test man page (either way around, tho I have a slight preference for adding it at the top and only in the man page) and I would probably ditch the posix link because it's not relevant.