GNU bug report logs -
#76135
passive voice in Emacs Lisp Reference Manual
Previous Next
Reported by: rms <at> gnu.org
Date: Fri, 7 Feb 2025 23:10:02 UTC
Severity: wishlist
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Full log
View this message in rfc822 format
[Message part 1 (text/plain, inline)]
Your bug report
#76135: passive voice in Emacs Lisp Reference Manual
which was filed against the emacs package, has been closed.
The explanation is attached below, along with your original report.
If you require more details, please reply to 76135 <at> debbugs.gnu.org.
--
76135: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=76135
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems
[Message part 2 (message/rfc822, inline)]
> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Mon, 10 Feb 2025 23:11:53 -0800
> Cc: rms <at> gnu.org, 76135 <at> debbugs.gnu.org
>
> Eli Zaretskii <eliz <at> gnu.org> writes:
>
> >> From: Richard Stallman <rms <at> gnu.org>
> >> Date: Fri, 07 Feb 2025 18:09:15 -0500
> >>
> >> It seems that people have a tendency to reqrite text into passive voice,
> >> which is gradually making the manual a little harder to read.
> >
> > We try to find these cases during patch review and flag them, but it's
> > an uphill battle that never ends.
>
> I think we fixed the issues that were indicated here.
>
> Can this bug be closed?
Yes, done.
[Message part 3 (message/rfc822, inline)]
[[[ To any NSA and FBI agents reading my email: please consider ]]]
[[[ whether defending the US Constitution against all enemies, ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]
I just lookd atthe definition of `defvar' in the Emacs Lisp Reference
Manual and saw that many sentences use the passve voice.
Here in the first paragraph are two instanes:
This special form defines SYMBOL as a variable. Note that SYMBOL
is not evaluated; the symbol to be defined should appear explicitly
in the ‘defvar’ form. The variable is marked as “special”,
Replacing them with active voice makes the text clearer in several
ways.
This special form defines SYMBOL as a variable. It does ot
evaluate SYMBOL--the symbol to be defined should appear explicitly
in the ‘defvar’ form. `defvar' also marks SYMBOL as “special”
Here is a third instance, in an infinitive in the same paragraph:
, meaning that it should always be dynamically bound (*note Variable
Scoping::).
should be
so that every binding of the variable SYMBOL will be dynamic,
not lexical (*note Variable Scoping::)
It has been customary for manuals to use the passive voice, perhaps
following a custom in scientific writing. Maybe people working on the
manual have followed that practice, but it doesn't make for readable
writing. But I had learned in the 1980s that active voice is clearer.
We don't want our manuals to read like scientific papers.
I am pretty sure I rewrote the Emacs Lisp Reference Manual early on
to use the active voice by default, and wrote this text
in the GNU Coding Standards:
Whenever possible, please stick to the active voice, avoiding the
passive, and use the present tense, not the future tense. For
instance, write ``The function @code{foo} returns a list containing
@var{a} and @var{b}'' rather than ``A list containing @var{a} and
@var{b} will be returned.'' One advantage of the active voice is it
requires you to state the subject of the sentence; with the passive
voice, you might omit the subject, which leads to vagueness.
So I looked at revsion 6336d8c3d7812815d083de055229ebb840fe6159 in
2007. In that version, this text had one active voice:
This special form defines @var{symbol} as a variable and can also
initialize and document it. The definition informs a person reading
your code that @var{symbol} is used as a variable that might be set or
changed. Note that @var{symbol} is not evaluated; the symbol to be
defined must appear explicitly in the @code{defvar}.
The last sentence there was passive already, but I have a hunch
hat in 1996 (before we used git) it was active too.
The next paragraph in the file, in the current version.
If @var{value} is specified, and @var{symbol} is void (i.e., it has no
dynamically bound value; @pxref{Void Variables}), then @var{value} is
evaluated and @var{symbol} is set to the result. But if @var{symbol}
is not void, @var{value} is not evaluated, and @var{symbol}'s value is
left unchanged. If @var{value} is omitted, the value of @var{symbol}
is not changed in any case.
is also very passive. The 2007 version
If @var{symbol} is void and @var{value} is specified, @code{defvar}
evaluates it and sets @var{symbol} to the result. But if @var{symbol}
already has a value (i.e., it is not void), @var{value} is not even
evaluated, and @var{symbol}'s value remains unchanged. If @var{value}
is omitted, the value of @var{symbol} is not changed in any case.
Has active voice in a couple of places.
We could make it better than that, like this:
If @var{symbol} is void and you specify @var{value}, @code{defvar}
evaluates it and sets @var{symbol} to the result. But if @var{symbol}
already has a value (i.e., it is not void), @code{defvar} does not
change its value. and it does not even evaluate @var{value}.
If you omit @var{value}, @code{defvar} does not change the value.
It seems that people have a tendency to reqrite text into passive voice,
which is gradually making the manual a little harder to read.
--
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
This bug report was last modified 160 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.