* literal newlines in @result{} strings
@ 2005-08-29 23:33 Thien-Thi Nguyen
2005-08-30 10:30 ` Richard M. Stallman
2005-08-30 15:32 ` Juri Linkov
0 siblings, 2 replies; 9+ messages in thread
From: Thien-Thi Nguyen @ 2005-08-29 23:33 UTC (permalink / raw
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literal newlines in @result{} strings
2005-08-29 23:33 literal newlines in @result{} strings Thien-Thi Nguyen
@ 2005-08-30 10:30 ` Richard M. Stallman
2005-08-30 15:32 ` Juri Linkov
1 sibling, 0 replies; 9+ messages in thread
From: Richard M. Stallman @ 2005-08-30 10:30 UTC (permalink / raw
Cc: emacs-devel
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literal newlines in @result{} strings
2005-08-29 23:33 literal newlines in @result{} strings Thien-Thi Nguyen
2005-08-30 10:30 ` Richard M. Stallman
@ 2005-08-30 15:32 ` Juri Linkov
2005-08-31 14:35 ` Richard M. Stallman
1 sibling, 1 reply; 9+ messages in thread
From: Juri Linkov @ 2005-08-30 15:32 UTC (permalink / raw
Cc: emacs-devel
> 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/
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literal newlines in @result{} strings
2005-08-30 15:32 ` Juri Linkov
@ 2005-08-31 14:35 ` Richard M. Stallman
2005-08-31 16:27 ` Juri Linkov
0 siblings, 1 reply; 9+ messages in thread
From: Richard M. Stallman @ 2005-08-31 14:35 UTC (permalink / raw
Cc: ttn, emacs-devel
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literal newlines in @result{} strings
2005-08-31 14:35 ` Richard M. Stallman
@ 2005-08-31 16:27 ` Juri Linkov
2005-09-01 7:11 ` Thien-Thi Nguyen
2005-09-01 15:52 ` Richard M. Stallman
0 siblings, 2 replies; 9+ messages in thread
From: Juri Linkov @ 2005-08-31 16:27 UTC (permalink / raw
Cc: ttn, emacs-devel
> 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/
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literal newlines in @result{} strings
2005-08-31 16:27 ` Juri Linkov
@ 2005-09-01 7:11 ` Thien-Thi Nguyen
2005-09-01 15:52 ` Richard M. Stallman
1 sibling, 0 replies; 9+ messages in thread
From: Thien-Thi Nguyen @ 2005-09-01 7:11 UTC (permalink / raw
Cc: rms, emacs-devel
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literal newlines in @result{} strings
2005-08-31 16:27 ` Juri Linkov
2005-09-01 7:11 ` Thien-Thi Nguyen
@ 2005-09-01 15:52 ` Richard M. Stallman
2005-09-01 19:32 ` Juri Linkov
1 sibling, 1 reply; 9+ messages in thread
From: Richard M. Stallman @ 2005-09-01 15:52 UTC (permalink / raw
Cc: ttn, emacs-devel
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literal newlines in @result{} strings
2005-09-01 15:52 ` Richard M. Stallman
@ 2005-09-01 19:32 ` Juri Linkov
2005-09-03 1:42 ` Richard M. Stallman
0 siblings, 1 reply; 9+ messages in thread
From: Juri Linkov @ 2005-09-01 19:32 UTC (permalink / raw
Cc: ttn, emacs-devel
> 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/
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: literal newlines in @result{} strings
2005-09-01 19:32 ` Juri Linkov
@ 2005-09-03 1:42 ` Richard M. Stallman
0 siblings, 0 replies; 9+ messages in thread
From: Richard M. Stallman @ 2005-09-03 1:42 UTC (permalink / raw
Cc: ttn, emacs-devel
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?
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2005-09-03 1:42 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2005-08-29 23:33 literal newlines in @result{} strings Thien-Thi Nguyen
2005-08-30 10:30 ` Richard M. Stallman
2005-08-30 15:32 ` Juri Linkov
2005-08-31 14:35 ` Richard M. Stallman
2005-08-31 16:27 ` Juri Linkov
2005-09-01 7:11 ` Thien-Thi Nguyen
2005-09-01 15:52 ` Richard M. Stallman
2005-09-01 19:32 ` Juri Linkov
2005-09-03 1:42 ` Richard M. Stallman
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).