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
2024-11-10 07:04:29 +00:00 · 2022-01-09 15:09:46 +01:00 · 2022-01-09 15:09:46 +01:00 · c0d1e41313
commit c0d1e41313
parent 1c21e26d08
113 changed files with 631 additions and 238 deletions
--- 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"
--- a/doc_src/cmds/_.rst
+++ b/doc_src/cmds/_.rst
@ -6,7 +6,9 @@ _ - call fish's translations
 Synopsis
 --------

-``_`` *STRING*
+.. synopsis::
+
+    _ STRING

 Description
 -----------
--- 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
 -----------
--- 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
--- 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
 -----------
--- 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
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
--- 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
--- 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
--- 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
 -----------
--- 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
--- 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
--- 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
--- 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
--- 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
 -----------
--- 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
 -----------
--- 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
--- 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
 -----------
--- 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
--- 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
--- 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
--- 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
--- 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
 -----------
--- 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
--- 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
 -----------
--- 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
 -----------
--- 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
--- 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
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
--- 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
--- 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
 -----------
--- 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
--- 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
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
 -----------
--- 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
--- 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
 -----------
--- 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

--- 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

--- 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

--- 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

--- 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

--- 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

--- 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

--- 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

--- 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

--- 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

--- 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

--- 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

--- 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

--- 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
 -----------
--- 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
 -----------
--- a/Show more
+++ b/Show more