gnustandards standards.texi

[Richard M. Stallman]

CVSROOT:        /sources/gnustandards
Module name:    gnustandards
Changes by:     Richard M. Stallman <rms>       15/12/24 03:50:09

Modified files:
        .              : standards.texi 

Log message:
        Avoid passive voice in documentation when possible.
        When to use future tense.
        
        Explain what a function's comment should say.
        
        Don't refer to pages that can't be viewed without running nonfree JS 
code.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnustandards/standards.texi?cvsroot=gnustandards&r1=1.242&r2=1.243

Patches:
Index: standards.texi
===================================================================
RCS file: /sources/gnustandards/gnustandards/standards.texi,v
retrieving revision 1.242
retrieving revision 1.243
diff -u -b -r1.242 -r1.243
--- standards.texi      23 Apr 2015 15:48:55 -0000      1.242
+++ standards.texi      24 Dec 2015 03:50:07 -0000      1.243
@@ -3,7 +3,7 @@
 @setfilename standards.info
 @settitle GNU Coding Standards
 @c This date is automagically updated when you save this file:
address@hidden lastupdate April 23, 2015
address@hidden lastupdate December 23, 2015
 @c %**end of header
 
 @dircategory GNU organization
@@ -3409,6 +3409,18 @@
 it is a function.  @code{foo ()} is not a function, it is a function
 call with no arguments.
 
+Whenever possible, please stick to the active voice, avoiding the
+passive, and use the present tense, not the future teste.  For
+instance, write ``The function @code{foo} returns a list containing
address@hidden and @var{b}'' rather than ``A list containing @var{a} and
address@hidden 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.
+
+It is proper to use the future tense when grammar demands it, as in,
+``If you type @kbd{x}, the computer will self-destruct in 10
+seconds.''
+
 @node Doc Strings and Manuals
 @section Doc Strings and Manuals
 
@@ -3582,7 +3594,7 @@
 where people will see it whenever they see the code.  For example,
 ``New function'' is enough for the change log when you add a function,
 because there should be a comment before the function definition to
-explain what it does.
+explain what it does, how to call it, and so on.
 
 For changes to files that do not support a comment syntax (e.g., media
 files), it is ok to include the full explanation in the change log file,
@@ -4269,11 +4281,22 @@
 
 Thus, for example, you should not refer to AT&T's web site if that
 recommends AT&T's non-free software packages; you should not refer to
-a site that links to AT&T's site presenting it as a place to get some
-non-free program, because that link recommends and legitimizes the
-non-free program.  However, that a site contains a link to AT&T's web
-site for some other purpose (such as long-distance telephone service)
-is not an objection against it.
+a page P that links to AT&T's site presenting it as a place to get
+some non-free program, because that part of the page P itself
+recommends and legitimizes the non-free program.  However, that P
+contains a link to AT&T's web site for some other purpose (such as
+long-distance telephone service) is not an objection against it.
+
+There are web sites which depend on nonfree Javascript code even to
+<em>see</em> the contents of the pages.  Any site hosted on wix.com
+has this problem, and so do some other sites.  Referring people to
+such pages to read their contents is, in effect, urging them to run
+those nonfree programs---so please don't refer to those pages.  (Such
+pages also break the Web, so they deserve condemnation for two
+reasons.)
+
+Instead, please quote excerpts from the page to make your point,
+or find another place to refer to that information.
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License