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

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

[Jean-Christophe Helary]

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

I slightly changed the paragraph order in the documentation to (split-string) to make it more readable.

Jean-Christophe 

===========================
Improve documentation of (split-string)

* /doc/lispref/strings.texi (split-string): change paragraph
  order to improve readability.
===========================


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

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 1d766869b1..be87fbd2c3 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 @var{omit-nulls}
+is forced to @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

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

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Mon, 15 May 2017 00:45:34 +0900
> 
> I slightly changed the paragraph order in the documentation to (split-string) to make it more readable.
> 
> Jean-Christophe 
> 
> ===========================
> Improve documentation of (split-string)
> 
> * /doc/lispref/strings.texi (split-string): change paragraph
>   order to improve readability.
> ===========================

Thanks, pushed.

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.

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

[Jean-Christophe Helary]

>> ===========================
>> Improve documentation of (split-string)
>> 
>> * /doc/lispref/strings.texi (split-string): change paragraph
>>  order to improve readability.
>> ===========================
> 
> Thanks, pushed.
> 
> 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.
>> ===========================


JC

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

[Eli Zaretskii]

> 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.

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

[Jean-Christophe Helary]

Ok, I'll remember.

JC

> On May 19, 2017, at 21:56, Eli Zaretskii <eliz@gnu.org> wrote:

>> 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.

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

[Stephen Berman]

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

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

[Jean-Christophe Helary]

[-- 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

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

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Sat, 3 Jun 2017 17:50:27 +0900
> Cc: Eli Zaretskii <eliz@gnu.org>,
>  26925@debbugs.gnu.org
> 
> -If the optional argument @var{trim}
> →
> +If @var{trim}
> 
> just to adapt the text to the description of the other arguments.

Thanks, but I see no problem with the current text.  We use both
styles intermittently.

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

[Jean-Christophe Helary]

> On 2017/06/03, at 18:59, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
>> Date: Sat, 3 Jun 2017 17:50:27 +0900
>> Cc: Eli Zaretskii <eliz@gnu.org>,
>> 26925@debbugs.gnu.org
>> 
>> -If the optional argument @var{trim}
>> →
>> +If @var{trim}
>> 
>> just to adapt the text to the description of the other arguments.
> 
> Thanks, but I see no problem with the current text.  We use both
> styles intermittently.

It's up to you. I thought it was weird that all the other optional arguments were not labeled as "optional" and only this one. And I think that comes from the fact that the trim argument was added way after the documentation was originally written and added after all the examples, so that there was no connection with the description of the other arguments.

JC

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

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Sat, 3 Jun 2017 22:50:55 +0900
> Cc: stephen.berman@gmx.net,
>  26925@debbugs.gnu.org
> 
> >> -If the optional argument @var{trim}
> >> →
> >> +If @var{trim}
> >> 
> >> just to adapt the text to the description of the other arguments.
> > 
> > Thanks, but I see no problem with the current text.  We use both
> > styles intermittently.
> 
> It's up to you. I thought it was weird that all the other optional arguments were not labeled as "optional" and only this one.

That's not what I see: grepping the ELisp manual for "optional
argument" comes up with more than 200 hits.  It's quite normal to use
that.

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

[Jean-Christophe Helary]

> On 2017/06/03, at 23:46, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
>> Date: Sat, 3 Jun 2017 22:50:55 +0900
>> Cc: stephen.berman@gmx.net,
>> 26925@debbugs.gnu.org
>> 
>>>> -If the optional argument @var{trim}
>>>> →
>>>> +If @var{trim}
>>>> 
>>>> just to adapt the text to the description of the other arguments.
>>> 
>>> Thanks, but I see no problem with the current text.  We use both
>>> styles intermittently.
>> 
>> It's up to you. I thought it was weird that all the other optional arguments were not labeled as "optional" and only this one.
> 
> That's not what I see: grepping the ELisp manual for "optional
> argument" comes up with more than 200 hits.  It's quite normal to use
> that.

I am talking about this function. This function does not use "optional arguments" for its other optional arguments.

Jean-Christophe 

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

[Eli Zaretskii]

> From: Jean-Christophe Helary <jean.christophe.helary@gmail.com>
> Date: Sun, 4 Jun 2017 08:45:47 +0900
> Cc: stephen.berman@gmx.net,
>  26925@debbugs.gnu.org
> 
> >> It's up to you. I thought it was weird that all the other optional arguments were not labeled as "optional" and only this one.
> > 
> > That's not what I see: grepping the ELisp manual for "optional
> > argument" comes up with more than 200 hits.  It's quite normal to use
> > that.
> 
> 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.

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

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

Hi Eli,

>> >> It's up to you. I thought it was weird that all the other
>> > optional arguments were not labeled as "optional" and only this
>> > one.
>> > 
>> > That's not what I see: grepping the ELisp manual for "optional
>> > argument" comes up with more than 200 hits.  It's quite normal to use
>> > that.
>> 
>> 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.

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

Best regards, Michael.

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

[Jean-Christophe Helary]

> On 2017/06/04, at 16:49, Michael Albinus <michael.albinus@gmx.de> wrote:
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> Hi Eli,
> 
>>>>> It's up to you. I thought it was weird that all the other
>>>> optional arguments were not labeled as "optional" and only this
>>>> one.
>>>> 
>>>> That's not what I see: grepping the ELisp manual for "optional
>>>> argument" comes up with more than 200 hits.  It's quite normal to use
>>>> that.
>>> 
>>> 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.

That's correct. Sorry if my wording made that unclear.

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

Indeed.

When I modified the documentation the other day I just copy-pasted the trim documentation from the *end* of the function documentation (after the examples) to its beginning (following the other arguments description *before* the examples) and  missed that lack of harmonization. That's something I should have fixed then. Sorry for that.

Jean-Christophe

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.

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

[Jean-Christophe Helary]

> On 2017/06/04, at 22:57, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> Frankly, I think we are splitting hair, but anyway...

*You* are splitting hairs. If I had made that modification in the first patch I sent we would never be having this conversation.

If you don't want to see that string change, just say so and I'll drop it.

>> 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.

No, because in the function signature they are defined as optional. If people go as far as checking the doc string, they at least take a look at the function signature. There is no ambiguity there at all.

Jean-Christophe

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 00:14:14 +0900
> Cc: Michael Albinus <michael.albinus@gmx.de>,
>  26925@debbugs.gnu.org,
>  stephen.berman@gmx.net
> 
> If you don't want to see that string change, just say so and I'll drop it.

I thought I did, in the very first response to your change suggestion.

But if that makes you so much unhappy, please go ahead and make the
change.

> >> 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.
> 
> No, because in the function signature they are defined as optional.

And yet we usually do say explicitly in doc strings that optional
arguments are optional.

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

[Jean-Christophe Helary]

> 2017/06/05 0:46、Eli Zaretskii <eliz@gnu.org>のメール:
>> If you don't want to see that string change, just say so and I'll drop it.
> 
> I thought I did, in the very first response to your change suggestion.
> 
> But if that makes you so much unhappy, please go ahead and make the
> change.

It is not about me being happy or not, but about me learning what's correct and what is not. If you tell me that it is not correct to worry about various styles being used seemingly at random, then I learn from that. If you tell me that it is not necessary, which you did, then I can argue that I feel better if the few lines I was involved with are tidied up.

>> No, because in the function signature they are defined as optional.
> 
> And yet we usually do say explicitly in doc strings that optional
> arguments are optional.

Does that mean that you suggest we explicitly declare them optional in split-string ? Maybe that's something I can do.

Jean-Christophe 

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 09:33:37 +0900
> Cc: michael.albinus@gmx.de,
>  26925@debbugs.gnu.org,
>  stephen.berman@gmx.net
> 
> It is not about me being happy or not, but about me learning what's correct and what is not. If you tell me that it is not correct to worry about various styles being used seemingly at random, then I learn from that. If you tell me that it is not necessary, which you did, then I can argue that I feel better if the few lines I was involved with are tidied up.

I'm not sure I understand the last sentence, but if I do, then no, you
shouldn't worry about random changes of style, as long as the text is
accurate and is correct English.  This is, after all, descriptive
text in plain English, not a formal document.

> >> No, because in the function signature they are defined as optional.
> > 
> > And yet we usually do say explicitly in doc strings that optional
> > arguments are optional.
> 
> Does that mean that you suggest we explicitly declare them optional in split-string ?

Yes, I think so.

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

[Jean-Christophe Helary]

> 2017/06/05 11:46、Eli Zaretskii <eliz@gnu.org>のメール:
> 
>> not correct to worry about various styles being used seemingly at random, then I learn from that. If you tell me that it is not necessary, which you did, then I can argue that I feel better if the few lines I was involved with are tidied up.
> 
> I'm not sure I understand the last sentence, but if I do, then no, you
> shouldn't worry about random changes of style, as long as the text is
> accurate and is correct English.  This is, after all, descriptive
> text in plain English, not a formal document.

Ok, I understand, it was just that I felt I could make my original modification look nicer. I drop it. Thank you.

>> Does that mean that you suggest we explicitly declare them optional in split-string ?
> 
> Yes, I think so.

Ok, I'll do it.

Jean-Christophe 

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

[Jean-Christophe Helary]

>>> Does that mean that you suggest we explicitly declare them optional in split-string ?
>> 
>> Yes, I think so.
> 
> Ok, I'll do it.

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.

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

Jean-Christophe 

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.

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

[Jean-Christophe Helary]

> 2017/06/06 0:09、Eli Zaretskii <eliz@gnu.org>のメール:
> 
> In general, yes.  But it isn't a mechanical replacement.

Reading the strings, I had already figured that out :)

I'll keep in mind your comment below when I work. And I'll stop using this thread for this issue.

Jean-Christophe 

> 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.