From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. Date: Thu, 26 Dec 2019 09:49:45 -0800 (PST) Message-ID: References: <<<<006e6244-dd0a-46a8-8c61-36744b3216de@default>>>> <<<<83pngcv5ha.fsf@gnu.org>>>> <<<32378b4e-d158-48d5-a48c-7afde59f5d32@default>>> <<<83d0ccuxoe.fsf@gnu.org>>> <<4a9b955a-ac97-41d9-a373-fc37b37581a4@default>> <<838smzvk86.fsf@gnu.org>> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="210048"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 38736@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Dec 26 18:50:17 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1ikXH6-000sUO-WB for geb-bug-gnu-emacs@m.gmane.org; Thu, 26 Dec 2019 18:50:17 +0100 Original-Received: from localhost ([::1]:55550 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ikXH0-00063S-V1 for geb-bug-gnu-emacs@m.gmane.org; Thu, 26 Dec 2019 12:50:10 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57077) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ikXGt-000628-EY for bug-gnu-emacs@gnu.org; Thu, 26 Dec 2019 12:50:04 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ikXGs-0006bt-3K for bug-gnu-emacs@gnu.org; Thu, 26 Dec 2019 12:50:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:50227) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ikXGr-0006bl-WD for bug-gnu-emacs@gnu.org; Thu, 26 Dec 2019 12:50:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ikXGr-0007EB-T4 for bug-gnu-emacs@gnu.org; Thu, 26 Dec 2019 12:50:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 26 Dec 2019 17:50:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 38736 X-GNU-PR-Package: emacs Original-Received: via spool by 38736-submit@debbugs.gnu.org id=B38736.157738259627763 (code B ref 38736); Thu, 26 Dec 2019 17:50:01 +0000 Original-Received: (at 38736) by debbugs.gnu.org; 26 Dec 2019 17:49:56 +0000 Original-Received: from localhost ([127.0.0.1]:56200 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ikXGl-0007Dj-MT for submit@debbugs.gnu.org; Thu, 26 Dec 2019 12:49:56 -0500 Original-Received: from userp2120.oracle.com ([156.151.31.85]:33232) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ikXGk-0007DR-DL for 38736@debbugs.gnu.org; Thu, 26 Dec 2019 12:49:54 -0500 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id xBQHiBiq190199; Thu, 26 Dec 2019 17:49:48 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2019-08-05; bh=SaNhqi9cmCQOl10qkIz7RzR1v2P/cUcOtX/b6hevCFw=; b=UcFioLgKpVcrMRc+BF/hn9+4iqhOoN7lqzqoMbL5QsuzowRAPSJLjD45wGCpVWT3eEDb mb1O9Yu3Nlk+LLsOK4iPMP4IipiGom1xQwcPegMF7LkHCNz9+W1glk9J2aQLAi8pdys4 5/B3H7L+7LNpKV5jNqlg/1Pv7FafgtcdWv/4AZ66bCndRgvtF6432Bfy34P972nNrlnf KH/lGlk1ZdCDLGcvHMFlt2Uqe8b5OWwg5kSskMtub/NAhLp5pZIsj/ybaQOe3aidcMor 6TUejBBUCEPYHMPP2qStaiVQ+vINTbbUol9AiDiBuB0USvDUOx60As7tBwgIg2IlD2Nd xg== Original-Received: from userp3020.oracle.com (userp3020.oracle.com [156.151.31.79]) by userp2120.oracle.com with ESMTP id 2x1c1r2r8m-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 26 Dec 2019 17:49:48 +0000 Original-Received: from pps.filterd (userp3020.oracle.com [127.0.0.1]) by userp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id xBQHiBDo164843; Thu, 26 Dec 2019 17:49:47 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userp3020.oracle.com with ESMTP id 2x3nn7mk4j-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 26 Dec 2019 17:49:47 +0000 Original-Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id xBQHnk54015790; Thu, 26 Dec 2019 17:49:46 GMT In-Reply-To: <<838smzvk86.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4939.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9482 signatures=668685 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1911140001 definitions=main-1912260162 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9482 signatures=668685 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1911140001 definitions=main-1912260162 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: 209.51.188.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:173790 Archived-At: > > > Like I said: eval's doc string documents this > > > feature, > > > > I see nothing in the doc string of `eval' that > > tells you `%S' in the `message' format string is > > controlled by `print-length'. Or even anything > > close to it. >=20 > Sorry, I meant eval-expression, what is run by M-:. FWIW, I made it clear that I did not use `eval-expression' (`M-:): >>> How did you get the ellipsis in *Messages*? >> >> By a call (message "Result: %S" result), >> where the value of `result' is a long list. And when you then said that (message "Result: %S" result) is "not a call, that's evaluation", I replied that it was used "in code, in a function body." The general point is that a user who wants to know about the behavior of `message', in particular for a format string with %S (but not limited to that), now needs to dig deep into a chain of doc strings or manual links. `message', like `format', is very commonly used. And (I think) %S may be the most commonly used %-sequence with `message'. We now clutter the doc of `message' with info about ` and ', and to link to the doc for `format-message'. That further complicates trying to understand `message' behavior. The `message' doc even has this gratuitous text now: To display STRING without special treatment, use (message "%s" STRING). There's no STRING in the function signature. There's nothing special about a STRING arg, and %s doesn't just print a STRING as a string - it prints anything as a string. Parameter ARGS isn't even described by name. It's OK that we say that "the rest are data to be formatted...". But, especially because of that sentence about STRING data, it's not made sufficiently clear that the "data", are Lisp objects of any kind. If you really want to have a statement about using %s to produce string output then just say that. Don't show a call to `message' where the second arg is STRING - that's misleading. Here's my suggestion, at this point. But perhaps we can do better - I don't have all the answers. 1. Say that the ARGS are Lisp objects of any kind. 2. Say that ARGS are handled by `format-message', (alas) and the result is shown as a message. 3. Users can follow the `format-message' link to get all the formatting info they need. 4. Don't mention `, ', or %. That doesn't help without more info; it's just noise. 5. If you _do_ show an example using % then use %S, and point out that it uses `prin1'. (Maybe even say that `prin1' is controlled by variables such as `print-level'.) #3 is a step back from my initial suggestion for trying to shorten the journey to info about the `prin1' variables. #5 might mitigate #3. I don't have a perfect solution, at this point. It's _really_ too bad that we had to introduce `format-message'. Going from `message' doc to `format-message' doc works against usability and understanding. As opposed to `format', the `format-message' doc talks only about the new "quoting" hoops. It forces you to move to the `format' doc to get the %-sequences info you really need, to make use of `message' in the most common ways. The "quoting" stuff should be the last, not the first, thing you read when trying to understand `message' and the like. (And `format-message' is specifically for messaging.) It would be better - if we're forced to send people to `format-message' first - if its doc string contained all of the info that's in the `format' doc, and it added the "quoting" stuff only at the end. Better, IOW, for users coming from `message' and the like to get the main format-control info (%-sequences) first. As it stands now, the cart ("quoting") is put before the horse (%-sequences), when trying to understand `message' and the like. I know that we don't want to just duplicate all the `format' doc. That's not great. But `message' is a high-level access point for using format control strings, and to get to the important info about those, you now have to get past the unhelpful, noisy doc of `format-message'. If a user stops at that doc, and doesn't plow forward to the `format' doc, then the most important messages about `message' will not get through. [This would have been avoided as a problem if `message' had not been co-opted to use `format-message', i.e., if we had instead just added a separate function, e.g., `message-with-quote-munging', which used `format-message'. Alas, that ship has sailed.]