From: Thien-Thi Nguyen <ttn@gnu.org>
Cc: rms@gnu.org, emacs-devel@gnu.org
Subject: Re: literal newlines in @result{} strings
Date: 01 Sep 2005 03:11:56 -0400 [thread overview]
Message-ID: <jkr7c945z7.fsf@glug.org> (raw)
In-Reply-To: <874q96yvcw.fsf@jurta.org>
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
next prev parent reply other threads:[~2005-09-01 7:11 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
2005-09-01 15:52 ` Richard M. Stallman
2005-09-01 19:32 ` Juri Linkov
2005-09-03 1:42 ` Richard M. Stallman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=jkr7c945z7.fsf@glug.org \
--to=ttn@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=rms@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).