h/fish-shell
1
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2026-04-25 20:41:15 -03:00
Code Issues Packages Projects Releases Wiki Activity

Reference more non-fish shell builtins that have relevant differences

Browse Source 
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 think we should can sacrifice a bit of the native fish-scripting
experience in exchange for playing nicer with other shells. 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, let's at least have `exec.rst` reference the system variant.

[Linux man-pages]: https://www.kernel.org/doc/man-pages/

Closes #10376
This commit is contained in:
Johannes Altmanninger
2024-03-16 16:45:00 +01:00
parent af5afe20c2
commit 414d9a1eb1
16 changed files with 61 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc_src/cmds/umask.rst
View File

@@ -14,6 +14,11 @@ Synopsis
Description
-----------
.. only:: builder_man
NOTE: This page documents the fish builtin ``umask``.
To see the documentation on any non-fish versions, use ``command man umask``.
``umask`` displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files.
The umask may be expressed either as an octal number, which represents the rights that will be removed by default, or symbolically, which represents the only rights that will be granted by default.