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: Mon, 05 Jun 2017 18:09:55 +0300 Message-ID: <83o9u2a2t8.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> <83a85nc0tu.fsf@gnu.org> <5D1082E3-48E6-4A39-B831-55BA992C7CC9@gmail.com> <8337bfbvs0.fsf@gnu.org> <83r2yz9mnb.fsf@gnu.org> <8EB2DE67-3233-4E0F-9AAB-6CE34885536A@gmail.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1496675476 18654 195.159.176.226 (5 Jun 2017 15:11:16 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 5 Jun 2017 15:11:16 +0000 (UTC) Cc: 26925@debbugs.gnu.org, stephen.berman@gmx.net, michael.albinus@gmx.de To: Jean-Christophe Helary Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jun 05 17:11:12 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 1dHteu-0004W1-Li for geb-bug-gnu-emacs@m.gmane.org; Mon, 05 Jun 2017 17:11:08 +0200 Original-Received: from localhost ([::1]:33839 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dHtf0-0004jU-10 for geb-bug-gnu-emacs@m.gmane.org; Mon, 05 Jun 2017 11:11:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53259) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dHtes-0004jI-To for bug-gnu-emacs@gnu.org; Mon, 05 Jun 2017 11:11:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dHteo-0003iN-5Y for bug-gnu-emacs@gnu.org; Mon, 05 Jun 2017 11:11:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:55041) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dHten-0003iF-VW for bug-gnu-emacs@gnu.org; Mon, 05 Jun 2017 11:11:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1dHten-0001Ri-Ra for bug-gnu-emacs@gnu.org; Mon, 05 Jun 2017 11:11: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: Mon, 05 Jun 2017 15:11: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.14966754205511 (code B ref 26925); Mon, 05 Jun 2017 15:11:01 +0000 Original-Received: (at 26925) by debbugs.gnu.org; 5 Jun 2017 15:10:20 +0000 Original-Received: from localhost ([127.0.0.1]:57718 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dHte8-0001Qp-D0 for submit@debbugs.gnu.org; Mon, 05 Jun 2017 11:10:20 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:33766) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dHte6-0001Qd-Vc for 26925@debbugs.gnu.org; Mon, 05 Jun 2017 11:10:19 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dHte0-00039I-NY for 26925@debbugs.gnu.org; Mon, 05 Jun 2017 11:10:13 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:40643) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dHtdu-000317-8Q; Mon, 05 Jun 2017 11:10:06 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1246 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dHtdt-00008g-Cf; Mon, 05 Jun 2017 11:10:05 -0400 In-reply-to: <8EB2DE67-3233-4E0F-9AAB-6CE34885536A@gmail.com> (message from Jean-Christophe Helary on Mon, 5 Jun 2017 14:15:55 +0900) 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:133296 Archived-At: > From: Jean-Christophe Helary > 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.