Includes harmonizing the display of options and arguments, standardising
terminology, using the envvar directive more broadly, adding help options to all
commands that support them, simplifying some language, and tidying up multiple
formatting issues.
string documentation is not changed.
man(1) uses lowercase placeholders but we usually don't. Additionally,
the new synopsis autoformatting only recognizes placeholders if they
are uppercase. Use uppercase for all placeholders.
Recent synopsis changes move from literal code blocks to
[RST line blocks]. This does not translate well to HTML: it's not
rendered in monospace, so aligment is lost. Additionally, we don't
get syntax highlighting in HTML, which adds differences to our code
samples which are highlighted.
We hard-wrap synopsis lines (like code blocks). To align continuation
lines in manpages we need [backslashes in weird places]. Combined with
the **, *, and `` markup, it's a bit hard to get the alignment right.
Fix these by moving synopsis sources back to code blocks and compute
HTML syntax highlighting and manpage markup with a custom Sphinx
extension.
The new Pygments lexer can tokenize a synopsis and assign the various
highlighting roles, which closely matches fish's syntax highlighing:
- command/keyword (dark blue)
- parameter (light blue)
- operator like and/or/not/&&/|| (cyan)
- grammar metacharacter (black)
For manpage output, we don't project the fish syntax highlighting
but follow the markup convention in GNU's man(1):
bold text type exactly as shown.
italic text replace with appropriate argument.
To make it easy to separate these two automatically, formalize that
(italic) placeholders must be uppercase; while all lowercase text is
interpreted literally (so rendered bold).
This makes manpages more consistent, see string-join(1) and and(1).
Implementation notes:
Since we want manpage formatting but Sphinx's Pygments highlighing
plugin does not support manpage output, add our custom "synopsis"
directive. This directive parses differently when manpage output is
specified. This means that the HTML and manpage build processes must
not share a cache, because the parsed doctrees are cached. Work around
this by using separate cache locations for build targets "sphinx-docs"
(which creates HTML) and "sphinx-manpages". A better solution would
be to only override Sphinx's ManualPageBuilder but that would take a
bit more code (ideally we could override ManualPageWriter but Sphinx
4.3.2 doesn't really support that).
---
Alternative solution: stick with line blocks but use roles like
:command: or :option: (or custom ones). While this would make it
possible to produce HTML that is consistent with code blocks (by adding
a bit of CSS), the source would look uglier and is harder to maintain.
(Let's say we want to add custom formatting to the [|] metacharacters
in HTML. This is much easier with the proposed patch.)
---
[RST line blocks]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
[backslashes in weird places]: https://github.com/fish-shell/fish-shell/pull/8626#discussion_r782837750
This corrects what looks like wrong alignment of some synopsis lines.
(I think the alignment is not a bad idea but it makes us do more
manual work, maybe we can automate that in future. We still need to
figure out how to translate it to HTML.)
"man -l build/user_doc/man/man1/history.1" before:
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-r | --regex] [-n | --index] [-q | --quiet] [-v | --invert]
PATTERN [STRING…]
and after:
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-r | --regex] [-n | --index] [-q | --quiet] [-v | --invert]
PATTERN [STRING…]
Also make the lines align the same way in the RST source by carefully
choosing the position of the backslash. I'm not sure why we used
two backslashes per line. Use only one; this gives us no choice
of where to put it so both source and man page output are aligned.
Change tabs to spaces to make the alignment in the source work.
The ellipsis is a grammar metacharacter, just like the []()|.
Write *FOO*… instead of *FOO…*, so the ellipsis is not underlined
in the man page. Not super sure about this one.
This matches the style in man(1) (except that we use the … ligature).
A previous iteration did the reverse (never use a space before the
ellipsis). That would be a smaller change.
We use plural "*OPTIONS*" more often than "*OPTION*...", so let's do
that everywhere.
In some other places where we do have an ellipsis, make sure to use
singular, since the ellipsis already means repetition. This change
is incomplete, and I'm not sure if this is worth it, since it's
subjective, so I might drop it.
Correct the grammar by moving the options after the command argument.
Also group the -c/--command and -p/--path pairs, to convey that the
short and long variants are equivalent.
While at it, consolidate the -C/--do-complete forms, like we usually
do.
One synopsis misrenders as
set [options] VARIABLE*[*INDICES]… VALUES…
Add a missing backslash to fix that. Also go back to uppercase
because I'm not sure why this was changed to lowercase.
Finally, remove the spurious ellipsis after VARIABLE[INDICES].
This element cannot be repeated. Multiple index values and ranges
can be specified but that's already implied by the plural INDICES.
For alteration we usually use "(a | b)", not "{a | b}".
While at it, instead of writing 4/6 subcommands in one line, write them
on separate lines, so it's very obvious that all these are separate
subcommands. We mainly use the (a | b) syntax for long/short options.
The -- is not special here and we don't mention it in other synopses.
It was originally added for a good reason in 98449fec5 (fix `math`
regression, 2017-07-14), along this addition to math.rst:
> You should always place a `--` flag separator before the expression. [...]
However, since 56d913453 (Cache math expressions, 2017-08-24) that
line was changed to
> You don't need to use `--` before the expression even if it begins with a minus sign [...]
Previously, when we got an unknown option with --ignore-unknown, we
would increment woptind but still try to read the same contents.
This means in e.g.
```
argparse -i h -- -ooo -h
```
The `-h` would also be skipped as an option, because after the first
`-o` getopt reads the other two `-o` and skips that many options.
This could be handled more extensively in wgetopt, but the simpler fix
is to just skip to the next argv entry once we have an unknown option
- there's nothing more we can do with it anyway!
Additionally, document this and clearly explain that we currently
don't transform the option.
Fixes#8637
Use the remaining_to_disclose count to determine if all completions
are shown (allows consistent behavior between short and long completion
lists).
Closes#8485
Currently,
set -q --unpath PATH
simply ignores the "--unpath" bit (and same for "--path").
This changes it, so just like exportedness you can check pathness.
Unless we use "complete --require-parameter", we must say "-w32",
not "-w 32", because the second "32" is a positional argument.
Notably, old options do not have this behavior, which is a bit weird,
see #8465
Taken from a discussion in #8459
* fish_key_reader: Simplify default output
It now only prints the bind statement. Timing information and such is
relegated to a separate "verbose" mode.
* Adjust fish_key_reader docs
* Adjust tests
Unlike in other shells, for-loops do not set $status if
1. the loop count is zero, or if
2. the loop body consists of only commands like "set" that don't
set $status.
POSIX for-loops always set an exit status (they set 0 if no loop
iterations). Following that would be awkward because it would add a
lot of complexity in combination with the 2 special cases above.
Document that "for" behaves the same as "set": it will pass through
existing $status, and also the last child's $status.
See the discussion in #8409
Unfortunately, currently :program: doesn't link to the program's page.
So we use the old-school :ref: again where we should link, i.e. for
everything that's not the program the current page is about.
Fixes#8438
Documents like fish-tutorial don't need the NAME portion below.
(they also shoudln't be in section 1! These should be section 7,
they aren't for programs.)
the manpage writer will skip NAME if given an empty sstring as
the description.
--
FISH-TUTORIAL(1) fish-shell FISH-TUTORIAL(1)
NAME
fish-tutorial - fish-shell tutorial
This fixes the indentation problem for the SYNOPSIS section by not
inserting the :: literal block. Format it the same way Sphinx does
their own manpages for commands.
Use more semantic markup, like :command:, so that commands are
highlighted in the man pages.
Split by sentence to give `man` a chance to ascertain lines.
Long-term, it should be possible to teach Sphinx to turn :command:s
into references and get us automatic links to articles for matching
cmds/*.
* commandline: Add --is-valid option to query whether it's syntactically complete
This means querying when the commandline is in a state that it could
be executed. Because our `execute` bind function also inserts a
newline if it isn't.
One case that's not handled right now: `execute` also expands
abbreviations, those can technically make the commandline invalid
again.
Unfortunately we have no real way to *check* without doing the
replacement.
Also since abbreviations are only available in command position when
you _execute_ them the commandline will most likely be valid.
This is enough to make transient prompts work:
```fish
function reset-transient --on-event fish_postexec
set -g TRANSIENT 0
end
function maybe_execute
if commandline --is-valid
set -g TRANSIENT 1
commandline -f repaint
else
set -g TRANSIENT 0
end
commandline -f execute
end
bind \r maybe_execute
```
and then in `fish_prompt` react to $TRANSIENT being set to 1.
* Add `set --function`
This makes the function's scope available, even inside of blocks. Outside of blocks it's the toplevel local scope.
This removes the need to declare variables locally before use, and will probably end up being the main way variables get set.
E.g.:
```fish
set -l thing
if condition
set thing one
else
set thing two
end
```
could be written as
```fish
if condition
set -f thing one
else
set -f thing two
end
```
Note: Many scripts shipped with fish use workarounds like `and`/`or`
instead of `if`, so it isn't easy to find good examples.
Also, if there isn't an else-branch in that above, just with
```fish
if condition
set -f thing one
end
```
that means something different from setting it before! Now, if
`condition` isn't true, it would use a global (or universal) variable of
te same name!
Some more interesting parts:
Because it *is* a local scope, setting a variable `-f` and
`-l` in the toplevel of a function ends up the same:
```fish
function foo2
set -l foo bar
set -f foo baz # modifies the *same* variable!
end
```
but setting it locally inside a block creates a new local variable
that shadows the function-scoped variable:
```fish
function foo3
set -f foo bar
begin
set -l foo banana
# $foo is banana
end
# $foo is bar again
end
```
This is how local variables already work. "Local" is actually "block-scoped".
Also `set --show` will only show the closest local scope, so it won't
show a shadowed function-level variable. Again, this is how local
variables already work, and could be done as a separate change.
As a fun tidbit, functions with --no-scope-shadowing can now use this to set variables in the calling function. That's probably okay given that it's already an escape hatch (but to be clear: if it turns out to problematic I reserve the right to remove it).
Fixes#565
Currently, if a "return" is given outside of a function, we'd just
throw an error.
That always struck me as a bit weird, given that scripts can also
return a value.
So simply let "return" outside also exit the script, kinda like "exit"
does.
However, unlike "exit" it doesn't quit an interactive shell - it seems
weird to have "return" do that as well. It sets $status, so it can be
used to quickly set that, in case you want to test something.
For builtins that have the same name as common commands, it might not
be entirely obvious that there is another page.
So, for those builtins, we add a note, but only in the man pages.
(exception is true and false because the note would be longer than the
page, and it's fridging true and false)
Fixes#8077.
`fish_config theme`:
- `list` to list all available themes (files in the two theme
directories - either the web_config/themes one or
~/.config/fish/themes!)
- `show` to show select (or all) themes right in the terminal - this
starts another fish that reads the theme file and prints the sample
text, manually colored
- `choose` to load a theme *now*, setting the variables globally
- `save` to load a theme and save the variables universally
- `dump` to write the current theme in .theme format (to stdout)
- `demo` to display the current theme
* string: Allow `collect --no-empty` to avoid empty ellision
Currently we still have that issue where
test -n (thing | string collect)
can return true if `thing` doesn't print anything, because the
collected argument will still be removed.
So, what we do is allow `--no-empty` to be used, in which case we
print one empty argument.
This means
test -n (thing | string collect -n)
can now be safely used.
"no-empty" isn't the best name for this flag, but string's design
really incentivizes reusing names, and it's not *terrible*.
* Switch to `--allow-empty`
`--no-empty` does the exact opposite for `string split` and split0.
Since `-a`/`--allow-empty` already exists, use it.
This introduces two functions to
- toggle a process prefix, used for adding "sudo"
- add a job suffix, used for adding "&| less"
Not sure if they are very useful; we'll see.
Closes#7905
The file is called "config.fish", not "init.fish". We'll call it
"configuration" now.
"Initialization" might be slightly more precise, but in an irritating
way.
Also some wording improvements to the section. In particular we now
mention config.fish *early*, before the whole shebang.
