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

[Stephen Berman <stephen.berman@gmx.net>]

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