Re: literal newlines in @result{} strings

[Thien-Thi Nguyen]

Juri Linkov <address@hidden> 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