bug#24051: 24.5; doc of `external-debugging-output'

[Noam Postavsky <npostavs@users.sourceforge.net>]

[-- Attachment #1: Type: text/plain, Size: 956 bytes --]

phillip.lord@russet.org.uk (Phillip Lord) writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>> 1. Please consider documenting this in the Elisp manual, e.g., where we
>> document `print'.
>>
>> 2. The doc string should enclose "print" in `...':
>>
>>  Write CHARACTER to stderr.
>>  You can call `print' while debugging emacs, and pass it this function
>>  to make it write to the debugging output.
>
>
> And also where we document "streams". Personally, I like the idea of
> adding "stderr" as an alias...

Yeah, I think it's already occured to me twice at least where I couldn't
remember the name of this function, and I ended up searching through
src/print.c.

I don't think it fits under "Output Functions" though, as it says:

    This section describes the Lisp functions for printing Lisp
    objects--converting objects into their printed representation.

It's rather an example of an output stream, so it should go in the
previous section:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 1609 bytes --]

From e670ceada77e094cc42732a131a2fea8e782fd71 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Sun, 28 Jan 2018 18:16:48 -0500
Subject: [PATCH v1] Document external-debugging-output in the Elisp Manual
 (Bug#24051)

* doc/lispref/streams.texi (Output Streams): List
external-debugging-output.
* src/print.c (Fexternal_debugging_output): Quote `print' in
docstring.
---
 doc/lispref/streams.texi | 6 ++++++
 src/print.c              | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index a25a5bfe84..8501466af6 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -530,6 +530,12 @@ Output Streams
 Calling @code{concat} converts the list to a string so you can see its
 contents more clearly.
 
+@findex stderr
+@defun external-debugging-output character
+This function can be useful as an output stream when debugging.  It
+writes @var{character} to the standard error stream.
+@end defun
+
 @node Output Functions
 @section Output Functions
 
diff --git a/src/print.c b/src/print.c
index 6cf3c37e5e..64fc7eda31 100644
--- a/src/print.c
+++ b/src/print.c
@@ -748,7 +748,7 @@ DEFUN ("print", Fprint, Sprint, 1, 2, 0,
 
 DEFUN ("external-debugging-output", Fexternal_debugging_output, Sexternal_debugging_output, 1, 1, 0,
        doc: /* Write CHARACTER to stderr.
-You can call print while debugging emacs, and pass it this function
+You can call `print' while debugging emacs, and pass it this function
 to make it write to the debugging output.  */)
   (Lisp_Object character)
 {
-- 
2.11.0