string docs: format options and arguments in line with other pages

There are a number of items which don't fit cleanly into the styles used in the
synopses, and have been left alone.

doc_src/cmds/string-collect.rst

@@ -23,9 +23,9 @@ A command like ``echo (cmd | string collect)`` is mostly equivalent to a quoted
 
 If invoked with multiple arguments instead of input, ``string collect`` preserves each argument separately, where the number of output arguments is equal to the number of arguments given to ``string collect``.
 
-Any trailing newlines on the input are trimmed, just as with ``"$(cmd)"`` substitution. Use ``--no-trim-newlines`` to disable this behavior, which may be useful when running a command such as ``set contents (cat filename | string collect -N)``.
+Any trailing newlines on the input are trimmed, just as with ``"$(cmd)"`` substitution. Use **--no-trim-newlines** to disable this behavior, which may be useful when running a command such as ``set contents (cat filename | string collect -N)``.
 
-With ``--allow-empty``, ``string collect`` always prints one (empty) argument. This can be used to prevent an argument from disappearing.
+With **--allow-empty**, ``string collect`` always prints one (empty) argument. This can be used to prevent an argument from disappearing.
 
 .. END DESCRIPTION
 

doc_src/cmds/string-escape.rst

@@ -18,15 +18,15 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string escape`` escapes each STRING in one of three ways. The first is ``--style=script``. This is the default. It alters the string such that it can be passed back to ``eval`` to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If ``-n`` or ``--no-quoted`` is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.
+``string escape`` escapes each *STRING* in one of three ways. The first is **--style=script**. This is the default. It alters the string such that it can be passed back to ``eval`` to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If **-n** or **--no-quoted** is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.
 
-``--style=var`` ensures the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded.
+**--style=var** ensures the string can be used as a variable name by hex encoding any non-alphanumeric characters. The string is first converted to UTF-8 before being encoded.
 
-``--style=url`` ensures the string can be used as a URL by hex encoding any character which is not legal in a URL. The string is first converted to UTF-8 before being encoded.
+**--style=url** ensures the string can be used as a URL by hex encoding any character which is not legal in a URL. The string is first converted to UTF-8 before being encoded.
 
-``--style=regex`` escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded.
+**--style=regex** escapes an input string for literal matching within a regex expression. The string is first converted to UTF-8 before being encoded.
 
-``string unescape`` performs the inverse of the ``string escape`` command. If the string to be unescaped is not properly formatted it is ignored. For example, doing ``string unescape --style=var (string escape --style=var $str)`` will return the original string. There is no support for unescaping ``--style=regex``.
+``string unescape`` performs the inverse of the ``string escape`` command. If the string to be unescaped is not properly formatted it is ignored. For example, doing ``string unescape --style=var (string escape --style=var $str)`` will return the original string. There is no support for unescaping **--style=regex**.
 
 .. END DESCRIPTION
 

doc_src/cmds/string-join.rst

@@ -18,9 +18,9 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string join`` joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise.
+``string join`` joins its *STRING* arguments into a single string separated by *SEP*, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise.
 
-``string join0`` joins its STRING arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as ``sort -z``. Exit status: 0 if at least one join was performed, or 1 otherwise.
+``string join0`` joins its *STRING* arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as ``sort -z``. Exit status: 0 if at least one join was performed, or 1 otherwise.
 
 Because Unix uses NUL as the string terminator, passing the output of ``string join0`` as an *argument* to a command (via a :ref:`command substitution <expand-command-substitution>`) won't actually work. Fish will pass the correct bytes along, but the command won't be able to tell where the argument ends. This is a limitation of Unix' argument passing.
 

doc_src/cmds/string-length.rst

@@ -10,7 +10,7 @@ Synopsis
 
 .. synopsis::
 
-    string length [-q | --quiet] [STRING ...]
+    string length [-q | --quiet] [-V | --visible] [STRING ...]
 
 .. END SYNOPSIS
 
@@ -19,9 +19,9 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string length`` reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.
+``string length`` reports the length of each string argument in characters. Exit status: 0 if at least one non-empty *STRING* was given, or 1 otherwise.
 
-With ``-V`` or ``--visible``, it uses the visible width of the arguments. That means it will discount escape sequences fish knows about, account for $fish_emoji_width and $fish_ambiguous_width. It will also count each line (separated by ``\n``) on its own, and with a carriage return (``\r``) count only the widest stretch on a line. The intent is to measure the number of columns the STRING would occupy in the current terminal.
+With **-V** or **--visible**, it uses the visible width of the arguments. That means it will discount escape sequences fish knows about, account for $fish_emoji_width and $fish_ambiguous_width. It will also count each line (separated by ``\n``) on its own, and with a carriage return (``\r``) count only the widest stretch on a line. The intent is to measure the number of columns the *STRING* would occupy in the current terminal.
 
 .. END DESCRIPTION
 

doc_src/cmds/string-lower.rst

@@ -17,7 +17,7 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string lower`` converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the ``-q`` flag you can readily test whether a string is already lowercase.
+``string lower`` converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the **-q** flag you can readily test whether a string is already lowercase.
 
 .. END DESCRIPTION
 

doc_src/cmds/string-match.rst

@@ -19,21 +19,21 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string match`` tests each STRING against PATTERN and prints matching substrings. Only the first match for each STRING is reported unless ``-a`` or ``--all`` is given, in which case all matches are reported.
+``string match`` tests each *STRING* against *PATTERN* and prints matching substrings. Only the first match for each *STRING* is reported unless **-a** or **--all** is given, in which case all matches are reported.
 
-If you specify the ``-e`` or ``--entire`` then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to ``grep`` without the ``-o`` flag). You can, obviously, achieve the same result by prepending and appending ``*`` or ``.*`` depending on whether or not you have specified the ``--regex`` flag. The ``--entire`` flag is simply a way to avoid having to complicate the pattern in that fashion and make the intent of the ``string match`` clearer. Without ``--entire`` and ``--regex``, a PATTERN will need to match the entire STRING before it will be reported.
+If you specify the **-e** or **--entire** then each matching string is printed including any prefix or suffix not matched by the pattern (equivalent to ``grep`` without the **-o** flag). You can, obviously, achieve the same result by prepending and appending **\*** or **.*** depending on whether or not you have specified the **--regex** flag. The **--entire** flag is simply a way to avoid having to complicate the pattern in that fashion and make the intent of the ``string match`` clearer. Without **--entire** and **--regex**, a *PATTERN* will need to match the entire *STRING* before it will be reported.
 
-Matching can be made case-insensitive with ``--ignore-case`` or ``-i``.
+Matching can be made case-insensitive with **--ignore-case** or **-i**.
 
-If ``--groups-only`` or ``-g`` is given, only the capturing groups will be reported - meaning the full match will be skipped. This is incompatible with ``--entire`` and ``--invert``, and requires ``--regex``. It is useful as a simple cutting tool instead of ``string replace``, so you can simply choose "this part" of a string.
+If **--groups-only** or **-g** is given, only the capturing groups will be reported - meaning the full match will be skipped. This is incompatible with **--entire** and **--invert**, and requires **--regex**. It is useful as a simple cutting tool instead of ``string replace``, so you can simply choose "this part" of a string.
 
-If ``--index`` or ``-n`` is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. A glob pattern is only considered a valid match if it matches the entire STRING.
+If **--index** or **-n** is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire *STRING* argument. A glob pattern is only considered a valid match if it matches the entire *STRING*.
 
-If ``--regex`` or ``-r`` is given, PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. With this, only the matching part of the STRING will be reported, unless ``--entire`` is given.
+If **--regex** or **-r** is given, *PATTERN* is interpreted as a Perl-compatible regular expression, which does not have to match the entire *STRING*. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. With this, only the matching part of the *STRING* will be reported, unless **--entire** is given.
 
-When matching via regular expressions, ``string match`` automatically sets variables for all named capturing groups (``(?<name>expression)``). It will create a variable with the name of the group, in the default scope, for each named capturing group, and set it to the value of the capturing group in the first matched argument. If a named capture group matched an empty string, the variable will be set to the empty string (like ``set var ""``). If it did not match, the variable will be set to nothing (like ``set var``).  When ``--regex`` is used with ``--all``, this behavior changes. Each named variable will contain a list of matches, with the first match contained in the first element, the second match in the second, and so on. If the group was empty or did not match, the corresponding element will be an empty string.
+When matching via regular expressions, ``string match`` automatically sets variables for all named capturing groups (``(?<name>expression)``). It will create a variable with the name of the group, in the default scope, for each named capturing group, and set it to the value of the capturing group in the first matched argument. If a named capture group matched an empty string, the variable will be set to the empty string (like ``set var ""``). If it did not match, the variable will be set to nothing (like ``set var``).  When **--regex** is used with **--all**, this behavior changes. Each named variable will contain a list of matches, with the first match contained in the first element, the second match in the second, and so on. If the group was empty or did not match, the corresponding element will be an empty string.
 
-If ``--invert`` or ``-v`` is used the selected lines will be only those which do not match the given glob pattern or regular expression.
+If **--invert** or **-v** is used the selected lines will be only those which do not match the given glob pattern or regular expression.
 
 Exit status: 0 if at least one match was found, or 1 otherwise.
 

doc_src/cmds/string-pad.rst

@@ -18,15 +18,15 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string pad`` extends each STRING to the given visible width by adding CHAR to the left. That means the width of all visible characters added together, excluding escape sequences and accounting for $fish_emoji_width and $fish_ambiguous_width. It is the amount of columns in a terminal the STRING occupies.
+``string pad`` extends each *STRING* to the given visible width by adding *CHAR* to the left. That means the width of all visible characters added together, excluding escape sequences and accounting for :envvar:`fish_emoji_width` and :envvar:`fish_ambiguous_width`. It is the amount of columns in a terminal the *STRING* occupies.
 
-The escape sequences reflect what *fish* knows about, and how it computes its output. Your terminal might support more escapes, or not support escape sequences that fish knows about.
+The escape sequences reflect what fish knows about, and how it computes its output. Your terminal might support more escapes, or not support escape sequences that fish knows about.
 
-If ``-r`` or ``--right`` is given, add the padding after a string.
+If **-r** or **--right** is given, add the padding after a string.
 
-If ``-c`` or ``--char`` is given, pad with CHAR instead of whitespace.
+If **-c** or **--char** is given, pad with *CHAR* instead of whitespace.
 
-The output is padded to the maximum width of all input strings. If ``-w`` or ``--width`` is given, use at least that.
+The output is padded to the maximum width of all input strings. If **-w** or **--width** is given, use at least that.
 
 .. END DESCRIPTION
 

doc_src/cmds/string-repeat.rst

@@ -18,7 +18,7 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string repeat`` repeats the STRING ``-n`` or ``--count`` times. The ``-m`` or ``--max`` option will limit the number of outputted char (excluding the newline). This option can be used by itself or in conjunction with ``--count``. If both ``--count`` and ``--max`` are present, max char will be outputed unless the final repeated string size is less than max, in that case, the string will repeat until count has been reached. Both ``--count`` and ``--max`` will accept a number greater than or equal to zero, in the case of zero, nothing will be outputed. If ``-N`` or ``--no-newline`` is given, the output won't contain a newline character at the end. Exit status: 0 if yielded string is not empty, 1 otherwise.
+``string repeat`` repeats the *STRING* **-n** or **--count** times. The **-m** or **--max** option will limit the number of outputted characters (excluding the newline). This option can be used by itself or in conjunction with **--count**. If both **--count** and **--max** are present, max char will be outputed unless the final repeated string size is less than max, in that case, the string will repeat until count has been reached. Both **--count** and **--max** will accept a number greater than or equal to zero, in the case of zero, nothing will be outputed. If **-N** or **--no-newline** is given, the output won't contain a newline character at the end. Exit status: 0 if yielded string is not empty, 1 otherwise.
 
 .. END DESCRIPTION
 

doc_src/cmds/string-replace.rst

@@ -9,7 +9,7 @@ Synopsis
 .. synopsis::
 
     string replace [-a | --all] [-f | --filter] [-i | --ignore-case]
-                   [-r | --regex] [-q | --quiet] PATTERN REPLACE [STRING ...]
+                   [-r | --regex] [-q | --quiet] PATTERN REPLACEMENT [STRING ...]
 
 .. END SYNOPSIS
 
@@ -18,11 +18,11 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string replace`` is similar to ``string match`` but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched.
+``string replace`` is similar to ``string match`` but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, *PATTERN* is treated as a literal substring to be matched.
 
-If ``-r`` or ``--regex`` is given, PATTERN is interpreted as a Perl-compatible regular expression, and REPLACEMENT can contain C-style escape sequences like ``\t`` as well as references to capturing groups by number or name as ``$n`` or ``${n}``.
+If **-r** or **--regex** is given, *PATTERN* is interpreted as a Perl-compatible regular expression, and *REPLACEMENT* can contain C-style escape sequences like **\t** as well as references to capturing groups by number or name as *$n* or *${n}*.
 
-If you specify the ``-f`` or ``--filter`` flag then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: ``a_cmd | string match pattern | string replace pattern new_pattern``. You can instead just write ``a_cmd | string replace --filter pattern new_pattern``.
+If you specify the **-f** or **--filter** flag then each input string is printed only if a replacement was done. This is useful where you would otherwise use this idiom: ``a_cmd | string match pattern | string replace pattern new_pattern``. You can instead just write ``a_cmd | string replace --filter pattern new_pattern``.
 
 Exit status: 0 if at least one replacement was performed, or 1 otherwise.
 

doc_src/cmds/string-split.rst

@@ -20,13 +20,13 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string split`` splits each STRING on the separator SEP, which can be an empty string. If ``-m`` or ``--max`` is specified, at most MAX splits are done on each STRING. If ``-r`` or ``--right`` is given, splitting is performed right-to-left. This is useful in combination with ``-m`` or ``--max``. With ``-n`` or ``--no-empty``, empty results are excluded from consideration (e.g. ``hello\n\nworld`` would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise.
+``string split`` splits each *STRING* on the separator *SEP*, which can be an empty string. If **-m** or **--max** is specified, at most MAX splits are done on each *STRING*. If **-r** or **--right** is given, splitting is performed right-to-left. This is useful in combination with **-m** or **--max**. With **-n** or **--no-empty**, empty results are excluded from consideration (e.g. ``hello\n\nworld`` would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise.
 
-Use ``-f`` or ``--fields`` to print out specific fields. Unless ``--allow-empty`` is used, if a given field does not exist, then the command exits with status 1 and does not print anything.
+Use **-f** or **--fields** to print out specific fields. Unless **--allow-empty** is used, if a given field does not exist, then the command exits with status 1 and does not print anything.
 
-See also the ``--delimiter`` option of the :ref:`read <cmd-read>` command.
+See also the **--delimiter** option of the :ref:`read <cmd-read>` command.
 
-``string split0`` splits each STRING on the zero byte (NUL). Options are the same as ``string split`` except that no separator is given.
+``string split0`` splits each *STRING* on the zero byte (NUL). Options are the same as ``string split`` except that no separator is given.
 
 ``split0`` has the important property that its output is not further split when used in a command substitution, allowing for the command substitution to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as ``find -print0`` or ``sort -z``. See split0 examples below.
 

doc_src/cmds/string-sub.rst

@@ -18,7 +18,7 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string sub`` prints a substring of each string argument. The start/end of the substring can be specified with ``-s``/``-e`` or ``--start``/``--end`` followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with ``-l`` or ``--length``. If the length or end is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise. ``--length`` is mutually exclusive with ``--end``.
+``string sub`` prints a substring of each string argument. The start/end of the substring can be specified with **-s**/**-e** or **--start**/**--end** followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with **-l** or **--length**. If the length or end is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise. **--length** is mutually exclusive with **--end**.
 
 .. END DESCRIPTION
 

doc_src/cmds/string-trim.rst

@@ -18,7 +18,7 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string trim`` removes leading and trailing whitespace from each STRING. If ``-l`` or ``--left`` is given, only leading whitespace is removed. If ``-r`` or ``--right`` is given, only trailing whitespace is trimmed. The ``-c`` or ``--chars`` switch causes the characters in CHARS to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise.
+``string trim`` removes leading and trailing whitespace from each *STRING*. If **-l** or **--left** is given, only leading whitespace is removed. If **-r** or **--right** is given, only trailing whitespace is trimmed. The **-c** or **--chars** switch causes the characters in *CHARS* to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise.
 
 .. END DESCRIPTION
 

doc_src/cmds/string-upper.rst

@@ -17,7 +17,7 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string upper`` converts each string argument to uppercase. Exit status: 0 if at least one string was converted to uppercase, else 1. This means that in conjunction with the ``-q`` flag you can readily test whether a string is already uppercase.
+``string upper`` converts each string argument to uppercase. Exit status: 0 if at least one string was converted to uppercase, else 1. This means that in conjunction with the **-q** flag you can readily test whether a string is already uppercase.
 
 .. END DESCRIPTION
 

doc_src/cmds/string.rst

@@ -39,11 +39,11 @@ Description
 
 ``string`` performs operations on strings.
 
-STRING arguments are taken from the command line unless standard input is connected to a pipe or a file, in which case they are read from standard input, one STRING per line. It is an error to supply STRING arguments on the command line and on standard input.
+*STRING* arguments are taken from the command line unless standard input is connected to a pipe or a file, in which case they are read from standard input, one *STRING* per line. It is an error to supply *STRING* arguments on the command line and on standard input.
 
 Arguments beginning with ``-`` are normally interpreted as switches; ``--`` causes the following arguments not to be treated as switches even if they begin with ``-``. Switches and required arguments are recognized only on the command line.
 
-Most subcommands accept a ``-q`` or ``--quiet`` switch, which suppresses the usual output but exits with the documented status. In this case these commands will quit early, without reading all of the available input.
+Most subcommands accept a **-q** or **--quiet** switch, which suppresses the usual output but exits with the documented status. In this case these commands will quit early, without reading all of the available input.
 
 The following subcommands are available.
 
@@ -274,7 +274,7 @@ Examples
 Regular Expressions
 -------------------
 
-Both the ``match`` and ``replace`` subcommand support regular expressions when used with the ``-r`` or ``--regex`` option. The dialect is that of PCRE2.
+Both the ``match`` and ``replace`` subcommand support regular expressions when used with the **-r** or **--regex** option. The dialect is that of PCRE2.
 
 In general, special characters are special by default, so ``a+`` matches one or more "a"s, while ``a\+`` matches an "a" and then a "+". ``(a+)`` matches one or more "a"s in a capturing group (``(?:XXXX)`` denotes a non-capturing group). For the replacement parameter of ``replace``, ``$n`` refers to the n-th group of the match. In the match parameter, ``\n`` (e.g. ``\1``) refers back to groups.
 
@@ -335,7 +335,7 @@ If you are familiar with these, it is useful to know how ``string`` differs from
 
 In contrast to these classics, ``string`` reads input either from stdin or as arguments. ``string`` also does not deal with files, so it requires redirections to be used with them.
 
-In contrast to ``grep``, ``string``'s ``match`` defaults to glob-mode, while ``replace`` defaults to literal matching. If set to regex-mode, they use PCRE regular expressions, which is comparable to ``grep``'s ``-P`` option. ``match`` defaults to printing just the match, which is like ``grep`` with ``-o`` (use ``--entire`` to enable grep-like behavior).
+In contrast to ``grep``, ``string``'s ``match`` defaults to glob-mode, while ``replace`` defaults to literal matching. If set to regex-mode, they use PCRE regular expressions, which is comparable to ``grep``'s ``-P`` option. ``match`` defaults to printing just the match, which is like ``grep`` with ``-o`` (use **--entire** to enable grep-like behavior).
 
 Like ``sed``'s ``s/old/new/`` command, ``string replace`` still prints strings that don't match. ``sed``'s ``-n`` in combination with a ``/p`` modifier or command is like ``string replace -f``.