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/*.
This introduces a new variable, $fish_color_option, that can be used
to highlight options differently.
Options are tokens starting with `-`, but only up to (and including!)
the first `--`.
Fixes#8292.
This uses a bit of javascript to add copy buttons, so you can directly
copy all the code in a given block to the clipboard!
For codeblocks without prompts, it just copies all the code, for
blocks with prompts, it copies all the lines after prompts, under the
assumption that that's the code to be executed.
It would give you *all* the lines, so the output wouldn't be
interleaved like it is in the html, but good enough.
The buttons appear on hover, so they aren't usable on phones, but
since you won't really have a clipboard on phones and I have no idea
how to make them not always in front of the text otherwise: Eh.
I'm not in love with the javascript here, but it'll do.
* 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.
That `find` example is a bit dated and awkward, and doesn't really fit
the section.
We also don't want to point people to `?` because we want to remove it.
* 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
For some reason I've seen one version of firefox use this over the one
we set in pydoctheme.css. Since we set it there in both light and dark
mode, this one should not be used.
This is opt-in through a new feature flag "ampersand-nobg-in-token".
When this flag and "qmark-noglob" are enabled, this command no longer
needs quoting:
curl https://example.com/thing?foo=bar&duran=duran
Compared to the previous approach e1570a4 ("Let '&' only separate as
the first char of a word"), this has some advantages:
1. "&&" and "&>" are no longer affected. They are still special, even
if used between tokens without spaces, like "echo bar&>foo".
Maybe this is not really *better*, but it avoids risking to annoy
users by breaking the old variant.
2. "&" is still special if at the end of a token, like in "sleep 1&".
Word movement is not affected by the semantics change, so Alt-F and
friends still stop at every "&".
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.
Still not happy with this, it's overwhelming!
Might have to split this into two - one with simple paths and rough
descriptions, and one with the full scoop for experts?
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
Instead of having a toctree after the "index", just append the
important documents directly. Having one pdf file with different
chapters and sections and such feels better.
This allows
sphinx-build -blinkcheck . /dev/null
To be used without getting rate-limited to hell by github because the
release notes include hundreds of links to our own issues. Just assume
all issue numbers are valid.
pdflatex simply doesn't cut it.
This still results in an awkward pdf that starts with "Further
Reading" (the intro section is placed before it, but doesn't have a
chapter marker!) and ends with a massive "Other help pages" chapter
that includes *the entire rest of the docs*.
But it's generally readable and acceptably formatted (with a lot of
empty pages in between).
* 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.
First, I changed "the escape key" to :kbd:`Esc`. This makes this information
easier to find when scanning the docs because it stands out and because it is
more consistent with the docs's formatting of keyboard keys.
Additionally, emphasize that escape/page-down can be used to edit
the original search sting.
Finally, I added a link from the FAQ to history-search to make this mechanism
easier to discover.
This was all to address confusion in former zsh and bash users as to how to
edit a search that is in progress, but this will also help new users. See
https://github.com/fish-shell/fish-shell/pull/6686#issuecomment-872960760
Especially in dark-mode this was often too close to the background.
Should make it easier to read.
As always, colors not checked for artistic merit for I have none.
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
This set "clear: both", which resulted in code blocks sometimes being
pushed down a lot, resulting in weird empty space.
Just undo it, I have no idea why it's there, presumably it makes sense
with sphinx' stock theme?
This spoke of "--bold" and "-b", which are two different things - "-b"
is short for "--background", bold is "-o".
Instead let's just mention the long versions of all the switches.
See #8053.
A bunch of our variables are only relevant for interactive use, but
this is two whole sections on them. Simply move them inside "Syntax
highlighting" and leave the link in Special Variables.
* Try to set LC_CTYPE to something UTF-8 capable
When fish is started with LC_CTYPE=C (even just effectively, often via
LC_ALL=C!), it's basically broken. There's no way to handle non-ASCII
characters with a C locale unless we want to write our
locale-independent replacements for all of the system functions.
Since we're not going to do that, let's try to find *some locale* for
LC_CTYPE.
We already do that in __fish_setlocale, but that's
- a bit of a weird thing that reads unstandardized system
configuration files
- allows setting locale to C explicitly
So it's still easily possible to end up in a broken configuration.
Now, the issue with this is that there is (AFAICT) no portable way to
get a list of all allowed locales and C.UTF-8 is not standardized, so
we have no one locale to fall back on and are forced to try a few. The
list we have here is quite arbitrary, but it's a start.
Python does something similar and only tries C.UTF-8, C.utf8 and
"UTF-8".
Once C.UTF-8 is (hopefully) standardized, that will just start
working (tm).
Note that we do not *export* the fixed LC_CTYPE variable, so external
programs still have to deal with the C locale, but we have no real
business messing with the user's environment.
To turn it off: $fish_allow_singlebyte_locale, if set to something true (like "1"),
will re-run the locale initialization and skip the bit where we force
LC_CTYPE to be utf8-capable.
This is mainly used in our tests, but might also be useful if people
are trying to do something weird.
