github-mirror/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2024-11-25 18:03:37 +08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity
414d9a1eb1
fish-shell/doc_src/cmds
History
Johannes Altmanninger 414d9a1eb1 Reference more non-fish shell builtins that have relevant differences 
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
2024-04-20 13:34:08 +02:00
..
_.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
abbr.rst docs/abbr: Explain saving abbrs 2023-07-04 18:30:28 +02:00
alias.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
and.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
argparse.rst docs/argparse: Add some more examples, something on -x 2024-02-03 21:41:50 +01:00
begin.rst docs: omnibus cleanup 2022-03-12 00:21:13 +08:00
bg.rst docs: Improve bg docs 2023-06-05 18:26:13 +02:00
bind.rst shift-delete to delete current history search match 2024-04-13 20:23:51 +02:00
block.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
break.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
breakpoint.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
builtin.rst docs: Document type/builtin exit status 2022-09-30 18:50:14 +02:00
case.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
cd.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
cdh.rst docs: Add some more envvars to reference 2022-12-01 18:00:06 +01:00
command.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
commandline.rst fish_clipboard_paste: don't bypass pager search field. 2024-04-02 14:35:16 +02:00
complete.rst docs/complete: List --description with the options 2023-11-14 16:32:43 +01:00
contains.rst docs: omnibus cleanup 2022-03-12 00:21:13 +08:00
continue.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
count.rst docs synopsis: make all placeholder arguments uppercase 2022-01-19 22:56:41 +08:00
dirh.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
dirs.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
disown.rst docs: Clarify that disowned jobs won't fire on-process/job-exit 2024-03-19 16:39:37 +01:00
echo.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
else.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
emit.rst docs: omnibus cleanup 2022-03-12 00:21:13 +08:00
end.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
eval.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
exec.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
exit.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
false.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
fg.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
fish_add_path.rst docs/fish_add_path: Also clarify the examples 2023-04-04 17:55:10 +02:00
fish_breakpoint_prompt.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
fish_clipboard_copy.rst Document fish_clipboard_copy/paste 2022-10-19 20:10:26 +02:00
fish_clipboard_paste.rst Document fish_clipboard_copy/paste 2022-10-19 20:10:26 +02:00
fish_command_not_found.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
fish_config.rst docs: Turn off highlighting correctly in fish_config 2023-06-16 16:17:58 +02:00
fish_default_key_bindings.rst Create fish_[default|vi]_key_bindings documentation 2023-04-19 19:22:55 +02:00
fish_delta.rst Add a fish_delta helper function 2022-10-19 20:06:35 +02:00
fish_git_prompt.rst git prompt: Interpret values of "1", "yes" or "true" as true for bools instead of relying on defined-or-not (#9274) 2022-10-21 20:22:20 +02:00
fish_greeting.rst docs: fix double space in example fish_greeting 2024-01-06 15:26:20 +01:00
fish_hg_prompt.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
fish_indent.rst Teach fish_indent to only indent and unindent 2024-04-15 08:32:31 +02:00
fish_is_root_user.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
fish_key_reader.rst Extended & human-friendly keys 2024-04-02 14:35:16 +02:00
fish_mode_prompt.rst docs: standardise name for vi mode 2023-12-17 17:40:45 +08:00
fish_opt.rst Fix small typos 2023-11-18 18:27:25 -08:00
fish_prompt.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
fish_right_prompt.rst We no longer have two doc systems, move sphinx_doc_src back to doc_src 2020-02-19 17:00:35 -08:00
fish_should_add_to_history.rst docs: Add fish_should_add_to_history to commands list 2024-03-09 12:09:00 +01:00
fish_status_to_signal.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
fish_svn_prompt.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
fish_title.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
fish_update_completions.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
fish_vcs_prompt.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
fish_vi_key_bindings.rst docs: standardise name for vi mode 2023-12-17 17:40:45 +08:00
fish.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
for.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
funced.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
funcsave.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
function.rst docs: Clarify that disowned jobs won't fire on-process/job-exit 2024-03-19 16:39:37 +01:00
functions.rst functions --copy: store file and lineno (#9542) 2023-02-13 09:59:28 -06:00
help.rst docs: More about envvars 2023-01-09 20:33:37 +01:00
history.rst add history append subcommand 2024-04-15 08:31:16 +02:00
if.rst docs/if: Link to other builtins 2023-02-28 20:49:11 +01:00
isatty.rst Fix formatting for isatty 2022-10-19 20:10:26 +02:00
jobs.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
math.rst Fix rounding error on math docs 2024-01-30 20:12:56 +01:00
nextd.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
not.rst Document the ! (not) and . (source) aliases more 2024-04-20 13:34:08 +02:00
open.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
or.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
path.rst docs/path: Remove incorrect status comments 2023-08-24 18:06:03 +02:00
popd.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
prevd.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
printf.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
prompt_hostname.rst docs synopsis: add HTML highlighing and automate manpage markup 2022-01-19 22:56:41 +08:00
prompt_login.rst docs: omnibus cleanup 2022-03-12 00:21:13 +08:00
prompt_pwd.rst docs/prompt_pwd: Fix envvar linking 2022-12-30 14:31:32 +01:00
psub.rst docs: omnibus cleanup 2022-03-12 00:21:13 +08:00
pushd.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
pwd.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
random.rst docs: omnibus cleanup 2022-03-12 00:21:13 +08:00
read.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
realpath.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
return.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
set_color.rst docs: Fix markdown links 2023-11-22 18:42:34 +01:00
set.rst docs/set: Fix typo 2024-01-02 21:54:07 +01:00
source.rst Document the ! (not) and . (source) aliases more 2024-04-20 13:34:08 +02:00
status.rst Add status current-commandline 2022-10-26 12:15:02 -05:00
string-collect.rst Fix more lost string documentation 2022-05-14 10:05:02 +02:00
string-escape.rst string docs: format options and arguments in line with other pages 2022-03-12 22:22:02 +08:00
string-join.rst New -n flag for string join. (#8774) 2022-03-13 11:47:33 +01:00
string-join0.rst We no longer have two doc systems, move sphinx_doc_src back to doc_src 2020-02-19 17:00:35 -08:00
string-length.rst string docs: format options and arguments in line with other pages 2022-03-12 22:22:02 +08:00
string-lower.rst string docs: format options and arguments in line with other pages 2022-03-12 22:22:02 +08:00
string-match.rst docs/string: Add a -- example to the match section 2023-01-08 12:44:02 +01:00
string-pad.rst docs/string: Separate "pad" and "shorten" 2023-04-20 22:17:08 +02:00
string-repeat.rst Add documentation and release notes for #10282 2024-02-11 12:43:13 +01:00
string-replace.rst string docs: format options and arguments in line with other pages 2022-03-12 22:22:02 +08:00
string-shorten.rst docs/string: Separate "pad" and "shorten" 2023-04-20 22:17:08 +02:00
string-split.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
string-split0.rst We no longer have two doc systems, move sphinx_doc_src back to doc_src 2020-02-19 17:00:35 -08:00
string-sub.rst Fix more lost string documentation 2022-05-14 10:05:02 +02:00
string-trim.rst string docs: format options and arguments in line with other pages 2022-03-12 22:22:02 +08:00
string-unescape.rst We no longer have two doc systems, move sphinx_doc_src back to doc_src 2020-02-19 17:00:35 -08:00
string-upper.rst string docs: format options and arguments in line with other pages 2022-03-12 22:22:02 +08:00
string.rst Add documentation and release notes for #10282 2024-02-11 12:43:13 +01:00
suspend.rst docs: omnibus cleanup 2022-03-12 00:21:13 +08:00
switch.rst docs: More about envvars 2023-01-09 20:33:37 +01:00
test.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
time.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
trap.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
true.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00
type.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
ulimit.rst docs: Fix typos 2022-09-17 21:31:06 +08:00
umask.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
vared.rst docs: omnibus cleanup 2022-03-12 00:21:13 +08:00
wait.rst Reference more non-fish shell builtins that have relevant differences 2024-04-20 13:34:08 +02:00
while.rst docs: Use :doc: role when linking to commands 2022-09-24 10:56:43 +02:00