string split: update docs

doc_src/cmds/string-split.rst

@@ -18,7 +18,9 @@ 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). Use ``-f`` or ``--fields`` to print out specific fields. 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.
 
 See also the ``--delimiter`` option of the :ref:`read <cmd-read>` command.
 
@@ -49,7 +51,7 @@ Examples
     b
     c
 
-    >_ string split -f1,3 '' abc
+    >_ string split --allow-empty -f1,3,5 '' abc
     a
     c