bug#26925: Improve /doc/lispref/strings.texi (split-string) documentation

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: Jean-Christophe Helary <jean.christophe.helary@gmail.com>,  
> 26925@debbugs.gnu.org,  stephen.berman@gmx.net
> Date: Sun, 04 Jun 2017 09:49:24 +0200
> 
> >> I am talking about this function. This function does not use
> >> "optional arguments" for its other optional arguments.
> >
> > Sorry, but I don't see that as a significant evidence.  There's
> > nothing special about this function that would cause us to treat it
> > any different from the rest.
> >
> > Once again, these are matters of personal style, and IMO we shouldn't
> > make changes motivated by style preferences alone.
> 
> I don't believe Jean-Christophe is speaking about his personal style. He
> claims that two different personal styles are used in the `split-string'
> description in the lispref manual: SEPARATORS and OMIT-NULLS are
> described as arguments, and TRIM is described as "optional argument"
> explicitely. He proposes to harmonize this, which I support.

Frankly, I think we are splitting hair, but anyway...

SEPARATORS and OMIT-NULLS are not described as arguments, they are
described as _optional_ arguments.  The manual describes them using
this template:

  If FOO is nil or omitted, ...

Note the "omitted" part: it means that the argument is optional.  So
the description of the 3rd argument, viz.:

  If the optional argument TRIM is non-'nil', ...

is equivalent to that of the other two.  It just uses a slightly
different wording to express the same fact.  And I think it's a Good
Thing: repeating the same wording 3 times in a row makes the reading a
bore, so breaking the boredom by using a slight variation is IMO and
IME not a deficiency, but an advantage.

IOW, the above two methods of describing optional arguments are
exactly equivalent, and therefore I see no need for using only one of
them consistently for documenting any given function.

Of course, personal stylistic preferences might cause you to disagree,
but that brings me back to my point...

> And btw, the docstring of `split-string' does not speak about TRIM as
> "optional argument" either.

Which is a mistake, IMO, because the doc string uses neither of the
above 2 patterns, and so makes it sound like these arguments are not
optional at all.