GNU bug report logs - #76135
passive voice in Emacs Lisp Reference Manual

Previous Next

Full log

View this message in rfc822 format

From: Richard Stallman <rms <at> gnu.org>
To: 76135 <at> debbugs.gnu.org
Subject: bug#76135: passive voice in Emacs Lisp Reference Manual
Date: Fri, 07 Feb 2025 18:09:15 -0500

[[[ 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)

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.