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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 76135 in the body.
You can then email your comments to 76135 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: bug-gnu-emacs <at> gnu.org
Subject: 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)

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)

Message #11 received at 76135 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 76135 <at> debbugs.gnu.org
Subject: Re: bug#76135: passive voice in Emacs Lisp Reference Manual
Date: Sat, 08 Feb 2025 13:32:43 +0200

> 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.

Message #16 received at 76135 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76135 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#76135: passive voice in Emacs Lisp Reference Manual
Date: Mon, 10 Feb 2025 23:11:53 -0800

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?

Message #21 received at 76135-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: rms <at> gnu.org, 76135-done <at> debbugs.gnu.org
Subject: Re: bug#76135: passive voice in Emacs Lisp Reference Manual
Date: Tue, 11 Feb 2025 15:10:39 +0200

> 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 #24 received at 76135 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 76135 <at> debbugs.gnu.org
Subject: Re: bug#76135: passive voice in Emacs Lisp Reference Manual
Date: Wed, 12 Feb 2025 05:38: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. ]]]

  > > 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 know what that is like.

Let's ask everyone to look for these when they read code or Info, and
report or fix them.

-- 
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.