From: "Mattias Engdegård" <mattiase@acm.org>
To: Robert Pluim <rpluim@gmail.com>
Cc: emacs-devel@gnu.org
Subject: Re: master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598)
Date: Mon, 28 Sep 2020 11:59:43 +0200 [thread overview]
Message-ID: <9B45E488-F245-4A94-A492-C60B617A734B@acm.org> (raw)
In-Reply-To: <m24kni1bma.fsf@gmail.com>
28 sep. 2020 kl. 11.42 skrev Robert Pluim <rpluim@gmail.com>:
> Mattias> @defun string-replace fromstring tostring instring
> Mattias> -This function copies @var{instring} and replaces any occurrences of
> Mattias> -@var{fromstring} with @var{tostring}.
> Mattias> +This function returns a string equal to @var{instring} where any
> Mattias> +occurrences of @var{fromstring} have been replaced with
> Mattias> +@var{tostring}. It may return one of its arguments.
> Mattias> +Case is significant, and text properties are ignored.
> Mattias> @end defun
>
> 'equal'? Really? And itʼs kind of passive-voicey.
Thank you for scrutinising my changes!
For technical documentation, a declarative or functional style is often appropriate than a procedural one. We would prefer defining (+ A B) as the sum of A and B instead of saying that it takes A, then adds B, and finally returns the result.
> How about:
>
> This function replaces any occurences of @var{fromstring} with
> @var{tostring} in @var{instring} and returns the result.
That is probably fine. I wanted there to be no reason to misread it as a mutation of INSTRING, but the risk is probably minimal. I'll amend the text.
Thanks again!
next prev parent reply other threads:[~2020-09-28 9:59 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20200927124520.25321.62354@vcs0.savannah.gnu.org>
[not found] ` <20200927124522.BA20F207E0@vcs0.savannah.gnu.org>
2020-09-28 9:42 ` master 583cb26 2/3: Improve accuracy in string-replace description (bug#43598) Robert Pluim
2020-09-28 9:59 ` Mattias Engdegård [this message]
2020-09-28 11:09 ` Robert Pluim
[not found] ` <CAJnXXojjUAcRVmsZNWQ2j9rSDv76Y0od4yWfVg11k-Q2tf4NYA@mail.gmail.com>
2020-09-28 13:50 ` Robert Pluim
2020-09-28 16:36 ` John Yates
2020-09-28 16:49 ` Drew Adams
2020-09-28 16:55 ` Eli Zaretskii
2020-09-28 17:11 ` Drew Adams
2020-09-28 18:11 ` Eli Zaretskii
2020-09-28 22:36 ` John Yates
2020-09-28 22:47 ` Drew Adams
2020-09-29 2:35 ` Eli Zaretskii
2020-09-29 4:28 ` Drew Adams
2020-09-29 5:30 ` Eli Zaretskii
2020-09-29 15:28 ` Drew Adams
2020-09-29 2:37 ` Eli Zaretskii
2020-09-29 7:12 ` Robert Pluim
2020-09-29 14:26 ` Eli Zaretskii
2020-09-29 15:23 ` Robert Pluim
2020-09-29 16:02 ` Eli Zaretskii
2020-09-28 17:44 ` John Yates
2020-09-29 13:40 ` Lars Ingebrigtsen
2020-09-29 14:08 ` Mattias Engdegård
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=9B45E488-F245-4A94-A492-C60B617A734B@acm.org \
--to=mattiase@acm.org \
--cc=emacs-devel@gnu.org \
--cc=rpluim@gmail.com \
/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).