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

[Jean-Christophe Helary <jean.christophe.helary@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 352 bytes --]

Just one tiny bit of cleanup:

-If the optional argument @var{trim}
→
+If @var{trim}

just to adapt the text to the description of the other arguments.

===========================
Improve documentation of 'split-string'

 * doc/lispref/strings.texi (Creating Strings): Correct a wording in `split-string'.
===========================


[-- Attachment #2: strings.texi.diff --]
[-- Type: application/octet-stream, Size: 910 bytes --]

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index e80e778bec..b500b3d355 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -289,10 +289,9 @@ null strings whenever there are two consecutive matches for
 @var{string}.  If @var{omit-nulls} is @code{t}, these null strings are
 omitted from the result.
 
-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 @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},

[-- Attachment #3: Type: text/plain, Size: 1743 bytes --]


> On 2017/05/19, at 22:30, Stephen Berman <stephen.berman@gmx.net> wrote:
> 
> On Fri, 19 May 2017 15:56:41 +0300 Eli Zaretskii <eliz@gnu.org> wrote:
> 
>>> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
>>> Date: Fri, 19 May 2017 21:23:57 +0900
>>> Cc: 26925-done@debbugs.gnu.org
>>> 
>>>> One nit: please don't refer to functions with syntax that looks like a
>>>> function call, as in (split-string) above, or foo() for C sources.
>>>> The GNU Coding Standards frown on such references, because they look
>>>> like a call to a function with no arguments, which is not what is
>>>> meant there.  We use 'split-string' and 'foo' instead, i.e. the name
>>>> of the function in quotes.
>>> 
>>> Thank you Eli.
>>> 
>>> So the function name should have been quoted in both occurrences?
>>> 
>>>>> ===========================
>>>>> Improve documentation of 'split-string'
>>>>> 
>>>>> * /doc/lispref/strings.texi 'split-string': change paragraph
>>>>> order to improve readability.
>>>>> ===========================
>> 
>> No, only in the first occurrence.  In the ChangeLog-style entries, we
>> always put function names in parentheses.
> 
> Yes for code ChangeLogs, but for the Texinfo sources, the convention for
> ChangeLog entries seems to be to put the node name in parentheses, and
> then the function name would be quoted in the entry, as usual, e.g.:
> 
>    * doc/lispref/strings.texi (Creating Strings): Change paragraph
>      order of `split-string' definition to improve readability.
> 
> This convention of putting the node name in parens is apparently
> undocumented, but it's what `C-x 4 a' does and (probably that's why)
> almost all the ChangeLog entries for the Texinfo sources follow it.
> 
> Steve Berman