From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Thien-Thi Nguyen Newsgroups: gmane.emacs.devel Subject: Re: literal newlines in @result{} strings Date: 01 Sep 2005 03:11:56 -0400 Message-ID: References: <87k6i38mqg.fsf@jurta.org> <874q96yvcw.fsf@jurta.org> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1125559482 5116 80.91.229.2 (1 Sep 2005 07:24:42 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Thu, 1 Sep 2005 07:24:42 +0000 (UTC) Cc: rms@gnu.org, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Sep 01 09:24:39 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1EAjQd-0007HW-J0 for ged-emacs-devel@m.gmane.org; Thu, 01 Sep 2005 09:24:08 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EAjUp-0001WW-RR for ged-emacs-devel@m.gmane.org; Thu, 01 Sep 2005 03:28:27 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1EAjQY-0000a0-TP for emacs-devel@gnu.org; Thu, 01 Sep 2005 03:24:03 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1EAjQV-0000XI-Bl for emacs-devel@gnu.org; Thu, 01 Sep 2005 03:24:01 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EAjQT-0000Dq-8d for emacs-devel@gnu.org; Thu, 01 Sep 2005 03:23:57 -0400 Original-Received: from [207.245.121.137] (helo=mail.agora-net.com) by monty-python.gnu.org with esmtp (TLS-1.0:RSA_ARCFOUR_SHA:16) (Exim 4.34) id 1EAjHe-0003DW-UQ; Thu, 01 Sep 2005 03:14:51 -0400 Original-Received: from ttn by mail.agora-net.com with local (Exim 4.34) id 1EAjEq-0000NJ-Pu; Thu, 01 Sep 2005 03:11:56 -0400 Original-To: Juri Linkov In-Reply-To: <874q96yvcw.fsf@jurta.org> Original-Lines: 34 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.2 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:42545 Archived-At: Juri Linkov writes: > I meant that these functions return only a literal newline, not `\n'. > It might be confusing for readers of the reference manual when they > will try out an example and see that its real output is different from > the documented output in regard to newlines. They might start to > search for an (AFAIK, nonexistent) option that toggles a literal newline > or `\n' in return values, or even to fill a bug report. to document a literal newline, we can (a) include a literal newline between double quotes (b) include a representation of such, between double quotes (c) use a literal newline after @print{}, for output (c) is not applicable for the three functions under discussion, so i explain my rationale for choosing (b) or (a) in this case (similar thinking might be useful generally, but i haven't thought about it generally). some observations: the strings in question share some characteristics: are result values, short, end with a newline (and only one). `\n' as a representation for literal newline is used not just for documentation but also in emacs lisp strings (see node "Character Type"). this is a programmer's manual for which the audience tends to be less easily confused by seeing such a representation (although programmers can become confused over anything, with enough concentration, it is often true :-). here are some cases where i think (a) would be more indicated than (b): if there is more than one newline in the result, if the newline is not at the end of the string. thi