Package: emacs;
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.
Message #8 received at 76135 <at> debbugs.gnu.org (full text, mbox):
From: Christopher Dimech <dimech <at> gmx.com> To: rms <at> gnu.org Cc: 76135 <at> debbugs.gnu.org Subject: Re: bug#76135: passive voice in Emacs Lisp Reference Manual Date: Sat, 8 Feb 2025 00:27:53 +0100
> Sent: Saturday, February 08, 2025 at 11:09 AM
> From: "Richard Stallman" <rms <at> gnu.org>
> To: 76135 <at> debbugs.gnu.org
> Subject: bug#76135: passive voice in Emacs Lisp Reference Manual
>
> [[[ 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.
Active voice is clearer.
> 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.
There has been a tendency for people to do more prose. Have got into
some discussions with Leslie Lamport, who worked on formal correctness
about writing mathematical proofs.
One quickly discovers that the approach based on excessive prose collapses
under the weight of the complexity of any nontrivial proof. One becomes
lost in a maze of details, and can't keep track of what had and had not
been proved at any point.
> --
> 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)
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.