From c0d1e41313244063112d48b67794cba200be8ba3 Mon Sep 17 00:00:00 2001 From: Johannes Altmanninger Date: Sun, 9 Jan 2022 15:09:46 +0100 Subject: [PATCH] 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 --- cmake/Docs.cmake | 5 +- doc_src/cmds/_.rst | 4 +- doc_src/cmds/abbr.rst | 14 +- doc_src/cmds/alias.rst | 8 +- doc_src/cmds/and.rst | 4 +- doc_src/cmds/argparse.rst | 4 +- doc_src/cmds/begin.rst | 4 +- doc_src/cmds/bg.rst | 4 +- doc_src/cmds/bind.rst | 14 +- doc_src/cmds/block.rst | 4 +- doc_src/cmds/break.rst | 12 +- doc_src/cmds/breakpoint.rst | 4 +- doc_src/cmds/builtin.rst | 6 +- doc_src/cmds/case.rst | 10 +- doc_src/cmds/cd.rst | 4 +- doc_src/cmds/cdh.rst | 4 +- doc_src/cmds/command.rst | 4 +- doc_src/cmds/commandline.rst | 4 +- doc_src/cmds/complete.rst | 6 +- doc_src/cmds/contains.rst | 4 +- doc_src/cmds/continue.rst | 4 +- doc_src/cmds/count.rst | 8 +- doc_src/cmds/dirh.rst | 4 +- doc_src/cmds/dirs.rst | 4 +- doc_src/cmds/disown.rst | 4 +- doc_src/cmds/echo.rst | 4 +- doc_src/cmds/else.rst | 4 +- doc_src/cmds/emit.rst | 4 +- doc_src/cmds/end.rst | 20 +-- doc_src/cmds/eval.rst | 4 +- doc_src/cmds/exec.rst | 4 +- doc_src/cmds/exit.rst | 4 +- doc_src/cmds/false.rst | 4 +- doc_src/cmds/fg.rst | 4 +- doc_src/cmds/fish.rst | 6 +- doc_src/cmds/fish_add_path.rst | 6 +- doc_src/cmds/fish_breakpoint_prompt.rst | 5 +- doc_src/cmds/fish_command_not_found.rst | 8 +- doc_src/cmds/fish_config.rst | 8 +- doc_src/cmds/fish_git_prompt.rst | 11 +- doc_src/cmds/fish_greeting.rst | 5 +- doc_src/cmds/fish_hg_prompt.rst | 5 +- doc_src/cmds/fish_indent.rst | 4 +- doc_src/cmds/fish_is_root_user.rst | 4 +- doc_src/cmds/fish_key_reader.rst | 4 +- doc_src/cmds/fish_mode_prompt.rst | 5 +- doc_src/cmds/fish_opt.rst | 7 +- doc_src/cmds/fish_prompt.rst | 5 +- doc_src/cmds/fish_status_to_signal.rst | 5 +- doc_src/cmds/fish_svn_prompt.rst | 5 +- doc_src/cmds/fish_title.rst | 5 +- doc_src/cmds/fish_update_completions.rst | 4 +- doc_src/cmds/fish_vcs_prompt.rst | 5 +- doc_src/cmds/for.rst | 4 +- doc_src/cmds/funced.rst | 4 +- doc_src/cmds/funcsave.rst | 6 +- doc_src/cmds/function.rst | 4 +- doc_src/cmds/functions.rst | 12 +- doc_src/cmds/help.rst | 4 +- doc_src/cmds/history.rst | 20 +-- doc_src/cmds/if.rst | 10 +- doc_src/cmds/isatty.rst | 4 +- doc_src/cmds/jobs.rst | 4 +- doc_src/cmds/math.rst | 4 +- doc_src/cmds/nextd.rst | 4 +- doc_src/cmds/not.rst | 4 +- doc_src/cmds/open.rst | 4 +- doc_src/cmds/or.rst | 4 +- doc_src/cmds/popd.rst | 4 +- doc_src/cmds/prevd.rst | 4 +- doc_src/cmds/printf.rst | 4 +- doc_src/cmds/prompt_hostname.rst | 4 +- doc_src/cmds/prompt_login.rst | 4 +- doc_src/cmds/prompt_pwd.rst | 4 +- doc_src/cmds/psub.rst | 4 +- doc_src/cmds/pushd.rst | 4 +- doc_src/cmds/pwd.rst | 6 +- doc_src/cmds/random.rst | 12 +- doc_src/cmds/read.rst | 4 +- doc_src/cmds/realpath.rst | 4 +- doc_src/cmds/return.rst | 4 +- doc_src/cmds/set.rst | 16 ++- doc_src/cmds/set_color.rst | 4 +- doc_src/cmds/source.rst | 6 +- doc_src/cmds/status.rst | 42 +++--- doc_src/cmds/string-collect.rst | 4 +- doc_src/cmds/string-escape.rst | 6 +- doc_src/cmds/string-join.rst | 6 +- doc_src/cmds/string-length.rst | 4 +- doc_src/cmds/string-lower.rst | 4 +- doc_src/cmds/string-match.rst | 8 +- doc_src/cmds/string-pad.rst | 6 +- doc_src/cmds/string-repeat.rst | 6 +- doc_src/cmds/string-replace.rst | 6 +- doc_src/cmds/string-split.rst | 10 +- doc_src/cmds/string-sub.rst | 6 +- doc_src/cmds/string-trim.rst | 6 +- doc_src/cmds/string-upper.rst | 4 +- doc_src/cmds/string.rst | 52 ++++---- doc_src/cmds/suspend.rst | 4 +- doc_src/cmds/switch.rst | 4 +- doc_src/cmds/test.rst | 6 +- doc_src/cmds/time.rst | 4 +- doc_src/cmds/trap.rst | 4 +- doc_src/cmds/true.rst | 4 +- doc_src/cmds/type.rst | 4 +- doc_src/cmds/ulimit.rst | 4 +- doc_src/cmds/umask.rst | 4 +- doc_src/cmds/vared.rst | 4 +- doc_src/cmds/wait.rst | 4 +- doc_src/cmds/while.rst | 4 +- doc_src/conf.py | 5 +- doc_src/fish_synopsis.py | 158 +++++++++++++++++++++++ 113 files changed, 631 insertions(+), 238 deletions(-) create mode 100644 doc_src/fish_synopsis.py 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