bug#26564: Document that only functions and not variables can end with "-p"

[Drew Adams <drew.adams@oracle.com>]

> The discussion on whether variables should end in "-p" came up few time on emacs-devel, at least the ones I was part of:
> 
> 1. https://lists.gnu.org/archive/html/emacs-devel/2016-07/msg00734.html
> 2. http://lists.gnu.org/archive/html/emacs-devel/2017-04/msg00540.html
> 
> Doing a rudimentary search in emacs/lisp/ code-base shows a sign of an undocumented convention that predicate functions, functions that return either nil or non-nil can end in "-p" (if the function name is multi-word, like nested-alist-p), or just "p" (if the function name is a single word, like stringp).
> 
> I ran ag[1] in emacs/lisp:
> 
> 1. 1511 matches -- defuns and defsubsts ending in -p -- ag 'def(un|subst)\s+[^ ]+-p\s+' --stats
> 2. 149 matches -- defvars, defconsts and defcustoms ending in -p -- ag 'def(var|const|custom)\s+[^ ]+-p\s+' --stats  
> 3. 65 matches -- Just the user-facing defcustoms -- ag 'defcustom\s+[^ ]+-p\s+' --stats
> 
> That corroborates that more functions tend to end in "-p" than variables.

A better measure would be # of `-p' vs number of NON-`-p',
for both functions and variables.  But I'm sure that the
same result holds: far more `-p' functions than `-p' vars.

Stefan, at least, has actively discouraged the use of vars
with `-p' names, in emacs-devel.  That could partly explain
the numbers.  Also, there is nothing in the Elisp manual
coding conventions about `-p' for var names, so users
wouldn't get the idea to do that from the manual.  That too
could partly explain the numbers.

> This bug report is to make a request to incorporate this unspoken rule as a rule in the Elisp manual.
> 
> What would be the correct section to do so?
>
> [1]: https://github.com/ggreer/the_silver_searcher

FWIW, I disagree with a guideline to not name Boolean vars
using `-p'.

1. Variables and functions are already in separate spaces -
they can be examined/found separately (`boundp' vs `fboundp').  

What do you hope to gain by outlawing/discouraging `-p' for 
Boolean variable names?  It cannot be to avoid confusing a
variable and a function, since the those kinds of animal are
already separate in Emacs Lisp.

2. A variable is, abstractly (e.g., in a formal abstract
data type), a nullary function.  It makes just as much
sense to name a Boolean variable using `*-p' as it does
to name a Boolean function using that convention.

Just one opinion.  Stefan disagrees, for instance (but
with no reasons given).

3. Is there a proposal for a _different_ naming convention
for Boolean variables?  I'd argue that we should have some
such a naming convention.  And I'd argue that it should be
different for options and non-option variables.

I use `-flag' for Boolean options and `-p' for Boolean
non-option variables.  (I did  not come up with the `-flag'
convention, BTW.  Someone else did, long ago.  I thought it
was a GNU Emacs convention, (maybe it was?) so I stuck to it.
Stefan is not a fan of `-flag' (or any naming convention for
vars).

4. There should be some easy way to ask for help on Boolean
variables.  Better yet would be a way to ask for help on
a user option, filtering by defcustom type.

FWIW, I have code that does that.  It provides help commands
that let you show the help for things based on different 
criteria, and for options that includes the custom type.

You can match the type in different ways, depending on the
prefix argument:

 - None:      OPTION is defined with TYPE or a subtype of TYPE.
              TYPE is a regexp.

 - `C-u':     OPTION is defined with TYPE or a subtype of TYPE,
                or its current value is compatible with TYPE.
              TYPE is a type definition or its first symbol.

 - Negative:  OPTION is defined with TYPE (exact match).
              TYPE is a regexp.

 - Positive:  OPTION is defined with TYPE,
                or its current value is compatible with TYPE.
              TYPE is a type definition or its first symbol.

 - Zero:      OPTION is defined with TYPE or a subtype of TYPE.
              TYPE is a type definition or its first symbol.

 - `C-u C-u': OPTION is defined with TYPE (exact match).
              TYPE is a type definition or its first symbol.

_Without_ such a capability, it should be possible, at a
minimum, to get only Boolean options, using a name-pattern
match.

Again, just one opinion.