github-mirror/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2024-11-22 15:37:59 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs synopsis: add HTML highlighing and automate manpage markup

Browse Source 
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 commit is contained in:
Johannes Altmanninger 2022-01-09 15:09:46 +01:00 committed by David Adam
parent 1c21e26d08
commit c0d1e41313
113 changed files with 631 additions and 238 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
cmake/Docs.cmake
View File

@ -9,7 +9,6 @@ include(FeatureSummary)
set(SPHINX_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc_src")
set(SPHINX_ROOT_DIR "${CMAKE_CURRENT_BINARY_DIR}/user_doc")
set(SPHINX_BUILD_DIR "${SPHINX_ROOT_DIR}/build")
set(SPHINX_CACHE_DIR "${SPHINX_ROOT_DIR}/doctrees")
set(SPHINX_HTML_DIR "${SPHINX_ROOT_DIR}/html")
set(SPHINX_MANPAGE_DIR "${SPHINX_ROOT_DIR}/man")
@ -22,7 +21,7 @@ add_custom_target(sphinx-docs
-j auto
-q -b html
-c "${SPHINX_SRC_DIR}"
-d "${SPHINX_CACHE_DIR}"
-d "${SPHINX_ROOT_DIR}/.doctrees-html"
"${SPHINX_SRC_DIR}"
"${SPHINX_HTML_DIR}"
DEPENDS ${SPHINX_SRC_DIR}/fish_indent_lexer.py fish_indent
@ -35,7 +34,7 @@ add_custom_target(sphinx-manpages
-j auto
-q -b man
-c "${SPHINX_SRC_DIR}"
-d "${SPHINX_CACHE_DIR}"
-d "${SPHINX_ROOT_DIR}/.doctrees-man"
"${SPHINX_SRC_DIR}"
# TODO: This only works if we only have section 1 manpages.
"${SPHINX_MANPAGE_DIR}/man1"

4
doc_src/cmds/_.rst
View File

@ -6,7 +6,9 @@ _ - call fish's translations
Synopsis
--------
``_`` *STRING*
.. synopsis::
_ STRING
Description
-----------

14
doc_src/cmds/abbr.rst
View File

@ -6,12 +6,14 @@ abbr - manage fish abbreviations
Synopsis
--------
| ``abbr`` --add [*SCOPE*] *WORD* *EXPANSION*
| ``abbr`` --erase *WORD* ...
| ``abbr`` --rename [*SCOPE*] *OLD_WORD* *NEW_WORD*
| ``abbr`` --show
| ``abbr`` --list
| ``abbr`` --query *WORD* ...
.. synopsis::
abbr --add [SCOPE] WORD EXPANSION
abbr --erase WORD ...
abbr --rename [SCOPE] OLD_WORD NEW_WORD
abbr --show
abbr --list
abbr --query WORD ...
Description
-----------

8
doc_src/cmds/alias.rst
View File

@ -6,9 +6,11 @@ alias - create a function
Synopsis
--------
| ``alias``
| ``alias`` [*OPTIONS*] *NAME* *DEFINITION*
| ``alias`` [*OPTIONS*] *NAME*=*DEFINITION*
.. synopsis::
alias
alias [OPTIONS] NAME DEFINITION
alias [OPTIONS] NAME=DEFINITION
Description

4
doc_src/cmds/and.rst
View File

@ -6,7 +6,9 @@ and - conditionally execute a command
Synopsis
--------
PREVIOUS; **and** *COMMAND*
.. synopsis::
PREVIOUS; and COMMAND
Description
-----------

4
doc_src/cmds/argparse.rst
View File

@ -6,7 +6,9 @@ argparse - parse options passed to a fish script or function
Synopsis
--------
``argparse`` [*OPTIONS*] *OPTION_SPEC* ... -- [*ARG* ...]
.. synopsis::
argparse [OPTIONS] OPTION_SPEC ... -- [ARG ...]
Description

4
doc_src/cmds/begin.rst
View File

@ -6,7 +6,9 @@ begin - start a new block of code
Synopsis
--------
**begin**; [*COMMANDS* ...]; **end**
.. synopsis::
begin; [COMMANDS ...]; end
Description
-----------

4
doc_src/cmds/bg.rst
View File

@ -6,7 +6,9 @@ bg - send jobs to background
Synopsis
--------
``bg`` [*PID* ...]
.. synopsis::
bg [PID ...]
Description
-----------

14
doc_src/cmds/bind.rst
View File

@ -5,12 +5,14 @@ bind - handle fish key bindings
Synopsis
--------
| ``bind`` [(**-M** | **--mode**) *MODE*] [(*-m* | *--sets-mode*) **NEW_MODE**] [*--preset* | *--user*] [*-s* | *--silent*] [**-k** | **--key**] *SEQUENCE* *COMMAND* ...
| ``bind`` [(**-M** | **--mode**) *MODE*] [**-k** | **--key**] [**--preset**] [**--user**] *SEQUENCE*
| ``bind`` (**-K** | **--key-names**) [**-a** | **--all**] [**--preset**] [**--user**]
| ``bind`` (**-f** | **--function-names**)
| ``bind`` (**-L** | **--list-modes**)
| ``bind`` (**-e** | **--erase**) [(**-M** | **--mode**) *MODE*] [**--preset**] [**--user**] [**-a** | **--all**] | [**-k** | **--key**] *SEQUENCE* ...
.. synopsis::
bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [-s | --silent] [-k | --key] SEQUENCE COMMAND ...
bind [(-M | --mode) MODE] [-k | --key] [--preset] [--user] SEQUENCE
bind (-K | --key-names) [-a | --all] [--preset] [--user]
bind (-f | --function-names)
bind (-L | --list-modes)
bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] [-a | --all] | [-k | --key] SEQUENCE ...
Description
-----------

4
doc_src/cmds/block.rst
View File

@ -6,7 +6,9 @@ block - temporarily block delivery of events
Synopsis
--------
**block** [*OPTIONS*]
.. synopsis::
block [OPTIONS]
Description
-----------

12
doc_src/cmds/break.rst
View File

@ -6,11 +6,13 @@ break - stop the current inner loop
Synopsis
--------
| loop_construct
| [*COMMANDS* ...]
| **break**
| [*COMMANDS* ...]
| end
.. synopsis::
loop_construct
[COMMANDS ...]
break
[COMMANDS ...]
end
Description
-----------

4
doc_src/cmds/breakpoint.rst
View File

@ -6,7 +6,9 @@ breakpoint - launch debug mode
Synopsis
--------
``breakpoint``
.. synopsis::
breakpoint
Description
-----------

6
doc_src/cmds/builtin.rst
View File

@ -6,8 +6,10 @@ builtin - run a builtin command
Synopsis
--------
| **builtin** [*OPTIONS*] *BUILTINNAME*
| **builtin** --query *BUILTINNAME* ...
.. synopsis::
builtin [OPTIONS] BUILTINNAME
builtin --query BUILTINNAME ...
Description
-----------

10
doc_src/cmds/case.rst
View File

@ -6,10 +6,12 @@ case - conditionally execute a block of commands
Synopsis
--------
| **switch** *VALUE*
| [**case** [*GLOB* ...]
| [*COMMAND* ...]]
| **end**
.. synopsis::
switch VALUE
[case [GLOB ...]
[COMMAND ...]]
end
Description
-----------

4
doc_src/cmds/cd.rst
View File

@ -6,7 +6,9 @@ cd - change directory
Synopsis
--------
**cd** [*DIRECTORY*]
.. synopsis::
cd [DIRECTORY]
Description
-----------

4
doc_src/cmds/cdh.rst
View File

@ -6,7 +6,9 @@ cdh - change to a recently visited directory
Synopsis
--------
``cdh`` [*DIR*]
.. synopsis::
cdh [DIR]
Description
-----------

4
doc_src/cmds/command.rst
View File

@ -6,7 +6,9 @@ command - run a program
Synopsis
--------
**command** [**OPTIONS**] [*COMMANDNAME* [ARG ...]]
.. synopsis::
command [OPTIONS] [COMMANDNAME [ARG ...]]
Description
-----------

4
doc_src/cmds/commandline.rst
View File

@ -6,7 +6,9 @@ commandline - set or get the current command line buffer
Synopsis
--------
``commandline`` [*OPTIONS*] [*CMD*]
.. synopsis::
commandline [OPTIONS] [CMD]
Description
-----------

6
doc_src/cmds/complete.rst
View File

@ -6,8 +6,10 @@ complete - edit command specific tab-completions
Synopsis
--------
``complete`` ((**-c** | **--command**) | (**-p** | **--path**)) *COMMAND* [*options*]
``complete`` ((**-C** | **--do-complete**)) *STRING*
.. synopsis::
complete ((-c | --command) | (-p | --path)) COMMAND [options]
complete ((-C | --do-complete)) STRING
Description
-----------

4
doc_src/cmds/contains.rst
View File

@ -6,7 +6,9 @@ contains - test if a word is present in a list
Synopsis
--------
``contains`` [**options**] *KEY* [*VALUES* ...]
.. synopsis::
contains [options] KEY [VALUES ...]
Description
-----------

4
doc_src/cmds/continue.rst
View File

@ -6,7 +6,9 @@ continue - skip the remainder of the current iteration of the current inner loop
Synopsis
--------
**LOOP_CONSTRUCT**; [*COMMANDS* ...;] **continue**; [*COMMANDS* ...;] **end**
.. synopsis::
LOOP_CONSTRUCT; [COMMANDS ...;] continue; [COMMANDS ...;] end
Description
-----------

8
doc_src/cmds/count.rst
View File

@ -6,9 +6,11 @@ count - count the number of elements of a list
Synopsis
--------
| ``count`` string1 string2 ...
| *command* | ``count``
| ``count`` [...] < *FILE*
.. synopsis::
count string1 string2 ...
command | count
count [...] < FILE
Description
-----------

4
doc_src/cmds/dirh.rst
View File

@ -6,7 +6,9 @@ dirh - print directory history
Synopsis
--------
``dirh``
.. synopsis::
dirh
Description
-----------

4
doc_src/cmds/dirs.rst
View File

@ -6,7 +6,9 @@ dirs - print directory stack
Synopsis
--------
``dirs`` [*-c*]
.. synopsis::
dirs [-c]
Description
-----------

4
doc_src/cmds/disown.rst
View File

@ -6,7 +6,9 @@ disown - remove a process from the list of jobs
Synopsis
--------
``disown`` [**PID** ...]
.. synopsis::
disown [PID ...]
Description
-----------

4
doc_src/cmds/echo.rst
View File

@ -6,7 +6,9 @@ echo - display a line of text
Synopsis
--------
``echo`` [*options*] [*STRING*]
.. synopsis::
echo [options] [STRING]
Description
-----------

4
doc_src/cmds/else.rst
View File

@ -6,7 +6,9 @@ else - execute command if a condition is not met
Synopsis
--------
**if** *CONDITION*; *COMMANDS_TRUE* ...; [**else**; *COMMANDS_FALSE* ...;] **end**
.. synopsis::
if CONDITION; COMMANDS_TRUE ...; [else; COMMANDS_FALSE ...;] end
Description
-----------

4
doc_src/cmds/emit.rst
View File

@ -6,7 +6,9 @@ emit - emit a generic event
Synopsis
--------
``emit`` *EVENT_NAME* [*ARGUMENTS* ...]
.. synopsis::
emit EVENT_NAME [ARGUMENTS ...]
Description
-----------

20
doc_src/cmds/end.rst
View File

@ -6,15 +6,19 @@ end - end a block of commands
Synopsis
--------
| **begin**
| [*COMMANDS* ...]
| **end**
.. synopsis::
| **function** *NAME* [*OPTIONS*]; *COMMANDS* ...; **end**
| **if** *CONDITION*; *COMMANDS_TRUE* ...; [**else**; *COMMANDS_FALSE* ...;] **end**
| **switch** *VALUE*; [**case** [*WILDCARD* ...]; [*COMMANDS* ...]; ...] **end**
| **while** *CONDITION*; *COMMANDS* ...; **end**
| **for** *VARNAME* in [*VALUES* ...]; **COMMANDS** ...; **end**
begin
[COMMANDS ...]
end
.. synopsis::
function NAME [OPTIONS]; COMMANDS ...; end
if CONDITION; COMMANDS_TRUE ...; [else; COMMANDS_FALSE ...;] end
switch VALUE; [case [WILDCARD ...]; [COMMANDS ...]; ...] end
while CONDITION; COMMANDS ...; end
for VARNAME in [VALUES ...]; COMMANDS ...; end
Description
-----------

4
doc_src/cmds/eval.rst
View File

@ -6,7 +6,9 @@ eval - evaluate the specified commands
Synopsis
--------
**eval** [*COMMANDS* ...]
.. synopsis::
eval [COMMANDS ...]
Description
-----------

4
doc_src/cmds/exec.rst
View File

@ -6,7 +6,9 @@ exec - execute command in current process
Synopsis
--------
**exec** *COMMAND*
.. synopsis::
exec COMMAND
Description
-----------

4
doc_src/cmds/exit.rst
View File

@ -7,7 +7,9 @@ exit - exit the shell
Synopsis
--------
**exit** [*code*]
.. synopsis::
exit [code]
Description
-----------

4
doc_src/cmds/false.rst
View File

@ -6,7 +6,9 @@ false - return an unsuccessful result
Synopsis
--------
**false**
.. synopsis::
false
Description
-----------

4
doc_src/cmds/fg.rst
View File

@ -6,7 +6,9 @@ fg - bring job to foreground
Synopsis
--------
``fg`` [*PID*]
.. synopsis::
fg [PID]
Description
-----------

6
doc_src/cmds/fish.rst
View File

@ -7,8 +7,10 @@ fish - the friendly interactive shell
Synopsis
--------
| ``fish`` [*OPTIONS*] [*FILE* [ARG ...]]
| ``fish`` [*OPTIONS*] [**-c** *COMMAND* [ARG ...]]
.. synopsis::
fish [OPTIONS] [FILE [ARG ...]]
fish [OPTIONS] [-c COMMAND [ARG ...]]
Description
-----------

6
doc_src/cmds/fish_add_path.rst
View File

@ -7,8 +7,10 @@ fish_add_path - add to the path
Synopsis
--------
| ``fish_add_path`` *path* ...
| ``fish_add_path`` [(*-g* | *--global*) | (*-U* | *--universal*) | (*-P* | *--path*)] [(*-m* | *--move*)] [(*-a* | *--append*) | (*-p* | *--prepend*)] [(*-v* | *--verbose*) | (*-n* | *--dry-run*)] *paths* ...
.. synopsis::
fish_add_path path ...
fish_add_path [(-g | --global) | (-U | --universal) | (-P | --path)] [(-m | --move)] [(-a | --append) | (-p | --prepend)] [(-v | --verbose) | (-n | --dry-run)] paths ...
Description

5
doc_src/cmds/fish_breakpoint_prompt.rst
View File

@ -6,7 +6,10 @@ fish_breakpoint_prompt - define the prompt when stopped at a breakpoint
Synopsis
--------
**fish_breakpoint_prompt**
.. synopsis::
fish_breakpoint_prompt
::
function fish_breakpoint_prompt

8
doc_src/cmds/fish_command_not_found.rst
View File

@ -6,9 +6,11 @@ fish_command_not_found - what to do when a command wasn't found
Synopsis
--------
| **function** ``fish_command_not_found``
| ...
| **end**
.. synopsis::
function fish_command_not_found
...
end
Description

8
doc_src/cmds/fish_config.rst
View File

@ -6,9 +6,11 @@ fish_config - start the web-based configuration interface
Synopsis
--------
| ``fish_config`` [browse]
| ``fish_config`` **prompt** (choose | list | save | show)
| ``fish_config`` **theme** (choose | demo | dump | list | save | show)
.. synopsis::
fish_config [browse]
fish_config prompt (choose | list | save | show)
fish_config theme (choose | demo | dump | list | save | show)
Description
-----------

5
doc_src/cmds/fish_git_prompt.rst
View File

@ -6,7 +6,10 @@ fish_git_prompt - output git information for use in a prompt
Synopsis
--------
``fish_git_prompt``
.. synopsis::
fish_git_prompt
::
function fish_prompt

5
doc_src/cmds/fish_greeting.rst
View File

@ -6,7 +6,10 @@ fish_greeting - display a welcome message in interactive shells
Synopsis
--------
**fish_greeting**
.. synopsis::
fish_greeting
::
function fish_greeting

5
doc_src/cmds/fish_hg_prompt.rst
View File

@ -6,7 +6,10 @@ fish_hg_prompt - output Mercurial information for use in a prompt
Synopsis
--------
**fish_hg_prompt**
.. synopsis::
fish_hg_prompt
::
function fish_prompt

4
doc_src/cmds/fish_indent.rst
View File

@ -7,7 +7,9 @@ fish_indent - indenter and prettifier
Synopsis
--------
**fish_indent** [*OPTIONS*] [*FILE* ...]
.. synopsis::
fish_indent [OPTIONS] [FILE ...]
Description

4
doc_src/cmds/fish_is_root_user.rst
View File

@ -6,7 +6,9 @@ fish_is_root_user - check if the current user is root
Synopsis
--------
**fish_is_root_user**
.. synopsis::
fish_is_root_user
Description
-----------

4
doc_src/cmds/fish_key_reader.rst
View File

@ -6,7 +6,9 @@ fish_key_reader - explore what characters keyboard keys send
Synopsis
--------
**fish_key_reader** [*OPTIONS*]
.. synopsis::
fish_key_reader [OPTIONS]
Description
-----------

5
doc_src/cmds/fish_mode_prompt.rst
View File

@ -6,7 +6,10 @@ fish_mode_prompt - define the appearance of the mode indicator
Synopsis
--------
**fish_mode_prompt**
.. synopsis::
fish_mode_prompt
::
function fish_mode_prompt

7
doc_src/cmds/fish_opt.rst
View File

@ -5,8 +5,11 @@ fish_opt - create an option spec for the argparse command
Synopsis
--------
| ``fish_opt`` [**--help**]
| ``fish_opt`` [(**-slor**, **--multiple-vals=**) *optname*]
.. synopsis::
fish_opt [--help]
fish_opt [(-slor | --multiple-vals=) optname]
Description
-----------

5
doc_src/cmds/fish_prompt.rst
View File

@ -6,7 +6,10 @@ fish_prompt - define the appearance of the command line prompt
Synopsis
--------
``fish_prompt``
.. synopsis::
fish_prompt
::
function fish_prompt

5
doc_src/cmds/fish_status_to_signal.rst
View File

@ -6,7 +6,10 @@ fish_status_to_signal - convert exit codes to human-friendly signals
Synopsis
--------
``fish_status_to_signal`` *NUM*
.. synopsis::
fish_status_to_signal NUM
::
function fish_prompt

5
doc_src/cmds/fish_svn_prompt.rst
View File

@ -6,7 +6,10 @@ fish_svn_prompt - output Subversion information for use in a prompt
Synopsis
--------
``fish_svn_prompt``
.. synopsis::
fish_svn_prompt
::
function fish_prompt

5
doc_src/cmds/fish_title.rst
View File

@ -6,7 +6,10 @@ fish_title - define the terminal's title
Synopsis
--------
``fish_title``
.. synopsis::
fish_title
::
function fish_title

4
doc_src/cmds/fish_update_completions.rst
View File

@ -6,7 +6,9 @@ fish_update_completions - update completions using manual pages
Synopsis
--------
``fish_update_completions``
.. synopsis::
fish_update_completions
Description
-----------

5
doc_src/cmds/fish_vcs_prompt.rst
View File

@ -6,7 +6,10 @@ fish_vcs_prompt - output version control system information for use in a prompt
Synopsis
--------
``fish_vcs_prompt``
.. synopsis::
fish_vcs_prompt
::
function fish_prompt

4
doc_src/cmds/for.rst
View File

@ -6,7 +6,9 @@ for - perform a set of commands multiple times
Synopsis
--------
**for** *VARNAME* in [*VALUES* ...]; *COMMANDS* ...; **end**
.. synopsis::
for VARNAME in [VALUES ...]; COMMANDS ...; end
Description
-----------

4
doc_src/cmds/funced.rst
View File

@ -6,7 +6,9 @@ funced - edit a function interactively
Synopsis
--------
``funced`` [**OPTIONS**] *NAME*
.. synopsis::
funced [OPTIONS] NAME
Description
-----------

6
doc_src/cmds/funcsave.rst
View File

@ -6,8 +6,10 @@ funcsave - save the definition of a function to the user's autoload directory
Synopsis
--------
| ``funcsave`` *FUNCTION_NAME*
| ``funcsave`` [**-q**] [(**-d** | **--directory**) *DIR*] *FUNCTION_NAME*
.. synopsis::
funcsave FUNCTION_NAME
funcsave [-q] [(-d | --directory) DIR] FUNCTION_NAME
Description

4
doc_src/cmds/function.rst
View File

@ -6,7 +6,9 @@ function - create a function
Synopsis
--------
**function** *NAME* [*OPTIONS*]; *BODY*; **end**
.. synopsis::
function NAME [OPTIONS]; BODY; end
Description

12
doc_src/cmds/functions.rst
View File

@ -6,11 +6,13 @@ functions - print or erase functions
Synopsis
--------
| **functions** [**-a** | **--all**] [**-n** | **--names**]
| **functions** [**-D** | **--details**] [**-v**] *FUNCTION*
| **functions** **-c** *OLDNAME* *NEWNAME*
| **functions** **-d** *DESCRIPTION* *FUNCTION*
| **functions** [**-e** | **-q**] *FUNCTION* ...
.. synopsis::
functions [-a | --all] [-n | --names]
functions [-D | --details] [-v] FUNCTION
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [-e | -q] FUNCTION ...
Description
-----------

4
doc_src/cmds/help.rst
View File

@ -6,7 +6,9 @@ help - display fish documentation
Synopsis
--------
``help`` [*SECTION*]
.. synopsis::
help [SECTION]
Description
-----------

20
doc_src/cmds/history.rst
View File

@ -6,15 +6,17 @@ history - show and manipulate command history
Synopsis
--------
| ``history`` [**search**] [**--show-time**] [**--case-sensitive**]
\ [**--exact** | **--prefix** | **--contains**] [**--max** *n*] [**--null**] [**--reverse**]
\ [*SEARCH_STRING* ...]
| ``history`` **delete** [**--case-sensitive**]
\ [**--exact** | **--prefix** | **--contains**] *SEARCH_STRING* ...
| ``history`` **merge**
| ``history`` **save**
| ``history`` **clear**
| ``history`` **clear-session**
.. synopsis::
history [search] [--show-time] [--case-sensitive]
[--exact | --prefix | --contains] [--max n] [--null] [--reverse]
[SEARCH_STRING ...]
history delete [--case-sensitive]
[--exact | --prefix | --contains] SEARCH_STRING ...
history merge
history save
history clear
history clear-session
Description
-----------

10
doc_src/cmds/if.rst
View File

@ -6,10 +6,12 @@ if - conditionally execute a command
Synopsis
--------
| **if** *CONDITION*; *COMMANDS_TRUE* ...;
| [**else** **if** *CONDITION2*; *COMMANDS_TRUE2* ...;]
| [**else**; *COMMANDS_FALSE* ...;]
| **end**
.. synopsis::
if CONDITION; COMMANDS_TRUE ...;
[else if CONDITION2; COMMANDS_TRUE2 ...;]
[else; COMMANDS_FALSE ...;]
end
Description
-----------

4
doc_src/cmds/isatty.rst
View File

@ -6,7 +6,9 @@ isatty - test if a file descriptor is a terminal
Synopsis
--------
``isatty`` [*FILE DESCRIPTOR*]
.. synopsis::
isatty [FILE DESCRIPTOR]
Description
-----------

4
doc_src/cmds/jobs.rst
View File

@ -6,7 +6,9 @@ jobs - print currently running jobs
Synopsis
--------
``jobs`` [*OPTIONS*] [*PID* | %*JOBID*]
.. synopsis::
jobs [OPTIONS] [PID | %JOBID]
Description

4
doc_src/cmds/math.rst
View File

@ -6,7 +6,9 @@ math - perform mathematics calculations
Synopsis
--------
``math`` [(**-s** | **--scale**) *N*] [(**-b** | **--base**) *BASE*] *EXPRESSION* ...
.. synopsis::
math [(-s | --scale) N] [(-b | --base) BASE] EXPRESSION ...
Description

4
doc_src/cmds/nextd.rst
View File

@ -6,7 +6,9 @@ nextd - move forward through directory history
Synopsis
--------
``nextd`` [**-l** | **--list**] [*POS*]
.. synopsis::
nextd [-l | --list] [POS]
Description
-----------

4
doc_src/cmds/not.rst
View File

@ -6,7 +6,9 @@ not - negate the exit status of a job
Synopsis
--------
**not** *COMMAND* [*options* ...]
.. synopsis::
not COMMAND [options ...]
Description

4
doc_src/cmds/open.rst
View File

@ -6,7 +6,9 @@ open - open file in its default application
Synopsis
--------
``open`` *FILES* ...
.. synopsis::
open FILES ...
Description

4
doc_src/cmds/or.rst
View File

@ -6,7 +6,9 @@ or - conditionally execute a command
Synopsis
--------
*COMMAND1*; **or** *COMMAND2*
.. synopsis::
COMMAND1; or COMMAND2
Description
-----------

4
doc_src/cmds/popd.rst
View File

@ -6,7 +6,9 @@ popd - move through directory stack
Synopsis
--------
``popd``
.. synopsis::
popd
Description
-----------

4
doc_src/cmds/prevd.rst
View File

@ -6,7 +6,9 @@ prevd - move backward through directory history
Synopsis
--------
``prevd`` [**-l** | **--list**] [*POS*]
.. synopsis::
prevd [-l | --list] [POS]
Description
-----------

4
doc_src/cmds/printf.rst
View File

@ -6,7 +6,9 @@ printf - display text according to a format string
Synopsis
--------
``printf`` *FORMAT* [*ARGUMENT* ...]
.. synopsis::
printf FORMAT [ARGUMENT ...]
Description
-----------

4
doc_src/cmds/prompt_hostname.rst
View File

@ -6,7 +6,9 @@ prompt_hostname - print the hostname, shortened for use in the prompt
Synopsis
--------
``prompt_hostname``
.. synopsis::
prompt_hostname
Description
-----------

4
doc_src/cmds/prompt_login.rst
View File

@ -6,7 +6,9 @@ prompt_login - describe the login suitable for prompt
Synopsis
--------
``prompt_login``
.. synopsis::
prompt_login
Description
-----------

4
doc_src/cmds/prompt_pwd.rst
View File

@ -6,7 +6,9 @@ prompt_pwd - print pwd suitable for prompt
Synopsis
--------
``prompt_pwd``
.. synopsis::
prompt_pwd
Description
-----------

4
doc_src/cmds/psub.rst
View File

@ -6,7 +6,9 @@ psub - perform process substitution
Synopsis
--------
*COMMAND1* ( *COMMAND2* | ``psub`` [**-F** | -**-fifo**] [**-f** | **--file**] [(**-s** | **--suffix**) *SUFFIX*] )
.. synopsis::
COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [(-s | --suffix) SUFFIX] )
Description
-----------

4
doc_src/cmds/pushd.rst
View File

@ -6,7 +6,9 @@ pushd - push directory to directory stack
Synopsis
--------
``pushd`` *DIRECTORY*
.. synopsis::
pushd DIRECTORY
Description
-----------

6
doc_src/cmds/pwd.rst
View File

@ -6,8 +6,10 @@ pwd - output the current working directory
Synopsis
--------
| ``pwd`` [**-P** | **--physical**]
| ``pwd`` [**-L** | **--logical**]
.. synopsis::
pwd [-P | --physical]
pwd [-L | --logical]
Description

12
doc_src/cmds/random.rst
View File

@ -6,11 +6,13 @@ random - generate random number
Synopsis
--------
| ``random``
| ``random`` *SEED*
| ``random`` *START* *END*
| ``random`` *START* *STEP* *END*
| ``random`` choice [*ITEMS* ...]
.. synopsis::
random
random SEED
random START END
random START STEP END
random choice [ITEMS ...]
Description
-----------

4
doc_src/cmds/read.rst
View File

@ -6,7 +6,9 @@ read - read line of input into variables
Synopsis
--------
``read`` [*options*] [*VARIABLE* ...]
.. synopsis::
read [options] [VARIABLE ...]
Description
-----------

4
doc_src/cmds/realpath.rst
View File

@ -7,7 +7,9 @@ realpath - convert a path to an absolute path without symlinks
Synopsis
--------
**realpath** [*options*] *PATH*
.. synopsis::
realpath [options] PATH
Description
-----------

4
doc_src/cmds/return.rst
View File

@ -7,7 +7,9 @@ return - stop the current inner function
Synopsis
--------
**return** [*n*]
.. synopsis::
return [n]
Description
-----------

16
doc_src/cmds/set.rst
View File

@ -6,13 +6,15 @@ set - display and change shell variables
Synopsis
--------
| ``set`` [*scope options*]
| ``set`` [*options*] *VARIABLE* *VALUES* ...
| ``set`` [*options*] *VARIABLE*\[*INDICES*] *VALUES* ...
| ``set`` (**-q** | **--query**) [*scope options*] *VARIABLE* ...
| ``set`` (**-e** | **--erase**) [*scope options*] *VARIABLE* ...
| ``set`` (**-e** | **--erase**) [*scope options*] *VARIABLE*\[*INDICES*] ...
| ``set`` (**-S** | **--show**) *VARIABLE* ...
.. synopsis::
set [scope options]
set [options] VARIABLE VALUES ...
set [options] VARIABLE[INDICES] VALUES ...
set (-q | --query) [scope options] VARIABLE ...
set (-e | --erase) [scope options] VARIABLE ...
set (-e | --erase) [scope options] VARIABLE[INDICES] ...
set (-S | --show) VARIABLE ...
Description
-----------

4
doc_src/cmds/set_color.rst
View File

@ -6,7 +6,9 @@ set_color - set the terminal color
Synopsis
--------
``set_color`` [*OPTIONS*] *VALUE*
.. synopsis::
set_color [OPTIONS] VALUE
Description
-----------

6
doc_src/cmds/source.rst
View File

@ -6,8 +6,10 @@ source - evaluate contents of file
Synopsis
--------
| **source** *FILE* [*arguments* ...]
| ``somecommand`` | **source**
.. synopsis::
source FILE [arguments ...]
somecommand | source
Description

42
doc_src/cmds/status.rst
View File

@ -6,26 +6,28 @@ status - query fish runtime information
Synopsis
--------
| **status**
| **status** is-login
| **status** is-interactive
| **status** is-block
| **status** is-breakpoint
| **status** is-command-substitution
| **status** is-no-job-control
| **status** is-full-job-control
| **status** is-interactive-job-control
| **status** current-command
| **status** filename
| **status** basename
| **status** dirname
| **status** fish-path
| **status** function
| **status** line-number
| **status** stack-trace
| **status** job-control *CONTROL_TYPE*
| **status** features
| **status** test-feature *FEATURE*
.. synopsis::
status
status is-login
status is-interactive
status is-block
status is-breakpoint
status is-command-substitution
status is-no-job-control
status is-full-job-control
status is-interactive-job-control
status current-command
status filename
status basename
status dirname
status fish-path
status function
status line-number
status stack-trace
status job-control CONTROL_TYPE
status features
status test-feature FEATURE
Description
-----------

4
doc_src/cmds/string-collect.rst
View File

@ -6,7 +6,9 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` collect [**-N** | **--no-trim-newlines**] [*STRING* ...]
.. synopsis::
string collect [-N | --no-trim-newlines] [STRING ...]
.. END SYNOPSIS

6
doc_src/cmds/string-escape.rst
View File

@ -6,8 +6,10 @@ Synopsis
.. BEGIN SYNOPSIS
| ``string`` escape [**-n** | **--no-quoted**] [**--style=**] [*STRING* ...]
| ``string`` unescape [**--style=**] [*STRING* ...]
.. synopsis::
string escape [-n | --no-quoted] [--style=] [STRING ...]
string unescape [--style=] [STRING ...]
.. END SYNOPSIS

6
doc_src/cmds/string-join.rst
View File

@ -6,8 +6,10 @@ Synopsis
.. BEGIN SYNOPSIS
| ``string`` join [**-q** | **--quiet**] SEP [*STRING* ...]
| ``string`` join0 [**-q** | **--quiet**] [*STRING* ...]
.. synopsis::
string join [-q | --quiet] SEP [STRING ...]
string join0 [-q | --quiet] [STRING ...]
.. END SYNOPSIS

4
doc_src/cmds/string-length.rst
View File

@ -8,7 +8,9 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` length [**-q** | **--quiet**] [*STRING* ...]
.. synopsis::
string length [-q | --quiet] [STRING ...]
.. END SYNOPSIS

4
doc_src/cmds/string-lower.rst
View File

@ -6,7 +6,9 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` lower [**-q** | **--quiet**] [*STRING* ...]
.. synopsis::
string lower [-q | --quiet] [STRING ...]
.. END SYNOPSIS

8
doc_src/cmds/string-match.rst
View File

@ -6,9 +6,11 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` match [**-a** | **--all**] [**-e** | **--entire**] [**-i** | **--ignore-case**]
\ [**-r** | **--regex**] [**-n** | **--index**] [**-q** | **--quiet**] [**-v** | **--invert**]
\ *PATTERN* [*STRING* ...]
.. synopsis::
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-r | --regex] [-n | --index] [-q | --quiet] [-v | --invert]
PATTERN [STRING ...]
.. END SYNOPSIS

6
doc_src/cmds/string-pad.rst
View File

@ -6,8 +6,10 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` pad [**-r** | **--right**] [(**-c** | **--char**) *CHAR*] [(**-w** | **--width**) *INTEGER*]
\ [*STRING* ...]
.. synopsis::
string pad [-r | --right] [(-c | --char) CHAR] [(-w | --width) INTEGER]
[STRING ...]
.. END SYNOPSIS

6
doc_src/cmds/string-repeat.rst
View File

@ -6,8 +6,10 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` repeat [(**-n** | **--count**) *COUNT*] [(**-m** | **--max**) *MAX*] [**-N** | **--no-newline**]
\ [**-q** | **--quiet**] [*STRING* ...]
.. synopsis::
string repeat [(-n | --count) COUNT] [(-m | --max) MAX] [-N | --no-newline]
[-q | --quiet] [STRING ...]
.. END SYNOPSIS

6
doc_src/cmds/string-replace.rst
View File

@ -6,8 +6,10 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` replace [**-a** | **--all**] [**-f** | **--filter**] [**-i** | **--ignore-case**]
\ [**-r** | **--regex**] [**-q** | **--quiet**] *PATTERN* *REPLACE* [*STRING* ...]
.. synopsis::
string replace [-a | --all] [-f | --filter] [-i | --ignore-case]
[-r | --regex] [-q | --quiet] PATTERN REPLACE [STRING ...]
.. END SYNOPSIS

10
doc_src/cmds/string-split.rst
View File

@ -6,10 +6,12 @@ Synopsis
.. BEGIN SYNOPSIS
| ``string`` split [(**-m** | **--max**) *MAX*] [**-n** | **--no-empty**] [**-q** | **--quiet**]
\ [**-r** | **--right**] *SEP* [*STRING* ...]
| ``string`` split0 [(**-m** | **--max**) *MAX*] [**-n** | **--no-empty**] [**-q** | **--quiet**]
\ [**-r** | **--right**] [*STRING* ...]
.. synopsis::
string split [(-m | --max) MAX] [-n | --no-empty] [-q | --quiet]
[-r | --right] SEP [STRING ...]
string split0 [(-m | --max) MAX] [-n | --no-empty] [-q | --quiet]
[-r | --right] [STRING ...]
.. END SYNOPSIS

6
doc_src/cmds/string-sub.rst
View File

@ -6,8 +6,10 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` sub [(**-s** | **--start**) *START*] [(**-l** | **--length**) *LENGTH*]
\ [**-q** | **--quiet**] [*STRING* ...]
.. synopsis::
string sub [(-s | --start) START] [(-l | --length) LENGTH]
[-q | --quiet] [STRING ...]
.. END SYNOPSIS

6
doc_src/cmds/string-trim.rst
View File

@ -6,8 +6,10 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` trim [**-l** | **--left**] [**-r** | **--right**] [(**-c** | **--chars**) *CHARS*]
\ [**-q** | **--quiet**] [*STRING* ...]
.. synopsis::
string trim [-l | --left] [-r | --right] [(-c | --chars) CHARS]
[-q | --quiet] [STRING ...]
.. END SYNOPSIS

4
doc_src/cmds/string-upper.rst
View File

@ -6,7 +6,9 @@ Synopsis
.. BEGIN SYNOPSIS
``string`` upper [**-q** | **--quiet**] [*STRING* ...]
.. synopsis::
string upper [-q | --quiet] [STRING ...]
.. END SYNOPSIS

52
doc_src/cmds/string.rst
View File

@ -6,31 +6,33 @@ string - manipulate strings
Synopsis
--------
| ``string`` collect [**-N** | **--no-trim-newlines**] [*STRING* ...]
| ``string`` escape [**-n** | **--no-quoted**] [**--style=**] [*STRING* ...]
| ``string`` join [**-q** | **--quiet**] SEP [*STRING* ...]
| ``string`` join0 [**-q** | **--quiet**] [*STRING* ...]
| ``string`` length [**-q** | **--quiet**] [*STRING* ...]
| ``string`` lower [**-q** | **--quiet**] [*STRING* ...]
| ``string`` match [**-a** | **--all**] [**-e** | **--entire**] [**-i** | **--ignore-case**]
\ [**-r** | **--regex**] [**-n** | **--index**] [**-q** | **--quiet**] [**-v** | **--invert**]
\ *PATTERN* [*STRING* ...]
| ``string`` pad [**-r** | **--right**] [**-c** | **--char** *CHAR*] [**-w** | **--width** *INTEGER*]
\ [*STRING* ...]
| ``string`` repeat [(**-n** | **--count**) *COUNT*] [(**-m** | **--max**) *MAX*] [**-N** | **--no-newline**]
\ [**-q** | **--quiet**] [*STRING* ...]
| ``string`` replace [**-a** | **--all**] [**-f** | **--filter**] [**-i** | **--ignore-case**]
\ [**-r** | **--regex**] [**-q** | **--quiet**] *PATTERN* *REPLACE* [*STRING* ...]
| ``string`` split [(**-m** | **--max**) *MAX*] [**-n** | **--no-empty**] [**-q** | **--quiet**]
\ [**-r** | **--right**] *SEP* [*STRING* ...]
| ``string`` split0 [(**-m** | **--max**) *MAX*] [**-n** | **--no-empty**] [**-q** | **--quiet**]
\ [**-r** | **--right**] [*STRING* ...]
| ``string`` sub [(**-s** | **--start**) *START*] [(**-l** | **--length**) *LENGTH*]
\ [**-q** | **--quiet**] [*STRING* ...]
| ``string`` trim [**-l** | **--left**] [**-r** | **--right**] [(**-c** | **--chars**) *CHARS*]
\ [**-q** | **--quiet**] [*STRING* ...]
| ``string`` unescape [**--style=**] [*STRING* ...]
| ``string`` upper [**-q** | **--quiet**] [*STRING* ...]
.. synopsis::
string collect [-N | --no-trim-newlines] [STRING ...]
string escape [-n | --no-quoted] [--style=] [STRING ...]
string join [-q | --quiet] SEP [STRING ...]
string join0 [-q | --quiet] [STRING ...]
string length [-q | --quiet] [STRING ...]
string lower [-q | --quiet] [STRING ...]
string match [-a | --all] [-e | --entire] [-i | --ignore-case]
[-r | --regex] [-n | --index] [-q | --quiet] [-v | --invert]
PATTERN [STRING ...]
string pad [-r | --right] [-c | --char CHAR] [-w | --width INTEGER]
[STRING ...]
string repeat [(-n | --count) COUNT] [(-m | --max) MAX] [-N | --no-newline]
[-q | --quiet] [STRING ...]
string replace [-a | --all] [-f | --filter] [-i | --ignore-case]
[-r | --regex] [-q | --quiet] PATTERN REPLACE [STRING ...]
string split [(-m | --max) MAX] [-n | --no-empty] [-q | --quiet]
[-r | --right] SEP [STRING ...]
string split0 [(-m | --max) MAX] [-n | --no-empty] [-q | --quiet]
[-r | --right] [STRING ...]
string sub [(-s | --start) START] [(-l | --length) LENGTH]
[-q | --quiet] [STRING ...]
string trim [-l | --left] [-r | --right] [(-c | --chars) CHARS]
[-q | --quiet] [STRING ...]
string unescape [--style=] [STRING ...]
string upper [-q | --quiet] [STRING ...]
Description
-----------

4
doc_src/cmds/suspend.rst
View File

@ -6,7 +6,9 @@ suspend - suspend the current shell
Synopsis
--------
``suspend`` [**--force**]
.. synopsis::
suspend [--force]
Description
-----------

Some files were not shown because too many files have changed in this diff Show More