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

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Mon, 5 Jun 2017 14:15:55 +0900
> Cc: michael.albinus@gmx.de,
>  26925@debbugs.gnu.org,
>  stephen.berman@gmx.net
> 
> I've checked subr.el and the only functions that specifically document an 
> argument as optional in the doc string are:
> alist-get
> suppress-keymap
> substitute-key-definition
> add-hook
> remove-hook
> add-to-list (only 1 out of 2)
> add-to-ordered-list
> add-to-history
> add-minor-mode
> locate-library (2/3)
> process-kill-without-query
> read-passwd
> read-char-choice
> sit-for
> momentary-string-display
> sha1 (2/3)
> match-substitute-replacement
> subst-char-in-string
> replace-regexp-in-string
> define-mail-user-agent
> set-transient-map
> make-progress-reporter (3/5)
> 
> out of 52 defuns (and 2 defsubst) that use &optional.

Indeed, the situation with doc strings is far from ideal there.  Some
doc strings just "need work" regardless of this particular issue.

> Should we modify all the remaining docstrings so that they explicitly specify 
> when an argument is optional?

In general, yes.  But it isn't a mechanical replacement.  For
starters, functions which get optional arguments from the prefix arg
don't need to state explicitly that this argument is optional, since
the reference to the prefix argument already does that.  Some strings
say "nil or omitted", which is good enough.  And in some cases
inserting "optional" would require more thorough rewrite of the doc
string, because the current style doesn't allow a simple insertion.

Thanks in advance for working on this.