From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#26925: Improve /doc/lispref/strings.texi (split-string) documentation Date: Sun, 04 Jun 2017 16:57:33 +0300 Message-ID: <83a85nc0tu.fsf@gnu.org> References: <93AB3C85-27C1-48FF-8C3D-B90B4CF33670@gmail.com> <83o9up2hli.fsf@gnu.org> <7F0AE9BE-93FF-4CF7-8F76-AE1BD0CFDDDC@gmail.com> <83inkx2eeu.fsf@gnu.org> <87vaoxoty1.fsf@rosalinde> <3D9A3600-CF3D-4DD9-866C-CBEE8F692B25@gmail.com> <83o9u5bde1.fsf@gnu.org> <12A8E2CE-F2F5-4DB9-88DE-BCD40513EEBA@gmail.com> <83h8zxb02p.fsf@gnu.org> <98B33B3E-AB18-4BDB-A012-5270F3FCD7C2@gmail.com> <83bmq4bhpv.fsf@gnu.org> <87efv09oqj.fsf@detlef> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1496584690 23056 195.159.176.226 (4 Jun 2017 13:58:10 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 4 Jun 2017 13:58:10 +0000 (UTC) Cc: 26925@debbugs.gnu.org, jean.christophe.helary@gmail.com, stephen.berman@gmx.net To: Michael Albinus Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Jun 04 15:58:05 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dHW2e-0005g5-Mq for geb-bug-gnu-emacs@m.gmane.org; Sun, 04 Jun 2017 15:58:04 +0200 Original-Received: from localhost ([::1]:57101 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dHW2j-0006Mf-9e for geb-bug-gnu-emacs@m.gmane.org; Sun, 04 Jun 2017 09:58:09 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47869) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dHW2c-0006MP-ST for bug-gnu-emacs@gnu.org; Sun, 04 Jun 2017 09:58:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dHW2b-0003Co-Vi for bug-gnu-emacs@gnu.org; Sun, 04 Jun 2017 09:58:02 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:53227) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dHW2b-0003Cg-SO for bug-gnu-emacs@gnu.org; Sun, 04 Jun 2017 09:58:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1dHW2b-0002MP-Lz for bug-gnu-emacs@gnu.org; Sun, 04 Jun 2017 09:58:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 04 Jun 2017 13:58:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 26925 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 26925-submit@debbugs.gnu.org id=B26925.14965846809064 (code B ref 26925); Sun, 04 Jun 2017 13:58:01 +0000 Original-Received: (at 26925) by debbugs.gnu.org; 4 Jun 2017 13:58:00 +0000 Original-Received: from localhost ([127.0.0.1]:55904 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dHW2Z-0002M8-SA for submit@debbugs.gnu.org; Sun, 04 Jun 2017 09:58:00 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:56874) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dHW2Y-0002Lw-H9 for 26925@debbugs.gnu.org; Sun, 04 Jun 2017 09:57:59 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dHW2S-0002yt-8P for 26925@debbugs.gnu.org; Sun, 04 Jun 2017 09:57:53 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:54371) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dHW2M-0002pU-95; Sun, 04 Jun 2017 09:57:46 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3432 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dHW2L-0002KA-Dv; Sun, 04 Jun 2017 09:57:45 -0400 In-reply-to: <87efv09oqj.fsf@detlef> (message from Michael Albinus on Sun, 04 Jun 2017 09:49:24 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:133252 Archived-At: > From: Michael Albinus > Cc: Jean-Christophe Helary , 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.