From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#24051: 24.5; doc of `external-debugging-output' Date: Mon, 29 Jan 2018 06:47:10 -0800 (PST) Message-ID: References: <871t2jyqj0.fsf@russet.org.uk> <87lgghk1q6.fsf@users.sourceforge.net> <12148302-2962-4a77-b644-d791c8581ce1@default> <878tchjyvh.fsf@users.sourceforge.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1517237189 17395 195.159.176.226 (29 Jan 2018 14:46:29 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 29 Jan 2018 14:46:29 +0000 (UTC) Cc: 24051@debbugs.gnu.org, phillip.lord@russet.org.uk To: Noam Postavsky Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jan 29 15:46:24 2018 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 1egAhE-0003LI-Pc for geb-bug-gnu-emacs@m.gmane.org; Mon, 29 Jan 2018 15:46:09 +0100 Original-Received: from localhost ([::1]:42475 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1egAjF-0006UL-Fh for geb-bug-gnu-emacs@m.gmane.org; Mon, 29 Jan 2018 09:48:13 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47952) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1egAj9-0006U5-LE for bug-gnu-emacs@gnu.org; Mon, 29 Jan 2018 09:48:08 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1egAj4-0005XP-Oj for bug-gnu-emacs@gnu.org; Mon, 29 Jan 2018 09:48:07 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:39327) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1egAj4-0005Wx-JS for bug-gnu-emacs@gnu.org; Mon, 29 Jan 2018 09:48:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1egAj4-0002hH-6D for bug-gnu-emacs@gnu.org; Mon, 29 Jan 2018 09:48:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 29 Jan 2018 14:48:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 24051 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 24051-submit@debbugs.gnu.org id=B24051.151723724410318 (code B ref 24051); Mon, 29 Jan 2018 14:48:02 +0000 Original-Received: (at 24051) by debbugs.gnu.org; 29 Jan 2018 14:47:24 +0000 Original-Received: from localhost ([127.0.0.1]:47224 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1egAiS-0002gM-7X for submit@debbugs.gnu.org; Mon, 29 Jan 2018 09:47:24 -0500 Original-Received: from userp2120.oracle.com ([156.151.31.85]:58080) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1egAiQ-0002g8-AQ for 24051@debbugs.gnu.org; Mon, 29 Jan 2018 09:47:23 -0500 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w0TElBtn001832; Mon, 29 Jan 2018 14:47:14 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-2017-10-26; bh=rODB0TD9zJCcuS3O+mYpPaS9nLhhHAQhVuUBAAEjeyM=; b=baW5tqvThX1CrZ9x+Joqsj7fLZBfLN7YXrwiMSLXpkZzSjGjDf6oY/vS/kESsoSsVRnE dY9RCnGBT/XiaRf5D3cqx5kF7romZ8fuZyj5OKJ3HgkfbkqMrMzOujE4LkxFP+NuuJLa CBEPXBMZCyedxIQ0CoZ8V4qh9EniGArhWMUZRw2N1HsiH0Jv0kVnkETuQvJS27awbgk7 g8QLsHMTAhBRLPjPahRCN/eSkgBXlSE0Br9yFet8+JKNAsVnBpit4lpRyeP0agBuOdX9 YQ9XIs+f3xATKzJff9vpxNqAxNUaPqfnEGqHs2p+irB1m+RcvCNWymnL1f5QhX3bI3dh jg== Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp2120.oracle.com with ESMTP id 2ft55506ca-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 29 Jan 2018 14:47:14 +0000 Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id w0TElEbl005478 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Mon, 29 Jan 2018 14:47:14 GMT Original-Received: from abhmp0004.oracle.com (abhmp0004.oracle.com [141.146.116.10]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w0TElBX3026358; Mon, 29 Jan 2018 14:47:11 GMT In-Reply-To: <878tchjyvh.fsf@users.sourceforge.net> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4639.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8788 signatures=668655 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=819 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1711220000 definitions=main-1801290197 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:142650 Archived-At: > > And it might be good to add an example that shows use of it, > > e.g., with `print'. >=20 > Something like this? I'm not sure if this example really adds much. >=20 > (Also not entirely sure about how the texinfo markup should be for > this.) >=20 > For example > @example > (print "This is the output #'external-debugging-output) > @end example > would print @samp{This is the output} to standard error. Yes, I think so (I can't speak to the texinfo markup either). --- But I do wonder how we should talk about the standard error stream. I see only one other occurrence of "standard error" where it means the stream (and not the discussion of standard Emacs errors), and there it is referred to the same way. So I guess that's the right way to refer to it in our docs. On the other hand, would it be good to say something about the streams (the terms) "standard output" and "standard error" in node `Output Streams'? We refer to both (especially the former) in various places, but we don't say what those names mean. For a UNIX or GNU/Linux user such terms are well known, but is that to be assumed about everyone reading the Elisp manual? Just a thought/question. Actually, in `Output Streams' we do kind of say what is meant by "standard output", by describing variable `standard-output': that value is the "default output stream" Using that short description not just for the value of variable `standard-output' but also for the term "standard output" would be helpful. Similarly for "standard error": some such brief description would help. In node `Output Streams' and in other nodes we refer to the variable `standard-output'. I think it would help to use the word "variable" before that - e.g.: 'nil' specified as an output stream means to use the value of variable 'standard-output' instead; that value is the "default ^^^^^^^^ output stream", and must not be 'nil'. Yes, it should be clear from "value of", but it would be clearer still with "variable". Also, the next line describes SYMBOL, and there the use is as a function name.=20 Similarly, in other places where we mention `standard-output'. It wouldn't hurt to make clear that it is a (global) variable.