[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#24051: 24.5; doc of `external-debugging-output'
From: |
Noam Postavsky |
Subject: |
bug#24051: 24.5; doc of `external-debugging-output' |
Date: |
Mon, 29 Jan 2018 19:38:38 -0500 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.0.90 (gnu/linux) |
tags 24051 + patch
quit
Eli Zaretskii <eliz@gnu.org> writes:
> You should use @print{} for displaying the results (inside the
> @example, not outside it). There are examples of that elsewhere in
> streams.texi.
Ah, so there are. I see some of them use @group, and some don't. I
can't see any visible effect from @group so I left it out.
>> I don't think it fits under "Output Functions" though, as it says:
> But you can also mention it there, with a cross-reference.
Hmm, it's a bit of an awkward fit, but yes, worth a mention (and actual
cross-references are only to nodes, not a single function entry, so "the
previous section" is already all the cross-reference needed, right?).
> stderr is not a function, so @findex is not appropriate for it. I'd
> rather suggest this:
>
> @cindex @code{stderr} stream, use for debugging
Okay, here's the full patch, please double check my texinfo.
>From bfdc940eaa265bc17aae79cf97fc9775ec3d6e56 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Sun, 28 Jan 2018 18:16:48 -0500
Subject: [PATCH v2] 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 | 22 ++++++++++++++++++----
src/print.c | 2 +-
2 files changed, 19 insertions(+), 5 deletions(-)
diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index a25a5bfe84..119dd02808 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -503,7 +503,7 @@ Output Streams
@end group
@group
-(print "This is the output" 'eat-output)
+(print "This is the output" #'eat-output)
@result{} "This is the output"
@end group
@@ -530,6 +530,19 @@ Output Streams
Calling @code{concat} converts the list to a string so you can see its
contents more clearly.
+@cindex @code{stderr} stream, use for debugging
+@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.
+
+For example
+@example
+(print "This is the output" #'external-debugging-output)
+@print{} This is the output
+@result{} "This is the output"
+@end example
+@end defun
+
@node Output Functions
@section Output Functions
@@ -570,9 +583,10 @@ Output Functions
@end example
In the functions below, @var{stream} stands for an output stream.
-(See the previous section for a description of output streams.) If
-@var{stream} is @code{nil} or omitted, it defaults to the value of
-@code{standard-output}.
+(See the previous section for a description of output streams. A
+useful stream value for debugging, @code{external-debugging-output},
+is also mentioned there.) If @var{stream} is @code{nil} or omitted,
+it defaults to the value of @code{standard-output}.
@defun print object &optional stream
@cindex Lisp printer
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
bug#24051: 24.5; doc of `external-debugging-output', Eli Zaretskii, 2018/01/29