Commit Graph

130 Commits

Author SHA1 Message Date
Fabian Boehm
a4dc6dcb74 docs: Add some more mentions
We should have more cross-linking and mentions of our builtins and
functions, so people can find the dang things.
2022-10-20 19:33:57 +02:00
Fabian Boehm
b6c1ecb288 docs: Add something on how we find commands 2022-10-20 19:31:18 +02:00
Michael Jarvis
ad696a1ec3
Fix warning 20221018 (#9287)
* Fix Sphinx warning:

../CHANGELOG.rst:2: WARNING: Explicit markup ends without a blank line; unexpected unindent.

* Fix Sphinx warning:

fish-shell/doc_src/language.rst:129: WARNING: Explicit markup ends without a blank line; unexpected unindent.
2022-10-18 18:23:12 +02:00
Fabian Boehm
d7f36fab44 docs: Fix some of the escaping section
No more need to escape `^`, be fancy with the backslash space to make
it actually, you know, render in the output.
2022-10-12 18:18:27 +02:00
Fabian Boehm
52dcfe11af Make \x the same as \X
Up to now, in normal locales \x was essentially the same as \X, except
that it errored if given a value > 0x7f.

That's kind of annoying and useless.

A subtle change is that `\xHH` now represents the character (if any)
encoded by the byte value "HH", so even for values <= 0x7f if that's
not the same as the ASCII value we would diverge.

I do not believe anyone has ever run fish on a system where that
distinction matters. It isn't a thing for UTF-8, it isn't a thing for
ASCII, it isn't a thing for UTF-16, it isn't a thing for any extended
ASCII scheme - ISO8859-X, it isn't a thing for SHIFT-JIS.

I am reasonably certain we are making that same assumption in other
places.

Fixes #1352
2022-10-09 15:24:01 +02:00
Fabian Boehm
521dc5c5d0 docs: Explain SIGPIPE and how it relates to $pipestatus 2022-09-30 18:32:43 +02:00
Fabian Boehm
1204cf5eb6 docs/read: Improve examples a bit 2022-09-24 10:56:43 +02:00
Fabian Boehm
38b24c2325 docs: Use :doc: role when linking to commands
This makes it so we link to the very top of the document instead of a
special anchor we manually include.

So clicking e.g. :doc:`string <cmds/string>` will link you to
cmds/string.html instead of cmds/string.html#cmd-string.

I would love to have a way to say "this document from the root of the
document path", but that doesn't appear to work, I tried
`/cmds/string`.

So we'll just have to use cmds/string in normal documents and plain
`string` from other commands.
2022-09-24 10:56:43 +02:00
Fabian Boehm
17426d4741 docs: Write an example for interactive read 2022-09-23 16:25:35 +02:00
tocic
ade61fd50f docs: Fix typos 2022-09-17 21:31:06 +08:00
Fabian Boehm
1819c7f2b8 docs: Add more specific guidance on locale variables 2022-06-17 22:08:00 +02:00
Fabian Homborg
83a993a28e Remove references to match/expand in the docs 2022-05-29 17:48:11 +02:00
Fabian Homborg
37fd508a59 Path is also a failglob exception 2022-05-29 17:48:11 +02:00
Fabian Homborg
af1050d83f Update the rest of the docs for path 2022-05-29 17:48:11 +02:00
Gregory Anders
55f0f2de4c Search $__fish_user_data_dir for vendor additions 2022-05-12 20:29:05 +02:00
Johannes Altmanninger
ca98325462 CHANGELOG: fix typo 2022-05-01 16:37:55 +02:00
Fabian Homborg
2fa51f1843 Add $EUID and use it in fish_is_root_user
Fixes #8866
2022-04-15 15:58:39 +02:00
Fabian Homborg
5e6b35696f Document feature flags for 3.5.0 2022-04-15 13:42:38 +02:00
Fabian Homborg
74be3e847f Force stderr-nocaret feature flag on
This can no longer be changed. If "no-stderr-nocaret" is in
$fish_features it will simply be ignored.

The "^" redirection that was deprecated in fish 3.0 is now gone for good.

Note: For testing reasons, it can still be set _internally_ by running
"feature_flags_t::set". We simply shouldn't do that.
2022-04-15 13:42:38 +02:00
Edward Betts
dc4e88d7b4 Fix a typo 2022-03-16 20:02:09 -07:00
Johannes Altmanninger
ad4530acd3 docs synopses: add space before ellipsis
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.
2022-01-16 14:05:47 +01:00
Johannes Altmanninger
be451091d4 docs synopses: use ellipsis with singular words
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.
2022-01-16 14:05:47 +01:00
Fabian Homborg
be43e95ac9 docs: Expand path variable section 2021-12-01 19:03:40 +01:00
Johannes Altmanninger
0d3d84a39c Fix typos in documentation 2021-11-18 15:06:12 +01:00
Fabian Homborg
0f1bc5335a docs: :envvar: the rest of the variables
Just a quick mechanical translation
2021-11-12 19:43:00 +01:00
Fabian Homborg
02553d8fa6 Docs: Don't use seealso
This is too eye catching and almost unreadable in the dark theme.
2021-11-12 18:13:36 +01:00
Fabian Homborg
edc09c8419 Docs: Switch back to vanilla :ref: for commands that should be linked
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
2021-11-12 18:02:56 +01:00
Fabian Homborg
2e9e94f17e Fix broken envvar link
Apparently you can't use spaces here.
2021-11-12 17:57:11 +01:00
Aaron Gyes
ac1df310c8 Long march towards more structured text 2021-11-12 04:22:35 -08:00
Aaron Gyes
97245fcd3f fix typo 2021-11-06 14:14:11 -07:00
Aaron Gyes
94890c28d3 Underline links. Use CSS to add $ to envvar links 2021-11-06 14:09:27 -07:00
ridiculousfish
797e3f1ce9 language.rst: clean up redirection docs and mention noclobber + append
Fixes #8380
2021-11-06 13:11:18 -07:00
Aaron Gyes
c5e02206d3 Fix up the _PATH ref.
So, it looks like even without -n `sphinx` will report on refs
are bad.

Closes #8407
2021-11-05 16:21:01 -07:00
Aaron Gyes
3078d0a252 fish documentation manpages: omit NAME for non-commands
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
2021-11-05 07:50:30 -07:00
Aaron Gyes
d54c8a42a9 Documentation WIP:
Start doing the envvar:: directives and cut some copy. These should
be linking up now.
2021-11-05 05:14:02 -07:00
Fabian Homborg
a4adda5da8 docs: Expand math for bash users a bit
Also fix some awkward typos.
2021-11-03 17:23:36 +01:00
Fabian Homborg
cbf28dfa57 Document turning off suggestions/history
Also add more mentions of `fish_config` in general.
2021-11-02 21:40:56 +01:00
Fabian Homborg
a4983af94d docs: Fix section level
Using "=====" makes it an entry in the toc
2021-10-29 17:01:48 +02:00
Fabian Homborg
8428247f31 docs: Split up the variable docs some more
(also remove some broken or incorrect footnotes)
2021-10-28 16:48:08 +02:00
Fabian Homborg
387904928b docs: Add more on wordsplitting 2021-10-28 16:42:19 +02:00
Fabian Homborg
ae3d5af1ab docs: Correct an example 2021-10-28 16:35:21 +02:00
Fabian Homborg
bffb49b38a Explicitly mention function variables don't go out of scope
Fixes #8385.
2021-10-27 16:55:11 +02:00
Fabian Homborg
4b46717a91 docs: Move configuration section to language
Instead leave a simple "use config.fish" bit in-place.

Also some minor rewording.
2021-10-23 17:13:36 +02:00
Fabian Homborg
db5e7734a6 Some small changes to the docs
Reorder the variables, make more cd-related stuff subsections, a
slight rewording.
2021-10-20 21:28:14 +02:00
Johannes Altmanninger
7cdf624086 docs: mention the "all" feature group 2021-09-05 03:34:25 +02:00
Evan Chen
878bfa94cb Typo funcions -> functions 2021-08-28 22:47:00 +02:00
Fabian Homborg
c055e3ae66 docs: Reword feature flags chapter 2021-08-17 17:32:41 +02:00
Fabian Homborg
35c53a94b5 docs: Remove stuff from globbing
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.
2021-08-11 18:42:21 +02:00
Fabian Homborg
013f98a5b3 docs: Double-re-extra mention bash vs fish globbing
And in the section we now point people towards!
2021-08-11 18:41:37 +02:00
Fabian Homborg
733114fefb
Add set --function (#8145)
* 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
2021-08-01 20:08:12 +02:00
Fabian Homborg
6e7d497a52 docs: Add a note explaining test 2021-07-27 18:35:20 +02:00
Fabian Homborg
25af0230ad docs: Clarify stderr-nocaret being on by default 2021-07-27 16:54:03 +02:00
Johannes Altmanninger
cc32b4f2a7 Make '&' only background if followed by a separating character
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 "&".
2021-07-23 22:58:51 +02:00
Fabian Homborg
df6109b953 docs: Reword bit about aliases and autoloading
This was kinda misleading. Point people to funcsave and `alias --save`
instead.

Fixes #8137.
2021-07-14 16:46:26 +02:00
Fabian Homborg
feb3a15739 docs: Make title level consistent
This allows us to ..include these without getting confused.
2021-07-13 23:05:23 +02:00
Johannes Altmanninger
5999d660c0 Docs for "$(cmd)" and $(cmd) 2021-07-13 21:33:42 +02:00
Johannes Altmanninger
4437a0d02a Minor doc rewording to use active voice 2021-07-13 21:33:42 +02:00
David Adam
eaa6149b87 docs: fix a missing reference 2021-06-28 22:45:29 +08:00
Fabian Homborg
c5bcd3cc95 Document $pipestatus/not harder 2021-06-25 18:28:30 +02:00
Fabian Homborg
71b9463165 docs: Some tweaks to "Syntax overview" 2021-06-06 21:36:04 +02:00
Fabian Homborg
b0b8cb0129 docs: Move color variables to interactive
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.
2021-06-06 17:43:06 +02:00
Fabian Homborg
046db09f90
Try to set LC_CTYPE to something UTF-8 capable (#8031)
* 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.
2021-06-06 09:28:32 +02:00
Fabian Homborg
843c9383aa docs: Remove non-functional link 2021-06-02 17:33:55 +02:00
Fabian Homborg
21f5032a55 docs: Don't speak of "initialization files"
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.
2021-05-28 20:49:57 +02:00
Fabian Homborg
af84c35282 docs: A bit more on autoloading 2021-05-16 21:27:00 +02:00
Fabian Homborg
678fa2e6a9 docs: A bit on index ranges
Try to make list-ness more accessible.
2021-05-12 19:40:43 +02:00
Fabian Homborg
127eaded96 docs: Mention set in variable expansion
This isn't strictly speaking variable expansion, but it's so related
that we should at least tease it.

See #7990.
2021-05-12 19:28:34 +02:00
ripytide
8c19b6105f Not quite accurate code example heading 2021-05-10 19:28:06 +02:00
ripytide
40704ba7a2 Explanation of list range example wrong way round.
I'm assuming the first number before the **..** is the FROM and the number after it is the TO.
2021-05-10 17:01:12 +02:00
Fabian Homborg
d5f9fc84dc docs: Remove "note that"
It's one of my verbal tics, and I don't want it.
2021-05-03 18:39:54 +02:00
Fabian Homborg
1e13c60059 docs: Link relevant language sections from the tutorial
This allows us to keep the tutorial more focussed and leave the more
in-depth information in the "language" part of the documentation.
2021-05-03 18:15:24 +02:00
Karolina Gontarek
9d66ddc840 Rename variable to fish_killring 2021-04-21 16:39:29 -07:00
Karolina Gontarek
da97daa800 Add variable to Special variables section 2021-04-21 16:39:29 -07:00
Josh Leichtung
f99127a158 Fix spelling of wheel in Wildcards docs 2021-04-18 07:47:52 +02:00
Fabian Homborg
d9b212f60b docs: Move some more sections from index to language
These aren't a 100% *exact* fit, but they're mostly language features.
2021-04-16 18:06:33 +02:00
Fabian Homborg
8bc7a85a69 docs: Remove #anchor links
Fixes at least one broken link to syntax
2021-04-16 18:06:33 +02:00
David Adam
9db846a5a7 docs: some improvements to the notes on key bindings
Includes acknowledgement that these are not full editors. Closes #4023.
2021-04-14 21:43:14 +08:00
Fabian Homborg
e1d19cf571 Don't touch $SHLVL if not interactive
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.
2021-03-29 17:44:13 +02:00
Fabian Homborg
e7abb52526 Remove special "default" value for $fish_history
This is really of very little use and makes checking $fish_history
harder because it makes two values mean the same thing.

Fixes #7650
2021-03-28 12:09:58 +02:00
Fabian Homborg
93eaa61294 Split up documentation
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.
2021-03-27 15:44:17 +01:00