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

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

[Drew Adams]

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.


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

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

[Phillip Lord]

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...

Phil

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

[Noam Postavsky]

[-- 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

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

[Drew Adams]

> 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:

Agreed.

And it might be good to add an example that shows use of it,
e.g., with `print'.

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

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:
>
> And it might be good to add an example that shows use of it,
> e.g., with `print'.

Something like this?  I'm not sure if this example really adds much.

(Also not entirely sure about how the texinfo markup should be for
this.)

    For example
    @example
    (print "This is the output #'external-debugging-output)
    @end example
    would print @samp{This is the output} to standard error.

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

[Drew Adams]

> > And it might be good to add an example that shows use of it,
> > e.g., with `print'.
> 
> Something like this?  I'm not sure if this example really adds much.
> 
> (Also not entirely sure about how the texinfo markup should be for
> this.)
> 
>     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. 

Similarly, in other places where we mention `standard-output'.
It wouldn't hurt to make clear that it is a (global) variable.

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

[Eli Zaretskii]

> Date: Mon, 29 Jan 2018 06:47:10 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 24051@debbugs.gnu.org, phillip.lord@russet.org.uk
> 
> 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)

That's strange, because I see it in no less than 7 other nodes of the
ELisp manual, and most of those nodes mention it more than once.

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

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Date: Sun, 28 Jan 2018 19:24:18 -0500
> Cc: 24051@debbugs.gnu.org, phillip.lord@russet.org.uk
> 
> (Also not entirely sure about how the texinfo markup should be for
> this.)
> 
>     For example
>     @example
>     (print "This is the output #'external-debugging-output)
>     @end example
>     would print @samp{This is the output} to standard error.

You should use @print{} for displaying the results (inside the
@example, not outside it).  There are examples of that elsewhere in
streams.texi.

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

[Noam Postavsky]

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

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.


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

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'

[Michael Albinus]

Noam Postavsky <npostavs@users.sourceforge.net> writes:

Hi Noam,

> 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.

@group prevents page breaks in printed manuals in the following lines.

> 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?).

You can also declare an @anchor, and use it as target of a cross reference.

HTH. Best regards, Michael.

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

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: Eli Zaretskii <eliz@gnu.org>,  24051@debbugs.gnu.org,  phillip.lord@russet.org.uk
> Date: Tue, 30 Jan 2018 09:22:43 +0100
> 
> > 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.
> 
> @group prevents page breaks in printed manuals in the following lines.

Right, and for that reason it's a good idea to use @group in this
case, to make sure @print{} doesn't get separated from the preceding
code fragment.

I actually suggest to have the Texinfo manual be loaded in some Info
buffer in your Emacs sessions; that's what I do.  Then you can quickly
consult it whenever the need arises.  That manual is very well
indexed, so finding what you need is usually a snap.

> > 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?).
> 
> You can also declare an @anchor, and use it as target of a cross reference.

Right.  Also, the 2-argument form of @xref commands can also sometimes
land you on the text that is the second arg (at least with some Info
readers).

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

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Cc: 24051@debbugs.gnu.org,  drew.adams@oracle.com,  phillip.lord@russet.org.uk
> Date: Mon, 29 Jan 2018 19:38:38 -0500
> 
> 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?).

"Previous section" is harder to follow in the on-line manual,
especially if some day that section will acquire subsections.

> Okay, here's the full patch, please double check my texinfo.

LGTM, with the minor comments already voiced.

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

[Noam Postavsky]

tags 24051 fixed
close 24051 26.1
quit

Eli Zaretskii <eliz@gnu.org> writes:

> LGTM, with the minor comments already voiced.

Pushed to emacs-26 with fixes.

[1: 2b35ed0b0c]: 2018-01-30 22:29:13 -0500
  Document external-debugging-output in the Elisp Manual (Bug#24051)
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=2b35ed0b0c49698337758004bd5e6062a3aaffab

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

[Phillip Lord]

Thanks for fixing this; apologies for being too late to the party to add
anything useful.

Phil

Noam Postavsky <npostavs@users.sourceforge.net> writes:

> tags 24051 fixed
> close 24051 26.1
> quit
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
>> LGTM, with the minor comments already voiced.
>
> Pushed to emacs-26 with fixes.
>
> [1: 2b35ed0b0c]: 2018-01-30 22:29:13 -0500
>   Document external-debugging-output in the Elisp Manual (Bug#24051)
>   https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=2b35ed0b0c49698337758004bd5e6062a3aaffab

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

[Drew Adams]

> > 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)
> 
> That's strange, because I see it in no less than 7 other nodes of the
> ELisp manual, and most of those nodes mention it more than once.

You're right: Subprocess Creation, Synchronous Processes,
Asynchronous Processes, Output from Processes, Filter
Functions, Displaying Messages, and Batch Mode.

Not sure what I meant by the text you cite, but the rest
of what I wrote there should make clear that, although we
use the term in several places, we don't actually say what
we mean by it.  This bit, for instance:

 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.

Some short description, at least, would be helpful.

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

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Date: Sun, 28 Jan 2018 18:22:41 -0500
> Cc: 24051@debbugs.gnu.org
> 
> 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:

But you can also mention it there, with a cross-reference.

> --- 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

stderr is not a function, so @findex is not appropriate for it.  I'd
rather suggest this:

  @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.
> +@end defun

Thanks, this is good for the release branch.