literal newlines in @result{} strings

literal newlines in @result{} strings

[Thien-Thi Nguyen]

i'm currently looking at text.texi (as part of the required review
indicated in admin/FOR-RELEASE) and see two instances of a newline
literal in the @result{} string, both in examples, one for
`buffer-string' and one for `buffer-substring':

     @result{} "This is the contents of buffer foo
"

@result{} "he contents of buffer foo
"

for `thing-at-point' i see:

     @result{} "Gentlemen may cry ``Peace! Peace!,''\n"

which has the `\n' instead of a literal newline.  i'd like to change the
former two to resemble the latter.  any objections?  any reason to go in
the opposite direction?

thi

Re: literal newlines in @result{} strings

[Richard M. Stallman]

    which has the `\n' instead of a literal newline.  i'd like to change the
    former two to resemble the latter.  any objections?  any reason to go in
    the opposite direction?

I agree it is better to make it uniform.  Each alternative has an
advantage, so I am not sure which is best.  It would be bad to have a
long discussion about which, since the question isn't worth spending
so much time.

So I guess you can go ahead and change it.

Re: literal newlines in @result{} strings

[Juri Linkov]

> for `thing-at-point' i see:
>
>      @result{} "Gentlemen may cry ``Peace! Peace!,''\n"
>
> which has the `\n' instead of a literal newline.  i'd like to change the
> former two to resemble the latter.  any objections?  any reason to go in
> the opposite direction?

Neither of these functions returns `\n'.  And `\n' is not an
alternative for a literal newline.  For differences, please see
examples of newlines in the documentation of `print-escape-newlines'
in (info "(elisp)Output Variables").  It demonstrates that the
difference whether a function returns or prints a literal newline or
`\n' is preserved in the Emacs Lisp Reference Manual.

Since `thing-at-point' actually returns a literal newline instead of
`\n', it would be more correct to replace `\n' with a literal newline
in its example.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: literal newlines in @result{} strings

[Richard M. Stallman]

    Neither of these functions returns `\n'.  And `\n' is not an
    alternative for a literal newline.

I am not sure what distinction you're making.  `\n' is alternative
Lisp syntax for a literal newline.  Which one we use in writing a Lisp
string is arbitrary, except when we're talking about print functions
which use one or the other.

Re: literal newlines in @result{} strings

[Juri Linkov]

> I am not sure what distinction you're making.  `\n' is alternative
> Lisp syntax for a literal newline.  Which one we use in writing a Lisp
> string is arbitrary, except when we're talking about print functions
> which use one or the other.

I meant that these functions return only a literal newline, not `\n'.
It might be confusing for readers of the reference manual when they
will try out an example and see that its real output is different from
the documented output in regard to newlines.  They might start to
search for an (AFAIK, nonexistent) option that toggles a literal newline
or `\n' in return values, or even to fill a bug report.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: literal newlines in @result{} strings

[Thien-Thi Nguyen]

Juri Linkov <juri@jurta.org> writes:

> I meant that these functions return only a literal newline, not `\n'.
> It might be confusing for readers of the reference manual when they
> will try out an example and see that its real output is different from
> the documented output in regard to newlines.  They might start to
> search for an (AFAIK, nonexistent) option that toggles a literal newline
> or `\n' in return values, or even to fill a bug report.

to document a literal newline, we can 

  (a) include a literal newline between double quotes
  (b) include a representation of such, between double quotes
  (c) use a literal newline after @print{}, for output

(c) is not applicable for the three functions under discussion, so i
explain my rationale for choosing (b) or (a) in this case (similar
thinking might be useful generally, but i haven't thought about it
generally).

some observations: the strings in question share some characteristics:
are result values, short, end with a newline (and only one).  `\n' as a
representation for literal newline is used not just for documentation
but also in emacs lisp strings (see node "Character Type").  this is a
programmer's manual for which the audience tends to be less easily
confused by seeing such a representation (although programmers can
become confused over anything, with enough concentration, it is often
true :-).

here are some cases where i think (a) would be more indicated than (b):
if there is more than one newline in the result, if the newline is not
at the end of the string.

thi

Re: literal newlines in @result{} strings

[Richard M. Stallman]

    I meant that these functions return only a literal newline, not `\n'.

They return strings which contain newlines.  You can write a newline
in a string either with a newline, or with `\n'.  So it is meaningless
to argue about which one they return.

Re: literal newlines in @result{} strings

[Juri Linkov]

> They return strings which contain newlines.  You can write a newline
> in a string either with a newline, or with `\n'.  So it is meaningless
> to argue about which one they return.

What I mean is that printed representation of the result of evaluation
(which is displayed in the echo area, or inserted into the buffer) contains
a literal newline instead of `\n'.  So after evaluating examples from
the manual users will see different results when examples of output
contain `\n' in the manual, and the real displayed output contains
literal newlines.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: literal newlines in @result{} strings

[Richard M. Stallman]

    What I mean is that printed representation of the result of evaluation
    (which is displayed in the echo area, or inserted into the buffer) contains
    a literal newline instead of `\n'.  So after evaluating examples from
    the manual users will see different results when examples of output
    contain `\n' in the manual, and the real displayed output contains
    literal newlines.

That is plausible.

However, I asked people NOT to have a discussion of this,
because it is not important enough to be worth the time.
I made a decision in my first message on the subject.
Can we please stop this discussion?