Improve documentation of 'split-string'

* doc/lispref/strings.texi (Creating Strings): Rearrange text to
make it more readable.  (Bug#26925)

1 files changed, 13 insertions, 15 deletions

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 1d766869b1f..9436a96ead4 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -279,17 +279,26 @@ expression @var{separators} (@pxref{Regular Expressions}).  Each match
 for @var{separators} defines a splitting point; the substrings between
 splitting points are made into a list, which is returned.
 
+If @var{separators} is @code{nil} (or omitted), the default is the
+value of @code{split-string-default-separators} and the function
+behaves as if @var{omit-nulls} were @code{t}.
+
 If @var{omit-nulls} is @code{nil} (or omitted), the result contains
 null strings whenever there are two consecutive matches for
 @var{separators}, or a match is adjacent to the beginning or end of
 @var{string}.  If @var{omit-nulls} is @code{t}, these null strings are
 omitted from the result.
 
-If @var{separators} is @code{nil} (or omitted), the default is the
-value of @code{split-string-default-separators}.
+If the optional argument @var{trim} is non-@code{nil}, it should be a
+regular expression to match text to trim from the beginning and end of
+each substring.  If trimming makes the substring empty, it is treated
+as null.
+
+If you need to split a string into a list of individual command-line
+arguments suitable for @code{call-process} or @code{start-process},
+see @ref{Shell Arguments, split-string-and-unquote}.
 
-As a special case, when @var{separators} is @code{nil} (or omitted),
-null strings are always omitted from the result.  Thus:
+Examples:
 
 @example
 (split-string "  two words ")
@@ -306,8 +315,6 @@ useful.  If you need such a result, use an explicit value for
      @result{} ("" "two" "words" "")
 @end example
 
-More examples:
-
 @example
 (split-string "Soup is good food" "o")
      @result{} ("S" "up is g" "" "d f" "" "d")
@@ -354,15 +361,6 @@ practice:
 (split-string "ooo" "\\|o+" t)
      @result{} ("o" "o" "o")
 @end example
-
-If the optional argument @var{trim} is non-@code{nil}, it should be a
-regular expression to match text to trim from the beginning and end of
-each substring.  If trimming makes the substring empty, it is treated
-as null.
-
-If you need to split a string into a list of individual command-line
-arguments suitable for @code{call-process} or @code{start-process},
-see @ref{Shell Arguments, split-string-and-unquote}.
 @end defun
 
 @defvar split-string-default-separators