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.
Chrome says that's better, presumably because it can then tell how
large the image is before it's loaded. Not that this tiny image really
is a massive problem, but let's be good, not acceptable.
This led to pydoctheme.css being included *twice*, which led to
everything it included being included twice, which was annoying in
firefox when playing with the styles.
I don't *think* it had any performance impact?
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.
Otherwise there's this weird *gap*, where the sections are narrow even
tho there's plenty of space?
So you have this screen layout:
```table
| sidebar | text |
| sidebar | narr |
| sidebar | ower |
| sidebar | than |
| sidebar | need |
| sidebar | ed |
```
For some gosh-forsaken reason.
Prior to this change, a function with an on-job-exit event handler must be
added with the pgid of the job. But sometimes the pgid of the job is fish
itself (if job control is disabled) and the previous commit made last_pid
an actual pid from the job, instead of its pgroup.
Switch on-job-exit to accept any pid from the job (except fish itself).
This allows it to be used directly with $last_pid, except that it now
works if job control is off. This is implemented by "resolving" the pid to
the internal job id at the point the event handler is added.
Also switch to passing the last pid of the job, rather than its pgroup.
This aligns better with $last_pid.
This is an attempt to make these more visible - the intro section
explains what this is, and then we mention where to go, and after that
we go into installation and stuff.
I don't think putting "where to go" *after* the installation
instruction is correct, but maybe it is? For the time being, we keep
the order as it is.
fish_private_mode is active if set to something non-empty, but the docs
suggested checking if it is set at all. Switch the docs to match the
implementation through `test -n "$fish_private_mode"`
Fixes#8001
Apparently new sphinxen want to create an *additional* section
directory, so things end up in /usr/share/fish/man/man1/1, instead of /usr/share/fish/man/man1
Why? No idea.
I can't reproduce it but I'm told this section fixes it.
Fixes#7996
It's a bit weird to *have* to fire up a browser to get fish_config to
choose a prompt.
So this adds a `prompt` subcommand to `fish_config`:
- `fish_config prompt list` shows all the available prompt names
- `fish_config prompt show` demos the available sample prompts
- `fish_config prompt choose` sources a prompt
- `fish_config prompt save` makes the choice permanent
A bare `fish_config` or `fish_config browse` opens the web UI.
Part of #3625.
TODO: This shows the right prompt on a new line. Showing it in-line is awkward
to do because we'd have to move it to the right.
This prints a description of the "host". Currently that's
`(chroot:debianchroot) $USER@$hostname`
with the chroot part when needed.
This also switches the default and terlar prompts to use it, the other
prompts have slightly different coloring or logic here.
When building the docs with an old sphinx (like e.g. on Debian), this
would break links in the search results.
This happens because we've nabbed the searchtools.js from a sphinx to
add our special handling of short builtins like "and", "end", "cd" (as
part of #7757).
I don't believe this will change *a lot* in practice, so it's probably
still okay, but this hack is still worthwhile.
See #7946
Otherwise this would look ugly by stopping the gradient after the
content, so in e.g. the `end` or `false` page it would leave an ugly stripe at
the bottom.
* math: Make function parentheses optional
It's a bit annoying to use parentheses here because that requires
quoting or escaping.
This allows the parens to be omitted, so
math sin pi
is the same as
math 'sin(pi)'
Function calls have the lowest precedence, so
math sin 2 + 6
is the same as
math 'sin(2 + 6)'
* Add more tests
* Add a note to the docs
* even moar docs
Moar docca
* moar tests
Call me Nikola Testla
It's not super clear what $SHLVL is useful for, but the current
definition is essentially
"number of shells in the parent processes + 1"
which isn't *super useful*?
Bash's behavior here is a bit weird in that it increments $SHLVL
basically always, but since it auto-execs the last process it will
decrement it again, so in practice it's often not incremented.
E.g.
```
> echo $SHLVL
1
> bash -c 'echo $SHLVL; bash'
2
>> echo $SHLVL
2
```
Both bashes here end up having the same $SHLVL because this is
equivalent to `echo $SHLVL; exec bash`. Running `echo $SHLVL` and then
`bash -c 'echo $SHLVL'` in an interactive bash will have a different
result (1 and 2) because that doesn't *exec* the inner bash.
That's not something we want to get into, so what we do is increment
$SHLVL in every interactive fish. Non-interactive fish will simply
import the existing value.
That means if you had e.g. a bash that runs a fish script that ends up
opening a new fish session, you would have a $SHLVL of *2* - one for the
bash, and one for the inner fish.
We key this off is_interactive_session() (which can also be enabled
via `fish -i`) because it's easy and because `fish -i` is asking for
fish to be, in some form, "interactive".
That means most of the time $SHLVL will be "how many shells am I deep,
how often do I have to `exit`", except for when you specifically asked
for a fish to be "interactive". If that's a problem, we can rethink it.
Fixes#7864.
This breaks apart the massive "index" document into
1. An "index" document that explains how to install and set up fish
and links to the other documents
2. A "fish-language" document that describes the syntax and semantics
of the language
3. A "fish-interactive" document that describes how to use fish
interactively
No change to the content has been made, only the parts have been moved
from index and some of the formatting (links and header levels) were
fixed.
See #7348.
Unlike links, these are checked by sphinx and it complains if they
don't match.
Also they have a better chance of doing something useful in outputs
other than html.
The "classic" theme is a mostly useless wrapper around the basic theme
that just adds a collapsible sidebar (that we no longer have).
Moving to basic directly drops a layer of indirection and a file that
needs to be transferred over the net.
Same thing goes for "default.css" which literally just includes
classic.css (WHYYYY???)
(also this removes some useless javascript)
Unfortunately this has both stopwords and a length limit, and things
like "and" just are tough to search.
So what we do is leave everything as it is, but when a search fails,
we show a list of things that are hard to search for, currently that's
"and", "for", "if" and such.
Fixes#7757.
The user may write for example:
echo foo >&5
and fish would try to output to file descriptor 5, within the fish process
itself. This has unpredictable effects and isn't useful. Make this an
error.
Note that the reverse is "allowed" but ignored:
echo foo 5>&1
this conceptually dup2s stdout to fd 5, but since no builtin writes to fd
5 we ignore it.
After commit 6dd6a57c60, 3 remaining
builtins were affected by uint8_t overflow: `exit`, `return`, and
`functions --query`.
This commit:
- Moves the overflow check from `builtin_set_query` to `builtin_run`.
- Removes a conflicting int -> uint8_t conversion in `builtin_return`.
- Adds tests for the 3 remaining affected builtins.
- Simplifies the wording for the documentation for `set --query`.
- Does not change documentation for `functions --query`, because it does
not state the exit code in its API.
- Updates the CHANGELOG to reflect the change to all builtins.
builtin_set_query returns the number of missing variables. Because the
return value passed to the shell is an 8-bit unsigned integer, if the
number of missing variables is a multiple of 256, it would overflow to 0.
This commit saturates the return value at 255 if there are more than 255
missing variables.
This introduces a new variable $fish_color_keyword that will be used
to highlight keywords. If it's not defined, we fall back on
$fish_color_command as before.
An issue here is that most of our keywords have this weird duality of
also being builtins *if* executed without an argument or with
`--help`.
This means that e.g.
if
is highlighted as a command until you start typing
if t
and then it turns keyword.
E.g. autoloading and aliases are both about functions, variable scope
and overrides are both about variables.
It makes sense to group these together, and this might allow us to
collapse some of the TOC later.
Also move abbr explanation to interactive use (as abbrs are purely an
interactive concept)
(also add an example to tilde expansion, not making a separate commit
for that)
This goes to a separate file because that makes option parsing easier
and allows profiling both at the same time.
The "normal" profile now contains only the profile data of the actual
run, which is much more useful - you can now profile a function by
running
fish -C 'source /path/to/thing' --profile /tmp/thefunction.prof -c 'thefunction'
and won't need to filter out extraneous information.
This allows us to flex them together, so now you get one column on the
left with the title "Documents" and one on the right saying
"Sections" on narrow screens.
On wide screens it doesn't say "Table Of Contents" twice.
This should make it clearer
This used to put the TOC last, which is the last place you'd want it.
It's not perfect and we do some hacky layoutery to achieve it, but it
should generally be usable.
This makes the *tables* themselves scrollable, not the section div
they are in, which means the section doesn't scroll along with
them (it's already reflowed).
We should typically avoid scrolling even at max-width.
An exception here is the output of `functions` - this prints one very
long line, but it's really not important what's in there specifically,
it's just to illustrate the kind of output you'd get.
This clips overflowing padding/margins and thereby removes
non-"content" that's just off-screen, making the site scrollable.
The exception here is for tables - we allow scrolling the *section*
divs for those (because I have no idea how to only make the <table>
scrollable), if necessary of course.
This came up online - here we exclaim that fish has no aliases (which
is true), but then in the main docs we explain that you can use
`alias` to make something (which is also true).
Add a foot note explaining the apparent contradiction.
This removes the margin with the background gradient and such
completely once the screen falls under 700px. In those cases we really
don't want to waste space, and having just a weird blue bit above the
docs looks weirder than not having anything.
Currently binding `exit` to a key checks too late that it's exitted,
so it leaves the shell hanging around until the user does an execute
or similar.
As I understand it, the `exit` builtin is supposed to only exit the
current "thread" (once that actually becomes a thing), and the
bindings would probably run in a dedicated one, so the simplest
solution here is to just add an `exit` bind function.
Fixes#7604.
Prior to this change, `fish_private_mode` worked by just suppressing
history outright. With this change, `fish_private_mode` can be toggled on
and off. Commands entered while `fish_private_mode` is set are stored but
in memory only; they are not written to disk.
Fixes#7590Fixes#7589
It was always a bit ridiculous that argparse required `X-longflag` if
that "X" short flag was never actually used anywhere.
Since the short letter is for getopt's benefit, we can hack around
this with our old friend: Unicode Private Use Areas.
We have a counter, starting at 0xE000 and going to 0xF8FF, that counts
up for all options that don't have a short flag and provides one. This
gives us up to 6400 long-only options.
6.4K should be enough for everybody.
Prior to this change, a glob like `**/file.txt` would only match
`file.txt` in subdirectories; the `**` must match at least one directory.
This is historical behavior.
With this change we move a little closer to bash's implementation by
allowing a literal `**` segment to match in the current directory. That
is, `**/foo` will match both `foo` and `bar/foo`, while `b**/foo` will
only match `bar/foo`.
Fixes#7222.
And again clang-format does something I don't like:
- if (found != end && std::strncmp(found->name, name, len) == 0 && found->name[len] == 0) return found;
+ if (found != end && std::strncmp(found->name, name, len) == 0 && found->name[len] == 0)
+ return found;
I *know* this is a bit of a long line. I would still quite like having
no brace-less multi-line if *ever*. Either put the body on the same
line, or add braces.
Blergh
When building from source, there is a warning:
../doc_src/cmds/string-match.rst:13: WARNING: Inline emphasis
start-string without end-string.
One fix appears to be putting a space after the epmhasized 'n' character,
e.g., `*n* th` instead of `*n*th`.
E.g. if we do `string match -q`, and we find a match, nothing about
the input can change anything, so we quit early.
This is mainly useful for performance, but it also allows `string`
with `-q` to be used with infinite input (e.g. `yes`).
Alternative to #7495.
Currently a bit limited, unfortunately printf's `%a` specifier is
absolutely unreadable.
So we add `hex` and `octal` with `0x` and `0` prefixes respectively,
and also take a number but currently only allow 16 and 8.
The output is truncated to integer, so scale values other than 0 are
invalid and 0 is implied.
The docs mention this may change.
This allows us to write the changelog reasonably simply.
The biggest downside is that pandoc won't be able to handle it anymore
when converting to markdown, but
sphinx-markdown-builder (https://github.com/codejamninja/sphinx-markdown-builder)
should be able to handle it.
This is super cheesy.
One of the most common feature requests we get is "control-r must
search", even tho just using history-search-backward via e.g. up-arrow
is perfectly capable. The only real difference is that ctrl-r search
in other shells allows editing the search term by default, while we
stop the history search and edit the new commandline in those cases.
So, since the major problem is muscle-memory on ctrl-r,
let's just use that!
This makes ctrl-r do nothing on empty commandlines, and do
history-search-backward otherwise, so the basic flow of "press ctrl-r
to start history search, enter your search term, press ctrl-r to cycle
through matches" just works (except the first ctrl-r is useless and it
doesn't show anything).
See #602.
This switch is no longer necessary when only one command is given.
Internally completions are stored separately for each command,
so we only every print one command name per "complete" line anyway.
The sidebar had a fixed 230px, which is absolutely untenable if your
phone has 700px in total and we only use 85% of that.
So this moves the sidebar to the bottom for now, which isn't *great*,
but at least it leaves the text readable and allows navigating the ToC.
One of these days I'll understand what the heck CSS is.
[ci skip]
Released under the Python Software Foundation License, this one
doesn't look awful (no green top bar, huzzah!).
Lightly forked it to remove the donation footer (we don't take any)
and to change the python references to fish references.
The image is just our favicon, which is a stylized "f" and therefore
not fantastic (are we facebook?), but it's the best I found, and the
thing before had no images at all.
Fixes#6500
(as far as I'm concerned)
If the padding is not divisible by the char's width without remainder,
we pad the remainder with spaces, so the total width of the output is correct.
Also add completions, changelog entry, adjust documentation, add examples
with emoji and some tests. Apply some minor style nitpicks and avoid extra
allocations of the input strings.
Technically the equivalence would be something like
string length -q $str
test -n (string join \n -- $str | string collect)
To handle when str has multiple empty strings;
but quoting is easier to remember and enough for most practical purposes.
This reads any additional positional arguments given to `fish -c` into
$argv.
We don't handle the first argument specially (as `$0`) as that's confusing and
doesn't seem very useful.
Fixes#2314.
This allows
bind -k backspace suppress-autosuggestion or backward-delete-char
To remove the suggestion on the first press and then delete
chars.
Note: This requires that we then don't reenable suggestions
immediately afterwards. Currently we don't after deletion.
Fixes#1419.
Try to keep related things together - first the variable questions,
then the prompt questions, then more customization, then syntax
incompatibilities, ...
I'm not convinced all of these are actually frequently asked, or that
all frequently asked questions are here, but that's for later.
[ci skip]
This makes history searches case-insensitive, unless the search string
contains an uppercase character.
This is what vim calls "smartcase".
Fixes#7273.
Some formatting improvements, an explanation of $PWD, and some updates
- --on-process-exit is gone, the fish_command_not_found event is gone,
nobody has sent enhancements via the mailing list in years.
[ci skip]
This harkens back to the days of fish's "we don't need no stinkin'
echo" minimalism. That's long past, we have a bunch useful builtins
now just because they are useful, not because they have to be builtins.
[ci skip]
The person reading this is "you". It's completely okay and sounds
better to address them directly.
When we're talking about OS users or users of fish script the reader
writes, "the user" is still okay.
[ci skip]
The case for symlinked directories being duplicated a lot isn't there,
but there *is* a usecase for adding the symlink rather than the
target, and that's homebrew.
E.g. homebrew installs ruby into /usr/local/Cellar/ruby/2.7.1_2/bin,
and links to it from /usr/local/opt/ruby/bin. If we add the target, we
would miss updates.
Having path entries that point to the same location isn't a big
problem - it's a path lookup, so it takes a teensy bit longer. The
canonicalization is mainly so paths don't end up duplicated via weird
spelling and so relative paths can be used.
Taken from GNU realpath, this one makes realpath not resolve symlinks.
It still makes paths absolute and handles duplicate and trailing
slashes.
(useful in fish_add_path)
Currently, completions have to be specified like
```fish
complete -c foo -l opt
```
while
```fish
complete foo -l opt
```
just complains about there being too many arguments.
That's kinda useless, so we just assume if there is one left-over
argument that it's meant to be the command.
Theoretically we could also use *all* the arguments as commands to
complete, but that seems unlikely to be what the user wants.
(I don't think multi-command completions really happen)
Currently only `complete` will list completions, and it will list all
of them.
That's a bit ridiculous, especially since `complete -c foo` just does nothing.
So just make `complete -c foo` list all the completions for `foo`.
Previously, when a command wasn't found, fish would emit the
"fish_command_not_found" *event*.
This was annoying as it was hard to override (the code ended up
checking for a function called `__fish_command_not_found_handler`
anyway!), the setup was ugly,
and it's useless - there is no use case for multiple command-not-found handlers.
Instead, let's just call a function `fish_command_not_found` if it
exists, or print the default message otherwise.
The event is completely removed, but because a missing event is not an error
(MEISNAE in C++-speak) this isn't an issue.
Note that, for backwards-compatibility, we still keep the default
handler function around even tho the new one is hard-coded in C++.
Also, if we detect a previous handler, the new handler just calls it.
This way, the backwards-compatible way to install a custom handler is:
```fish
function __fish_command_not_found_handler --on-event fish_command_not_found
# do a little dance, make a little love, get down tonight
end
```
and the new hotness is
```fish
function fish_command_not_found
# do the thing
end
```
Fixes#7293.
For the few weird code blocks where default highlighting does not work,
we must add the 'highlight' class manually to get matching backgrounds.
This reuses the background color defined in pygments.css.
Now command, jobs, type, abbr, builtin, functions and set take `-q` to
query for existence, but the long option is inconsistent.
The first three use `--quiet`, the latter use `--query`. Add `--query`
to the first three, but keep `--quiet` around.
Fixes#7276.
This needs to have the vi-bindings take precedence, so they need to be
executed *last*.
It just needs to tell them that they shouldn't erase all the bindings.
[ci skip]
Instead of informing the bell character (hex 07), the example was using
an escaped \ followed by x07.
$ echo \\x07
\x07
$ echo \x07
$ echo \x07 | od -a
0000000 bel nl
0000002
$
* docs: Use \u instead of \\u
Instead of informing the Unicode character 慡, this example was using an
escaped \ followed by u6161.
$ echo \\u6161
\u6161
$ echo \u6161
慡
Before:
$ string escape --style=var 'a1 b2'\\u6161 | string unescape --style=var
a1 b2\u6161
Now:
$ string escape --style=var 'a1 b2'\u6161 | string unescape --style=var
a1 b2慡
Just as `math "bitand(5,3)"` and `math "bitor(6,2)"`.
These cast to long long before doing their thing,
so they truncate to an integer, producing weird results with floats.
That's to be expected because float representation is *very*
different, and performing bitwise operations on floats feels quite useless.
Fixes#7281.
Was: "parameter expansion takes before expressions are evaluated."
Now: "parameter expansion happens before expressions are evaluated."
I suspect the original intent was to use "takes place," but I see "happens" as less idiomatic and therefore may benefit non-English-native users.
Also return the number of failed files.
I decided to *just* print the filenames (newline-separated because
NULLs are annoying here) to make it easier to deal with.
See #7251.
This can be used to determine whether the previous command produced a real status, or just carried over the status from the command before it. Backgrounded commands and variable assignments will not increment status_generation, all other commands will.
There are a few code blocks where the default highlighting does not
work and the documentation looks bad as a result. Usually this happens
when we are demonstrating an important interactive feature, such as
autosuggestions, syntax highlighting, or tab completion.
The pygments highlighter was not designed for code samples like these.
But it is important to show the behavior clearly in the docs. I am
attempting to make these weird examples look as much like the "normal"
code blocks as possible.
https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal
One of the nicest things about fish is how introspectable it is. We
should probably get people to just mess around and see what is
implemented how. This is a step in that direction.
[ci skip]
- add missing links for some commands (control flow section)
- fix broken links that use the old syntax (#tut_ links)
- miscellaneous fixing of backticks/emphasis
