Re: When will emacs 27.1 be officially released?

[Richard Stallman <rms@gnu.org>]

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

  > For example, the imperative style is IMO inappropriate for the manual
  > (think about reading the book), while the indicative style of the
  > manual wastes precious screen space if we'd use it in doc strings.

That is one of many big differences.  Manual text and doc string text
are different at every level.  Everyone, please read the node Doc
Strings and Manuals in the GNU Coding Standards before posting about
this topic.

Each doc string is meant to be read by itself, so it must explain
the necessary background that we cannot assume the user knows.

By contrast, the manual consists of sections, each of which usually
describes several functions.  When writing the descriptions of those
functions, we avoid duplication.  Often the section states some background
outside the definitions of individual functions.

In this section, the function definitions don't say that TABLE is a
hash table.  They don't need to.  The title and introduction show
that.

BTW, do you see the style error in the definition of gethash?


8.2 Hash Table Access
=====================

This section describes the functions for accessing and storing
associations in a hash table.  In general, any Lisp object can be used
as a hash key, unless the comparison method imposes limits.  Any Lisp
object can also be used as the value.

 -- Function: gethash key table &optional default
     This function looks up KEY in TABLE, and returns its associated
     VALUE—or DEFAULT, if KEY has no association in TABLE.

 -- Function: puthash key value table
     This function enters an association for KEY in TABLE, with value
     VALUE.  If KEY already has an association in TABLE, VALUE replaces
     the old associated value.

 -- Function: remhash key table
     This function removes the association for KEY from TABLE, if there
     is one.  If KEY has no association, ‘remhash’ does nothing.

     Common Lisp note: In Common Lisp, ‘remhash’ returns non-‘nil’ if it
     actually removed an association and ‘nil’ otherwise.  In Emacs
     Lisp, ‘remhash’ always returns ‘nil’.

 -- Function: clrhash table
     This function removes all the associations from hash table TABLE,
     so that it becomes empty.  This is also called “clearing” the hash
     table.

     Common Lisp note: In Common Lisp, ‘clrhash’ returns the empty
     TABLE.  In Emacs Lisp, it returns ‘nil’.

 -- Function: maphash function table
     This function calls FUNCTION once for each of the associations in
     TABLE.  The function FUNCTION should accept two arguments—a KEY
     listed in TABLE, and its associated VALUE.  ‘maphash’ returns
     ‘nil’.



-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)