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

From: Drew Adams <[email-masked]>
Date: Mon, 29 Jan 2018 06:47:10 -0800 (PST)

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