diff --git a/cmake/Docs.cmake b/cmake/Docs.cmake index e5c81c852..27e94be22 100644 --- a/cmake/Docs.cmake +++ b/cmake/Docs.cmake @@ -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" diff --git a/doc_src/cmds/_.rst b/doc_src/cmds/_.rst index 1be26a12c..a8d11e8b8 100644 --- a/doc_src/cmds/_.rst +++ b/doc_src/cmds/_.rst @@ -6,7 +6,9 @@ _ - call fish's translations Synopsis -------- -``_`` *STRING* +.. synopsis:: + + _ STRING Description ----------- diff --git a/doc_src/cmds/abbr.rst b/doc_src/cmds/abbr.rst index ea4e9e0a6..544f41809 100644 --- a/doc_src/cmds/abbr.rst +++ b/doc_src/cmds/abbr.rst @@ -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 ----------- diff --git a/doc_src/cmds/alias.rst b/doc_src/cmds/alias.rst index 576e45585..29d5c239a 100644 --- a/doc_src/cmds/alias.rst +++ b/doc_src/cmds/alias.rst @@ -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 diff --git a/doc_src/cmds/and.rst b/doc_src/cmds/and.rst index 6e5956ca1..f43a45bdd 100644 --- a/doc_src/cmds/and.rst +++ b/doc_src/cmds/and.rst @@ -6,7 +6,9 @@ and - conditionally execute a command Synopsis -------- -PREVIOUS; **and** *COMMAND* +.. synopsis:: + + PREVIOUS; and COMMAND Description ----------- diff --git a/doc_src/cmds/argparse.rst b/doc_src/cmds/argparse.rst index bd87f247b..29216c034 100644 --- a/doc_src/cmds/argparse.rst +++ b/doc_src/cmds/argparse.rst @@ -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 diff --git a/doc_src/cmds/begin.rst b/doc_src/cmds/begin.rst index b670faa18..5664db3ad 100644 --- a/doc_src/cmds/begin.rst +++ b/doc_src/cmds/begin.rst @@ -6,7 +6,9 @@ begin - start a new block of code Synopsis -------- -**begin**; [*COMMANDS* ...]; **end** +.. synopsis:: + + begin; [COMMANDS ...]; end Description ----------- diff --git a/doc_src/cmds/bg.rst b/doc_src/cmds/bg.rst index 731d26d36..8d9b0635c 100644 --- a/doc_src/cmds/bg.rst +++ b/doc_src/cmds/bg.rst @@ -6,7 +6,9 @@ bg - send jobs to background Synopsis -------- -``bg`` [*PID* ...] +.. synopsis:: + + bg [PID ...] Description ----------- diff --git a/doc_src/cmds/bind.rst b/doc_src/cmds/bind.rst index e708704a1..9de9ed5ca 100644 --- a/doc_src/cmds/bind.rst +++ b/doc_src/cmds/bind.rst @@ -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 ----------- diff --git a/doc_src/cmds/block.rst b/doc_src/cmds/block.rst index 7a4ed2abb..521d05dbc 100644 --- a/doc_src/cmds/block.rst +++ b/doc_src/cmds/block.rst @@ -6,7 +6,9 @@ block - temporarily block delivery of events Synopsis -------- -**block** [*OPTIONS*] +.. synopsis:: + + block [OPTIONS] Description ----------- diff --git a/doc_src/cmds/break.rst b/doc_src/cmds/break.rst index 523709be1..b625caa76 100644 --- a/doc_src/cmds/break.rst +++ b/doc_src/cmds/break.rst @@ -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 ----------- diff --git a/doc_src/cmds/breakpoint.rst b/doc_src/cmds/breakpoint.rst index a076f760f..48c225e5f 100644 --- a/doc_src/cmds/breakpoint.rst +++ b/doc_src/cmds/breakpoint.rst @@ -6,7 +6,9 @@ breakpoint - launch debug mode Synopsis -------- -``breakpoint`` +.. synopsis:: + + breakpoint Description ----------- diff --git a/doc_src/cmds/builtin.rst b/doc_src/cmds/builtin.rst index 69261ef46..dd443ce71 100644 --- a/doc_src/cmds/builtin.rst +++ b/doc_src/cmds/builtin.rst @@ -6,8 +6,10 @@ builtin - run a builtin command Synopsis -------- -| **builtin** [*OPTIONS*] *BUILTINNAME* -| **builtin** --query *BUILTINNAME* ... +.. synopsis:: + + builtin [OPTIONS] BUILTINNAME + builtin --query BUILTINNAME ... Description ----------- diff --git a/doc_src/cmds/case.rst b/doc_src/cmds/case.rst index 6f33d3dc9..e971108b8 100644 --- a/doc_src/cmds/case.rst +++ b/doc_src/cmds/case.rst @@ -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 ----------- diff --git a/doc_src/cmds/cd.rst b/doc_src/cmds/cd.rst index 38ea70d94..99e6a691e 100644 --- a/doc_src/cmds/cd.rst +++ b/doc_src/cmds/cd.rst @@ -6,7 +6,9 @@ cd - change directory Synopsis -------- -**cd** [*DIRECTORY*] +.. synopsis:: + + cd [DIRECTORY] Description ----------- diff --git a/doc_src/cmds/cdh.rst b/doc_src/cmds/cdh.rst index d85a494fd..4a47b1656 100644 --- a/doc_src/cmds/cdh.rst +++ b/doc_src/cmds/cdh.rst @@ -6,7 +6,9 @@ cdh - change to a recently visited directory Synopsis -------- -``cdh`` [*DIR*] +.. synopsis:: + + cdh [DIR] Description ----------- diff --git a/doc_src/cmds/command.rst b/doc_src/cmds/command.rst index 598172169..c0249fc14 100644 --- a/doc_src/cmds/command.rst +++ b/doc_src/cmds/command.rst @@ -6,7 +6,9 @@ command - run a program Synopsis -------- -**command** [**OPTIONS**] [*COMMANDNAME* [ARG ...]] +.. synopsis:: + + command [OPTIONS] [COMMANDNAME [ARG ...]] Description ----------- diff --git a/doc_src/cmds/commandline.rst b/doc_src/cmds/commandline.rst index b58835944..411bd83f3 100644 --- a/doc_src/cmds/commandline.rst +++ b/doc_src/cmds/commandline.rst @@ -6,7 +6,9 @@ commandline - set or get the current command line buffer Synopsis -------- -``commandline`` [*OPTIONS*] [*CMD*] +.. synopsis:: + + commandline [OPTIONS] [CMD] Description ----------- diff --git a/doc_src/cmds/complete.rst b/doc_src/cmds/complete.rst index 91c17c31c..501dbe1c0 100644 --- a/doc_src/cmds/complete.rst +++ b/doc_src/cmds/complete.rst @@ -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 ----------- diff --git a/doc_src/cmds/contains.rst b/doc_src/cmds/contains.rst index 283c765b3..7d79238c5 100644 --- a/doc_src/cmds/contains.rst +++ b/doc_src/cmds/contains.rst @@ -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 ----------- diff --git a/doc_src/cmds/continue.rst b/doc_src/cmds/continue.rst index 208f37ff1..275976c76 100644 --- a/doc_src/cmds/continue.rst +++ b/doc_src/cmds/continue.rst @@ -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 ----------- diff --git a/doc_src/cmds/count.rst b/doc_src/cmds/count.rst index 2ebd5859f..cda64bd3c 100644 --- a/doc_src/cmds/count.rst +++ b/doc_src/cmds/count.rst @@ -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 ----------- diff --git a/doc_src/cmds/dirh.rst b/doc_src/cmds/dirh.rst index d55a6de85..d226a257d 100644 --- a/doc_src/cmds/dirh.rst +++ b/doc_src/cmds/dirh.rst @@ -6,7 +6,9 @@ dirh - print directory history Synopsis -------- -``dirh`` +.. synopsis:: + + dirh Description ----------- diff --git a/doc_src/cmds/dirs.rst b/doc_src/cmds/dirs.rst index 837f892ca..613ec96e9 100644 --- a/doc_src/cmds/dirs.rst +++ b/doc_src/cmds/dirs.rst @@ -6,7 +6,9 @@ dirs - print directory stack Synopsis -------- -``dirs`` [*-c*] +.. synopsis:: + + dirs [-c] Description ----------- diff --git a/doc_src/cmds/disown.rst b/doc_src/cmds/disown.rst index c6b972604..678f33c39 100644 --- a/doc_src/cmds/disown.rst +++ b/doc_src/cmds/disown.rst @@ -6,7 +6,9 @@ disown - remove a process from the list of jobs Synopsis -------- -``disown`` [**PID** ...] +.. synopsis:: + + disown [PID ...] Description ----------- diff --git a/doc_src/cmds/echo.rst b/doc_src/cmds/echo.rst index 5cf5de3e7..9fb0adb05 100644 --- a/doc_src/cmds/echo.rst +++ b/doc_src/cmds/echo.rst @@ -6,7 +6,9 @@ echo - display a line of text Synopsis -------- -``echo`` [*options*] [*STRING*] +.. synopsis:: + + echo [options] [STRING] Description ----------- diff --git a/doc_src/cmds/else.rst b/doc_src/cmds/else.rst index 2d93270b1..62aa655d0 100644 --- a/doc_src/cmds/else.rst +++ b/doc_src/cmds/else.rst @@ -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 ----------- diff --git a/doc_src/cmds/emit.rst b/doc_src/cmds/emit.rst index b4696b08d..6b11a15f3 100644 --- a/doc_src/cmds/emit.rst +++ b/doc_src/cmds/emit.rst @@ -6,7 +6,9 @@ emit - emit a generic event Synopsis -------- -``emit`` *EVENT_NAME* [*ARGUMENTS* ...] +.. synopsis:: + + emit EVENT_NAME [ARGUMENTS ...] Description ----------- diff --git a/doc_src/cmds/end.rst b/doc_src/cmds/end.rst index 4300a7cd8..9ceb17e1e 100644 --- a/doc_src/cmds/end.rst +++ b/doc_src/cmds/end.rst @@ -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 ----------- diff --git a/doc_src/cmds/eval.rst b/doc_src/cmds/eval.rst index 867158c2f..2b05fdb84 100644 --- a/doc_src/cmds/eval.rst +++ b/doc_src/cmds/eval.rst @@ -6,7 +6,9 @@ eval - evaluate the specified commands Synopsis -------- -**eval** [*COMMANDS* ...] +.. synopsis:: + + eval [COMMANDS ...] Description ----------- diff --git a/doc_src/cmds/exec.rst b/doc_src/cmds/exec.rst index 25987acf9..28be61f50 100644 --- a/doc_src/cmds/exec.rst +++ b/doc_src/cmds/exec.rst @@ -6,7 +6,9 @@ exec - execute command in current process Synopsis -------- -**exec** *COMMAND* +.. synopsis:: + + exec COMMAND Description ----------- diff --git a/doc_src/cmds/exit.rst b/doc_src/cmds/exit.rst index 8ff971896..f3f481c9a 100644 --- a/doc_src/cmds/exit.rst +++ b/doc_src/cmds/exit.rst @@ -7,7 +7,9 @@ exit - exit the shell Synopsis -------- -**exit** [*code*] +.. synopsis:: + + exit [code] Description ----------- diff --git a/doc_src/cmds/false.rst b/doc_src/cmds/false.rst index e7c5ec9f6..1910e8647 100644 --- a/doc_src/cmds/false.rst +++ b/doc_src/cmds/false.rst @@ -6,7 +6,9 @@ false - return an unsuccessful result Synopsis -------- -**false** +.. synopsis:: + + false Description ----------- diff --git a/doc_src/cmds/fg.rst b/doc_src/cmds/fg.rst index 6bf4be662..7db7cc1dd 100644 --- a/doc_src/cmds/fg.rst +++ b/doc_src/cmds/fg.rst @@ -6,7 +6,9 @@ fg - bring job to foreground Synopsis -------- -``fg`` [*PID*] +.. synopsis:: + + fg [PID] Description ----------- diff --git a/doc_src/cmds/fish.rst b/doc_src/cmds/fish.rst index 22670453d..559c1f8c0 100644 --- a/doc_src/cmds/fish.rst +++ b/doc_src/cmds/fish.rst @@ -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 ----------- diff --git a/doc_src/cmds/fish_add_path.rst b/doc_src/cmds/fish_add_path.rst index d397e0ff8..9fedec533 100644 --- a/doc_src/cmds/fish_add_path.rst +++ b/doc_src/cmds/fish_add_path.rst @@ -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 diff --git a/doc_src/cmds/fish_breakpoint_prompt.rst b/doc_src/cmds/fish_breakpoint_prompt.rst index 8eeb4025c..af8f12838 100644 --- a/doc_src/cmds/fish_breakpoint_prompt.rst +++ b/doc_src/cmds/fish_breakpoint_prompt.rst @@ -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 diff --git a/doc_src/cmds/fish_command_not_found.rst b/doc_src/cmds/fish_command_not_found.rst index bed9071e8..007f4ef00 100644 --- a/doc_src/cmds/fish_command_not_found.rst +++ b/doc_src/cmds/fish_command_not_found.rst @@ -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 diff --git a/doc_src/cmds/fish_config.rst b/doc_src/cmds/fish_config.rst index 08503d723..1ae913680 100644 --- a/doc_src/cmds/fish_config.rst +++ b/doc_src/cmds/fish_config.rst @@ -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 ----------- diff --git a/doc_src/cmds/fish_git_prompt.rst b/doc_src/cmds/fish_git_prompt.rst index 88b0dadfa..3d8a1623c 100644 --- a/doc_src/cmds/fish_git_prompt.rst +++ b/doc_src/cmds/fish_git_prompt.rst @@ -6,12 +6,15 @@ fish_git_prompt - output git information for use in a prompt Synopsis -------- -``fish_git_prompt`` +.. synopsis:: + + fish_git_prompt + :: - function fish_prompt - printf '%s' $PWD (fish_git_prompt) ' $ ' - end + function fish_prompt + printf '%s' $PWD (fish_git_prompt) ' $ ' + end Description diff --git a/doc_src/cmds/fish_greeting.rst b/doc_src/cmds/fish_greeting.rst index 722addee8..c5c06b903 100644 --- a/doc_src/cmds/fish_greeting.rst +++ b/doc_src/cmds/fish_greeting.rst @@ -6,7 +6,10 @@ fish_greeting - display a welcome message in interactive shells Synopsis -------- -**fish_greeting** +.. synopsis:: + + fish_greeting + :: function fish_greeting diff --git a/doc_src/cmds/fish_hg_prompt.rst b/doc_src/cmds/fish_hg_prompt.rst index 0fa7dc3aa..b2f96dbc1 100644 --- a/doc_src/cmds/fish_hg_prompt.rst +++ b/doc_src/cmds/fish_hg_prompt.rst @@ -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 diff --git a/doc_src/cmds/fish_indent.rst b/doc_src/cmds/fish_indent.rst index 855def6f4..bab448292 100644 --- a/doc_src/cmds/fish_indent.rst +++ b/doc_src/cmds/fish_indent.rst @@ -7,7 +7,9 @@ fish_indent - indenter and prettifier Synopsis -------- -**fish_indent** [*OPTIONS*] [*FILE* ...] +.. synopsis:: + + fish_indent [OPTIONS] [FILE ...] Description diff --git a/doc_src/cmds/fish_is_root_user.rst b/doc_src/cmds/fish_is_root_user.rst index 45c030a89..9bfb73ba5 100644 --- a/doc_src/cmds/fish_is_root_user.rst +++ b/doc_src/cmds/fish_is_root_user.rst @@ -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 ----------- diff --git a/doc_src/cmds/fish_key_reader.rst b/doc_src/cmds/fish_key_reader.rst index 32074a63c..ed26554a7 100644 --- a/doc_src/cmds/fish_key_reader.rst +++ b/doc_src/cmds/fish_key_reader.rst @@ -6,7 +6,9 @@ fish_key_reader - explore what characters keyboard keys send Synopsis -------- -**fish_key_reader** [*OPTIONS*] +.. synopsis:: + + fish_key_reader [OPTIONS] Description ----------- diff --git a/doc_src/cmds/fish_mode_prompt.rst b/doc_src/cmds/fish_mode_prompt.rst index 62ffa09b9..42632f12c 100644 --- a/doc_src/cmds/fish_mode_prompt.rst +++ b/doc_src/cmds/fish_mode_prompt.rst @@ -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 diff --git a/doc_src/cmds/fish_opt.rst b/doc_src/cmds/fish_opt.rst index 4ff8ac573..140c5aaf2 100644 --- a/doc_src/cmds/fish_opt.rst +++ b/doc_src/cmds/fish_opt.rst @@ -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 ----------- diff --git a/doc_src/cmds/fish_prompt.rst b/doc_src/cmds/fish_prompt.rst index 74ace8422..097bac4bd 100644 --- a/doc_src/cmds/fish_prompt.rst +++ b/doc_src/cmds/fish_prompt.rst @@ -6,7 +6,10 @@ fish_prompt - define the appearance of the command line prompt Synopsis -------- -``fish_prompt`` +.. synopsis:: + + fish_prompt + :: function fish_prompt diff --git a/doc_src/cmds/fish_status_to_signal.rst b/doc_src/cmds/fish_status_to_signal.rst index 2ef79dee0..4d81db8c1 100644 --- a/doc_src/cmds/fish_status_to_signal.rst +++ b/doc_src/cmds/fish_status_to_signal.rst @@ -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 diff --git a/doc_src/cmds/fish_svn_prompt.rst b/doc_src/cmds/fish_svn_prompt.rst index 589faf9cb..edc86b65d 100644 --- a/doc_src/cmds/fish_svn_prompt.rst +++ b/doc_src/cmds/fish_svn_prompt.rst @@ -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 diff --git a/doc_src/cmds/fish_title.rst b/doc_src/cmds/fish_title.rst index 7c4046a1f..d286d1445 100644 --- a/doc_src/cmds/fish_title.rst +++ b/doc_src/cmds/fish_title.rst @@ -6,7 +6,10 @@ fish_title - define the terminal's title Synopsis -------- -``fish_title`` +.. synopsis:: + + fish_title + :: function fish_title diff --git a/doc_src/cmds/fish_update_completions.rst b/doc_src/cmds/fish_update_completions.rst index b8d155dbb..340dbb343 100644 --- a/doc_src/cmds/fish_update_completions.rst +++ b/doc_src/cmds/fish_update_completions.rst @@ -6,7 +6,9 @@ fish_update_completions - update completions using manual pages Synopsis -------- -``fish_update_completions`` +.. synopsis:: + + fish_update_completions Description ----------- diff --git a/doc_src/cmds/fish_vcs_prompt.rst b/doc_src/cmds/fish_vcs_prompt.rst index 9e5da1be0..15eb3997d 100644 --- a/doc_src/cmds/fish_vcs_prompt.rst +++ b/doc_src/cmds/fish_vcs_prompt.rst @@ -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 diff --git a/doc_src/cmds/for.rst b/doc_src/cmds/for.rst index 36e15ddce..4d5064cc5 100644 --- a/doc_src/cmds/for.rst +++ b/doc_src/cmds/for.rst @@ -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 ----------- diff --git a/doc_src/cmds/funced.rst b/doc_src/cmds/funced.rst index b78920b01..596baf4e8 100644 --- a/doc_src/cmds/funced.rst +++ b/doc_src/cmds/funced.rst @@ -6,7 +6,9 @@ funced - edit a function interactively Synopsis -------- -``funced`` [**OPTIONS**] *NAME* +.. synopsis:: + + funced [OPTIONS] NAME Description ----------- diff --git a/doc_src/cmds/funcsave.rst b/doc_src/cmds/funcsave.rst index 923530999..76b3a0dde 100644 --- a/doc_src/cmds/funcsave.rst +++ b/doc_src/cmds/funcsave.rst @@ -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 diff --git a/doc_src/cmds/function.rst b/doc_src/cmds/function.rst index 2ec3d990a..abb3ba33c 100644 --- a/doc_src/cmds/function.rst +++ b/doc_src/cmds/function.rst @@ -6,7 +6,9 @@ function - create a function Synopsis -------- -**function** *NAME* [*OPTIONS*]; *BODY*; **end** +.. synopsis:: + + function NAME [OPTIONS]; BODY; end Description diff --git a/doc_src/cmds/functions.rst b/doc_src/cmds/functions.rst index bb7b0e801..cdd0da710 100644 --- a/doc_src/cmds/functions.rst +++ b/doc_src/cmds/functions.rst @@ -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 ----------- diff --git a/doc_src/cmds/help.rst b/doc_src/cmds/help.rst index 1b6af322b..8a344338b 100644 --- a/doc_src/cmds/help.rst +++ b/doc_src/cmds/help.rst @@ -6,7 +6,9 @@ help - display fish documentation Synopsis -------- -``help`` [*SECTION*] +.. synopsis:: + + help [SECTION] Description ----------- diff --git a/doc_src/cmds/history.rst b/doc_src/cmds/history.rst index 46be50164..cb4b36cbb 100644 --- a/doc_src/cmds/history.rst +++ b/doc_src/cmds/history.rst @@ -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 ----------- diff --git a/doc_src/cmds/if.rst b/doc_src/cmds/if.rst index 2f6aa65ce..771fcdfe5 100644 --- a/doc_src/cmds/if.rst +++ b/doc_src/cmds/if.rst @@ -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 ----------- diff --git a/doc_src/cmds/isatty.rst b/doc_src/cmds/isatty.rst index cbd52bb2e..f3417aca2 100644 --- a/doc_src/cmds/isatty.rst +++ b/doc_src/cmds/isatty.rst @@ -6,7 +6,9 @@ isatty - test if a file descriptor is a terminal Synopsis -------- -``isatty`` [*FILE DESCRIPTOR*] +.. synopsis:: + + isatty [FILE DESCRIPTOR] Description ----------- diff --git a/doc_src/cmds/jobs.rst b/doc_src/cmds/jobs.rst index 0453247de..f84dd592c 100644 --- a/doc_src/cmds/jobs.rst +++ b/doc_src/cmds/jobs.rst @@ -6,7 +6,9 @@ jobs - print currently running jobs Synopsis -------- -``jobs`` [*OPTIONS*] [*PID* | %*JOBID*] +.. synopsis:: + + jobs [OPTIONS] [PID | %JOBID] Description diff --git a/doc_src/cmds/math.rst b/doc_src/cmds/math.rst index 7f0b043f1..db203669e 100644 --- a/doc_src/cmds/math.rst +++ b/doc_src/cmds/math.rst @@ -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 diff --git a/doc_src/cmds/nextd.rst b/doc_src/cmds/nextd.rst index 72f6d1b8b..6ea10f316 100644 --- a/doc_src/cmds/nextd.rst +++ b/doc_src/cmds/nextd.rst @@ -6,7 +6,9 @@ nextd - move forward through directory history Synopsis -------- -``nextd`` [**-l** | **--list**] [*POS*] +.. synopsis:: + + nextd [-l | --list] [POS] Description ----------- diff --git a/doc_src/cmds/not.rst b/doc_src/cmds/not.rst index 3168f1956..6e7a9c375 100644 --- a/doc_src/cmds/not.rst +++ b/doc_src/cmds/not.rst @@ -6,7 +6,9 @@ not - negate the exit status of a job Synopsis -------- -**not** *COMMAND* [*options* ...] +.. synopsis:: + + not COMMAND [options ...] Description diff --git a/doc_src/cmds/open.rst b/doc_src/cmds/open.rst index 3bff34c4e..9f9875d27 100644 --- a/doc_src/cmds/open.rst +++ b/doc_src/cmds/open.rst @@ -6,7 +6,9 @@ open - open file in its default application Synopsis -------- -``open`` *FILES* ... +.. synopsis:: + + open FILES ... Description diff --git a/doc_src/cmds/or.rst b/doc_src/cmds/or.rst index 8a932d802..52c547661 100644 --- a/doc_src/cmds/or.rst +++ b/doc_src/cmds/or.rst @@ -6,7 +6,9 @@ or - conditionally execute a command Synopsis -------- -*COMMAND1*; **or** *COMMAND2* +.. synopsis:: + + COMMAND1; or COMMAND2 Description ----------- diff --git a/doc_src/cmds/popd.rst b/doc_src/cmds/popd.rst index 38567b5df..3eb6b8ad5 100644 --- a/doc_src/cmds/popd.rst +++ b/doc_src/cmds/popd.rst @@ -6,7 +6,9 @@ popd - move through directory stack Synopsis -------- -``popd`` +.. synopsis:: + + popd Description ----------- diff --git a/doc_src/cmds/prevd.rst b/doc_src/cmds/prevd.rst index 2a1345b52..3d9a310ee 100644 --- a/doc_src/cmds/prevd.rst +++ b/doc_src/cmds/prevd.rst @@ -6,7 +6,9 @@ prevd - move backward through directory history Synopsis -------- -``prevd`` [**-l** | **--list**] [*POS*] +.. synopsis:: + + prevd [-l | --list] [POS] Description ----------- diff --git a/doc_src/cmds/printf.rst b/doc_src/cmds/printf.rst index 2febca422..be66487e8 100644 --- a/doc_src/cmds/printf.rst +++ b/doc_src/cmds/printf.rst @@ -6,7 +6,9 @@ printf - display text according to a format string Synopsis -------- -``printf`` *FORMAT* [*ARGUMENT* ...] +.. synopsis:: + + printf FORMAT [ARGUMENT ...] Description ----------- diff --git a/doc_src/cmds/prompt_hostname.rst b/doc_src/cmds/prompt_hostname.rst index 1751abaa2..386e62138 100644 --- a/doc_src/cmds/prompt_hostname.rst +++ b/doc_src/cmds/prompt_hostname.rst @@ -6,7 +6,9 @@ prompt_hostname - print the hostname, shortened for use in the prompt Synopsis -------- -``prompt_hostname`` +.. synopsis:: + + prompt_hostname Description ----------- diff --git a/doc_src/cmds/prompt_login.rst b/doc_src/cmds/prompt_login.rst index 2741e4b6a..b69dbc5d4 100644 --- a/doc_src/cmds/prompt_login.rst +++ b/doc_src/cmds/prompt_login.rst @@ -6,7 +6,9 @@ prompt_login - describe the login suitable for prompt Synopsis -------- -``prompt_login`` +.. synopsis:: + + prompt_login Description ----------- diff --git a/doc_src/cmds/prompt_pwd.rst b/doc_src/cmds/prompt_pwd.rst index 7437694f7..47a5a7fd9 100644 --- a/doc_src/cmds/prompt_pwd.rst +++ b/doc_src/cmds/prompt_pwd.rst @@ -6,7 +6,9 @@ prompt_pwd - print pwd suitable for prompt Synopsis -------- -``prompt_pwd`` +.. synopsis:: + + prompt_pwd Description ----------- diff --git a/doc_src/cmds/psub.rst b/doc_src/cmds/psub.rst index f83e086cc..bf0be47d1 100644 --- a/doc_src/cmds/psub.rst +++ b/doc_src/cmds/psub.rst @@ -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 ----------- diff --git a/doc_src/cmds/pushd.rst b/doc_src/cmds/pushd.rst index 66fd57a33..95f256816 100644 --- a/doc_src/cmds/pushd.rst +++ b/doc_src/cmds/pushd.rst @@ -6,7 +6,9 @@ pushd - push directory to directory stack Synopsis -------- -``pushd`` *DIRECTORY* +.. synopsis:: + + pushd DIRECTORY Description ----------- diff --git a/doc_src/cmds/pwd.rst b/doc_src/cmds/pwd.rst index ce4244bdc..52fc3e107 100644 --- a/doc_src/cmds/pwd.rst +++ b/doc_src/cmds/pwd.rst @@ -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 diff --git a/doc_src/cmds/random.rst b/doc_src/cmds/random.rst index 6f77da8d1..f1a4ff8a4 100644 --- a/doc_src/cmds/random.rst +++ b/doc_src/cmds/random.rst @@ -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 ----------- diff --git a/doc_src/cmds/read.rst b/doc_src/cmds/read.rst index c52049b4b..1978ece47 100644 --- a/doc_src/cmds/read.rst +++ b/doc_src/cmds/read.rst @@ -6,7 +6,9 @@ read - read line of input into variables Synopsis -------- -``read`` [*options*] [*VARIABLE* ...] +.. synopsis:: + + read [options] [VARIABLE ...] Description ----------- diff --git a/doc_src/cmds/realpath.rst b/doc_src/cmds/realpath.rst index 2c8b0d9b4..3bf603246 100644 --- a/doc_src/cmds/realpath.rst +++ b/doc_src/cmds/realpath.rst @@ -7,7 +7,9 @@ realpath - convert a path to an absolute path without symlinks Synopsis -------- -**realpath** [*options*] *PATH* +.. synopsis:: + + realpath [options] PATH Description ----------- diff --git a/doc_src/cmds/return.rst b/doc_src/cmds/return.rst index 9bd84d001..405336f09 100644 --- a/doc_src/cmds/return.rst +++ b/doc_src/cmds/return.rst @@ -7,7 +7,9 @@ return - stop the current inner function Synopsis -------- -**return** [*n*] +.. synopsis:: + + return [n] Description ----------- diff --git a/doc_src/cmds/set.rst b/doc_src/cmds/set.rst index d0c36871e..b5363c2e1 100644 --- a/doc_src/cmds/set.rst +++ b/doc_src/cmds/set.rst @@ -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 ----------- diff --git a/doc_src/cmds/set_color.rst b/doc_src/cmds/set_color.rst index 15ba0f0fd..6c3bde437 100644 --- a/doc_src/cmds/set_color.rst +++ b/doc_src/cmds/set_color.rst @@ -6,7 +6,9 @@ set_color - set the terminal color Synopsis -------- -``set_color`` [*OPTIONS*] *VALUE* +.. synopsis:: + + set_color [OPTIONS] VALUE Description ----------- diff --git a/doc_src/cmds/source.rst b/doc_src/cmds/source.rst index 7baf42e15..25fe67f9f 100644 --- a/doc_src/cmds/source.rst +++ b/doc_src/cmds/source.rst @@ -6,8 +6,10 @@ source - evaluate contents of file Synopsis -------- -| **source** *FILE* [*arguments* ...] -| ``somecommand`` | **source** +.. synopsis:: + + source FILE [arguments ...] + somecommand | source Description diff --git a/doc_src/cmds/status.rst b/doc_src/cmds/status.rst index 076cfc612..670e2ba93 100644 --- a/doc_src/cmds/status.rst +++ b/doc_src/cmds/status.rst @@ -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 ----------- diff --git a/doc_src/cmds/string-collect.rst b/doc_src/cmds/string-collect.rst index 2851c09d2..fbacdd99b 100644 --- a/doc_src/cmds/string-collect.rst +++ b/doc_src/cmds/string-collect.rst @@ -6,7 +6,9 @@ Synopsis .. BEGIN SYNOPSIS -``string`` collect [**-N** | **--no-trim-newlines**] [*STRING* ...] +.. synopsis:: + + string collect [-N | --no-trim-newlines] [STRING ...] .. END SYNOPSIS diff --git a/doc_src/cmds/string-escape.rst b/doc_src/cmds/string-escape.rst index 4fffcae9b..cddc80184 100644 --- a/doc_src/cmds/string-escape.rst +++ b/doc_src/cmds/string-escape.rst @@ -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 diff --git a/doc_src/cmds/string-join.rst b/doc_src/cmds/string-join.rst index 658077b55..cf6a60c4a 100644 --- a/doc_src/cmds/string-join.rst +++ b/doc_src/cmds/string-join.rst @@ -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 diff --git a/doc_src/cmds/string-length.rst b/doc_src/cmds/string-length.rst index 03728116c..ec4fb9ed4 100644 --- a/doc_src/cmds/string-length.rst +++ b/doc_src/cmds/string-length.rst @@ -8,7 +8,9 @@ Synopsis .. BEGIN SYNOPSIS -``string`` length [**-q** | **--quiet**] [*STRING* ...] +.. synopsis:: + + string length [-q | --quiet] [STRING ...] .. END SYNOPSIS diff --git a/doc_src/cmds/string-lower.rst b/doc_src/cmds/string-lower.rst index a265bd049..08a36ca19 100644 --- a/doc_src/cmds/string-lower.rst +++ b/doc_src/cmds/string-lower.rst @@ -6,7 +6,9 @@ Synopsis .. BEGIN SYNOPSIS -``string`` lower [**-q** | **--quiet**] [*STRING* ...] +.. synopsis:: + + string lower [-q | --quiet] [STRING ...] .. END SYNOPSIS diff --git a/doc_src/cmds/string-match.rst b/doc_src/cmds/string-match.rst index 555ca6468..ceebaa0c4 100644 --- a/doc_src/cmds/string-match.rst +++ b/doc_src/cmds/string-match.rst @@ -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 diff --git a/doc_src/cmds/string-pad.rst b/doc_src/cmds/string-pad.rst index 4daaccbf6..c70ea6d5e 100644 --- a/doc_src/cmds/string-pad.rst +++ b/doc_src/cmds/string-pad.rst @@ -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 diff --git a/doc_src/cmds/string-repeat.rst b/doc_src/cmds/string-repeat.rst index dce27c6ba..53ada8f62 100644 --- a/doc_src/cmds/string-repeat.rst +++ b/doc_src/cmds/string-repeat.rst @@ -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 diff --git a/doc_src/cmds/string-replace.rst b/doc_src/cmds/string-replace.rst index 0dcc6039e..2017f0c5b 100644 --- a/doc_src/cmds/string-replace.rst +++ b/doc_src/cmds/string-replace.rst @@ -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 diff --git a/doc_src/cmds/string-split.rst b/doc_src/cmds/string-split.rst index 70e68b30b..480fb3336 100644 --- a/doc_src/cmds/string-split.rst +++ b/doc_src/cmds/string-split.rst @@ -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 diff --git a/doc_src/cmds/string-sub.rst b/doc_src/cmds/string-sub.rst index 368a0419a..784abe2e1 100644 --- a/doc_src/cmds/string-sub.rst +++ b/doc_src/cmds/string-sub.rst @@ -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 diff --git a/doc_src/cmds/string-trim.rst b/doc_src/cmds/string-trim.rst index 89832ac7a..16a67ab1a 100644 --- a/doc_src/cmds/string-trim.rst +++ b/doc_src/cmds/string-trim.rst @@ -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 diff --git a/doc_src/cmds/string-upper.rst b/doc_src/cmds/string-upper.rst index e8c7fe441..47f68fdf8 100644 --- a/doc_src/cmds/string-upper.rst +++ b/doc_src/cmds/string-upper.rst @@ -6,7 +6,9 @@ Synopsis .. BEGIN SYNOPSIS -``string`` upper [**-q** | **--quiet**] [*STRING* ...] +.. synopsis:: + + string upper [-q | --quiet] [STRING ...] .. END SYNOPSIS diff --git a/doc_src/cmds/string.rst b/doc_src/cmds/string.rst index b101d6e7a..15a853945 100644 --- a/doc_src/cmds/string.rst +++ b/doc_src/cmds/string.rst @@ -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 ----------- diff --git a/doc_src/cmds/suspend.rst b/doc_src/cmds/suspend.rst index 093490bd6..853044b87 100644 --- a/doc_src/cmds/suspend.rst +++ b/doc_src/cmds/suspend.rst @@ -6,7 +6,9 @@ suspend - suspend the current shell Synopsis -------- -``suspend`` [**--force**] +.. synopsis:: + + suspend [--force] Description ----------- diff --git a/doc_src/cmds/switch.rst b/doc_src/cmds/switch.rst index 735b6ba40..4079501a7 100644 --- a/doc_src/cmds/switch.rst +++ b/doc_src/cmds/switch.rst @@ -6,7 +6,9 @@ switch - conditionally execute a block of commands Synopsis -------- -**switch** *VALUE*; [**case** [*GLOB* ...]; [*COMMANDS* ...]; ...] **end** +.. synopsis:: + + switch VALUE; [case [GLOB ...]; [COMMANDS ...]; ...] end Description ----------- diff --git a/doc_src/cmds/test.rst b/doc_src/cmds/test.rst index a1b44921b..10ff53472 100644 --- a/doc_src/cmds/test.rst +++ b/doc_src/cmds/test.rst @@ -6,8 +6,10 @@ test - perform tests on files and text Synopsis -------- -| ``test`` [*EXPRESSION*] -| ``[`` [*EXPRESSION*] ] +.. synopsis:: + + test [EXPRESSION] + [ [EXPRESSION] ] Description diff --git a/doc_src/cmds/time.rst b/doc_src/cmds/time.rst index db2d73926..064f642fc 100644 --- a/doc_src/cmds/time.rst +++ b/doc_src/cmds/time.rst @@ -6,7 +6,9 @@ time - measure how long a command or block takes Synopsis -------- -**time** *COMMAND* +.. synopsis:: + + time COMMAND Description ----------- diff --git a/doc_src/cmds/trap.rst b/doc_src/cmds/trap.rst index 76603f8a9..117fb5974 100644 --- a/doc_src/cmds/trap.rst +++ b/doc_src/cmds/trap.rst @@ -6,7 +6,9 @@ trap - perform an action when the shell receives a signal Synopsis -------- -``trap`` [*options*] [[*ARG*] *REASON* ... ] +.. synopsis:: + + trap [options] [[ARG] REASON ... ] Description ----------- diff --git a/doc_src/cmds/true.rst b/doc_src/cmds/true.rst index 4010a9d73..9ffa1667f 100644 --- a/doc_src/cmds/true.rst +++ b/doc_src/cmds/true.rst @@ -6,7 +6,9 @@ true - return a successful result Synopsis -------- -``true`` +.. synopsis:: + + true Description ----------- diff --git a/doc_src/cmds/type.rst b/doc_src/cmds/type.rst index 6d7b7d54a..45bc17bc0 100644 --- a/doc_src/cmds/type.rst +++ b/doc_src/cmds/type.rst @@ -6,7 +6,9 @@ type - locate a command and describe its type Synopsis -------- -``type`` [*options*] *NAME* [...] +.. synopsis:: + + type [options] NAME [...] Description ----------- diff --git a/doc_src/cmds/ulimit.rst b/doc_src/cmds/ulimit.rst index f34f644a8..7ad3cd00d 100644 --- a/doc_src/cmds/ulimit.rst +++ b/doc_src/cmds/ulimit.rst @@ -6,7 +6,9 @@ ulimit - set or get resource usage limits Synopsis -------- -``ulimit`` [**options**] [*limit*] +.. synopsis:: + + ulimit [options] [limit] Description diff --git a/doc_src/cmds/umask.rst b/doc_src/cmds/umask.rst index 442394bb9..a455024e7 100644 --- a/doc_src/cmds/umask.rst +++ b/doc_src/cmds/umask.rst @@ -6,7 +6,9 @@ umask - set or get the file creation mode mask Synopsis -------- -``umask`` [**options**] [*MASK*] +.. synopsis:: + + umask [options] [MASK] Description diff --git a/doc_src/cmds/vared.rst b/doc_src/cmds/vared.rst index 487ee7e56..0feda6108 100644 --- a/doc_src/cmds/vared.rst +++ b/doc_src/cmds/vared.rst @@ -6,7 +6,9 @@ vared - interactively edit the value of an environment variable Synopsis -------- -``vared`` *VARIABLE_NAME* +.. synopsis:: + + vared VARIABLE_NAME Description ----------- diff --git a/doc_src/cmds/wait.rst b/doc_src/cmds/wait.rst index 2bd1bf693..2144f5f58 100644 --- a/doc_src/cmds/wait.rst +++ b/doc_src/cmds/wait.rst @@ -6,7 +6,9 @@ wait - wait for jobs to complete Synopsis -------- -``wait`` [**-n** | **--any**] [*PID* | *PROCESS_NAME*] ... +.. synopsis:: + + wait [-n | --any] [PID | PROCESS_NAME] ... Description ----------- diff --git a/doc_src/cmds/while.rst b/doc_src/cmds/while.rst index eaa08ce11..7e0060536 100644 --- a/doc_src/cmds/while.rst +++ b/doc_src/cmds/while.rst @@ -6,7 +6,9 @@ while - perform a set of commands multiple times Synopsis -------- -**while** *CONDITION*; *COMMANDS*; **end** +.. synopsis:: + + while CONDITION; COMMANDS; end Description ----------- diff --git a/doc_src/conf.py b/doc_src/conf.py index 22708e950..fee3ace93 100644 --- a/doc_src/conf.py +++ b/doc_src/conf.py @@ -37,14 +37,17 @@ def issue_role(name, rawtext, text, lineno, inliner, options=None, content=None) # -- Load our extensions ------------------------------------------------- def setup(app): - # Our own pygments lexer + # Our own pygments lexers from sphinx.highlighting import lexers this_dir = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, this_dir) from fish_indent_lexer import FishIndentLexer + from fish_synopsis import FishSynopsisDirective, FishSynopsisLexer lexers["fish-docs-samples"] = FishIndentLexer() + lexers["fish-synopsis"] = FishSynopsisLexer() + app.add_directive("synopsis", FishSynopsisDirective) app.add_config_value("issue_url", default=None, rebuild="html") app.add_role("issue", issue_role) diff --git a/doc_src/fish_synopsis.py b/doc_src/fish_synopsis.py new file mode 100644 index 000000000..51df271e1 --- /dev/null +++ b/doc_src/fish_synopsis.py @@ -0,0 +1,158 @@ +# Pygments lexer for a fish command synopsis. +# +# Example usage: +# echo 'string match [OPTIONS] [STRING]' | pygmentize -f terminal256 -l doc_src/fish_synopsis.py:FishSynopsisLexer -x + +from docutils import nodes +from pygments.lexer import Lexer +from pygments.token import ( + Generic, + Name, + Operator, + Punctuation, + Text, +) +import re +from sphinx.directives.code import CodeBlock + + +class FishSynopsisDirective(CodeBlock): + """A custom directive that describes a command's grammar.""" + + has_content = True + required_arguments = 0 + + def run(self): + if self.env.app.builder.name != "man": + self.arguments = ["fish-synopsis"] + return CodeBlock.run(self) + lexer = FishSynopsisLexer() + result = nodes.line_block() + for (start, tok, text) in lexer.get_tokens_unprocessed("\n".join(self.content)): + if ( # Literal text. + (tok in (Name.Function, Name.Constant) and not text.isupper()) + or text.startswith("-") # Literal option, even if it's uppercase. + or tok in (Operator, Punctuation) + or text + == " ]" # Tiny hack: the closing bracket of the test(1) alias is a literal. + ): + node = nodes.strong(text=text) + elif ( + tok in (Name.Constant, Name.Function) and text.isupper() + ): # Placeholder parameter. + node = nodes.emphasis(text=text) + else: # Grammar metacharacter or whitespace. + node = nodes.inline(text=text) + result.append(node) + return [result] + + +lexer_rules = [ + (re.compile(pattern), token) + for pattern, token in ( + # Hack: treat the "[ expr ]" alias of builtin test as command token (not as grammar + # metacharacter). This works because we write it without spaces in the grammar (like + # "[OPTIONS]"). + (r"\[ | \]", Name.Constant), + # Statement separators. + (r"\n", Text.Whitespace), + (r";", Punctuation), + (r" +", Text.Whitespace), + # Operators have different highlighting than commands or parameters. + (r"\b(and|not|or|time)\b", Operator), + # Keywords that are not in command position. + (r"\b(if|in)\b", Name.Function), + # Grammar metacharacters. + (r"[()[\]|]", Generic.Other), + (r"\.\.\.", Generic.Other), + # Parameters. + (r"[\w-]+", Name.Constant), + (r"[=%]", Name.Constant), + ( + r"[<>]", + Name.Constant, + ), # Redirection are highlighted like parameters by default. + ) +] + + +class FishSynopsisLexer(Lexer): + name = "FishSynopsisLexer" + aliases = ["fish-synopsis"] + + is_before_command_token = None + + def next_token(self, rule: str, offset: int, has_continuation_line: bool): + for pattern, token_kind in lexer_rules: + m = pattern.match(rule, pos=offset) + if m is None: + continue + if token_kind is Name.Constant and self.is_before_command_token: + token_kind = Name.Function + + if has_continuation_line: + # Traditional case: rules with continuation lines only have a single command. + self.is_before_command_token = False + else: + if m.group() in ("\n", ";") or token_kind is Operator: + self.is_before_command_token = True + elif token_kind in (Name.Constant, Name.Function): + self.is_before_command_token = False + + return m, token_kind, m.end() + return None, None, offset + + def get_tokens_unprocessed(self, input_text): + """Return a list of (start, tok, value) tuples. + + start is the index into the string + tok is the token type (as above) + value is the string contents of the token + """ + """ + A synopsis consists of multiple rules. Each rule can have continuation lines, which + are expected to be indented: + + cmd foo [--quux] + [ARGUMENT] ... + cmd bar + + We'll split the input into rules. This is easy for a traditional synopsis because each + non-indented line starts a new rule. However, we also want to support code blocks: + + switch VALUE + [case [GLOB ...] + [COMMAND ...]] + end + + which makes this format ambiguous. Hack around this by always adding "end" to the + current rule, which is enough in practice. + """ + rules = [] + rule = [] + for line in list(input_text.splitlines()) + [""]: + if rule and not line.startswith(" "): + rules.append(rule) + rule = [] + if line == "end": + rules[-1].append(line) + continue + rule.append(line) + result = [] + for rule in rules: + offset = 0 + self.is_before_command_token = True + has_continuation_line = rule[-1].startswith(" ") + rule = "\n".join(rule) + "\n" + while True: + match, token_kind, offset = self.next_token( + rule, offset, has_continuation_line + ) + if match is None: + break + text = match.group() + result.append((match.start(), token_kind, text)) + assert offset == len(rule), "cannot tokenize leftover text: '{}'".format( + rule[offset:] + ) + return result