Commit Graph

34 Commits

Author SHA1 Message Date
Johannes Stölp
1cba28c120 [doc]: fix --path description of set cmd 2023-11-18 19:00:56 -08:00
Oliver Schrenk
631f2c073c fix typo in set -U option 2023-10-18 19:08:09 +02:00
Fabian Boehm
ad54f07328 docs/set: Correct some errors 2023-09-13 17:08:52 +02:00
Andy Hall
6ff971e4c2 Fix typo in set docs 2023-04-08 18:56:46 -07:00
Maurizio De Santis
68ba30d8c8 Fix typo 2023-03-03 19:25:17 +01:00
shenleban tongying
27952db9f7 docs: clearify global vs universal variable 2023-01-13 15:58:37 +01:00
Fabian Boehm
e551f93f6d docs/set: Don't hide -u so much
It's fine if it doesn't show up in the synopsis above, but putting it
under "Notes" is just too awkward.

It's a short option that exists, and so it should be documented.
2022-11-10 11:34:50 +01:00
Aaron Gyes
6859a4c6f6 add missing space 2022-11-09 18:42:44 -08:00
Aaron Gyes
c107b57562 fixup unintentional NOTES newline 2022-11-09 18:04:44 -08:00
Aaron Gyes
32e770a4c2 set docs: improve syopsis, fix formatting, hide -u
I tried to make the synopsis a little less theoretical with
the placeholders and instead introduced the actual scope
options, long and short once, then refer to them as -Uflg from
then on.

I mentioned that list indicies are accepted / work to erase stuff.

In the list of options, we pretend like --unexport is long-only.
Especially with --unpath and --path, and what would go wrong
if one confused it with --univeral, and how rarely it's used,
I think it's better this way. I mention it as a synonym later
in the document so that it's not literally undocumented.

Changed phrasing such as:

"Causes the specified shell variable to be given a global scope"

Which can be read as we are taking a shell variable that exists
and giving it global scope, upgrading it to global (retaining
the value).

Redid the example section using the > syntax for things entered
into a prompt, with shell output following. The explanatory

Added in missing newlines at the ends of sentences.
2022-11-09 17:50:48 -08:00
Mahmoud Al-Qudsi
994049d33b Document support for erasing from multiple scopes 2022-10-20 11:21:05 -05:00
Mahmoud Al-Qudsi
dd0fd88736 Clarify and expand scope documentation
The function scope was not mentioned at all, even though it can be manually
specified.
2022-10-15 16:04:09 -05:00
David Adam
3a23fdf359 docs: omnibus cleanup
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.
2022-03-12 00:21:13 +08:00
David Adam
e23e52a8e9 docs: standardise on definition lists for options
Harmonizes the option listing including formatting in a similar manner to the
synopsis of each entry.
2022-03-12 00:21:12 +08:00
Johannes Altmanninger
2a98b7a593 docs synopsis: make all placeholder arguments uppercase
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.
2022-01-19 22:56:41 +08:00
Johannes Altmanninger
c0d1e41313 docs synopsis: add HTML highlighing and automate manpage markup
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
2022-01-19 22:56:41 +08:00
Johannes Altmanninger
78101364c3 docs synopses: remove unconventional spaces inside [] and ()
We usually write "[a | b]", not "[ a | b ]".
2022-01-16 14:05:47 +01: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
d9287ec471 set.rst: fix synopsis glitch and make placeholder uppercase
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.
2022-01-16 14:05:47 +01:00
Aaron Gyes
14d60ccb32 More synopsis work.
A great leap forward
2021-12-21 17:24:47 -08:00
Fabian Homborg
47e45704b1
Allow set --query to check for pathvarness (#8494)
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.
2021-11-26 18:29:10 +01:00
ridiculousfish
88a89d0a52 docs: remove an errant space 2021-11-14 13:40:02 -08:00
Fabian Homborg
eee38836cf set -q: Return 255 if no variable name was passed
Previously this strictly returned the number of unset variables. So if
no variable was given, it would return *true*, which is highly
suspect.
2021-08-14 10:55:21 +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
9fd69acd1a docs: Clean up set a bit
More links! Links good! Link link linky link!
2021-05-12 18:52:24 +02:00
Ethel Morgan
5a0aa7824f Saturate exit codes to 255 for all builtins
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.
2021-02-13 08:41:51 +01:00
Ethel Morgan
6dd6a57c60 Saturate return value in builtin_set_query
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.
2021-02-08 20:38:56 +01:00
Fabian Homborg
bb1aa5e72f docs: Make more code lines shorter 2021-02-02 08:35:38 +01:00
Fabian Homborg
4ef6490a26 docs: Some fixes to the erase section of set's exit status
[ci skip]
2020-11-20 16:09:24 +01:00
Fabian Homborg
ad138ecef8 docs: Document sets $status peculiarities harder
[ci skip]
2020-11-20 16:07:22 +01:00
Fabian Homborg
194f4f3734 Update docs for multi-erase in abbr and set
[ci skip]
2020-10-04 12:39:32 +02:00
Fabian Homborg
389c5e7ece Update set --show docs
See #6944
2020-04-26 17:55:17 +02:00
Delapouite
b8281f1284 doc: homogenize commands titles 2020-04-04 10:44:53 +02:00
Aaron Gyes
85a0ca66e0 We no longer have two doc systems, move sphinx_doc_src back to doc_src 2020-02-19 17:00:35 -08:00