Subject: Re: bug#72212: 31.0.50; API for condition objects

From: Stefan Monnier <[email-masked]>
Date: Sat, 02 Nov 2024 15:37:59 -0400

>>> Beside whether we want to do this or not, there is another question
>>> about naming: currently we use "condition" in some places (e.g. in
>>> `condition-case`) but we use "error" in others (e.g. `define-error` and
>>> `error-message-string`).
> I think we should keep the word "condition", and think we could have
> aliases "define-condition" and "condition-message-string" like you
> propose.

>From the code's point of view, this works OK, except I noticed that it
conflicts with the notion of "condition" used in the threading code (as
in `condition-wait`, `condition-variable-p`, ...), but on the manual
side it's quite a different story, because there we "systematically" use
the term "error", e.g.:

    @node Errors
    @subsection Errors
    @cindex errors
    
      When Emacs Lisp attempts to evaluate a form that, for some reason,
    cannot be evaluated, it @dfn{signals} an @dfn{error}.
    
      When an error is signaled, Emacs's default reaction is to print an
    error message and terminate execution of the current command.  This is
    the right thing to do in most cases, such as if you type @kbd{C-f} at
    the end of the buffer.
    
      In complicated programs, simple termination may not be what you want.
    For example, the program may have made temporary changes in data
    structures, or created temporary buffers that should be deleted before
    the program is finished.  In such cases, you would use
    @code{unwind-protect} to establish @dfn{cleanup expressions} to be
    evaluated in case of error.  (@xref{Cleanups}.)  Occasionally, you may
    wish the program to continue execution despite an error in a subroutine.
    In these cases, you would use @code{condition-case} to establish
    @dfn{error handlers} to recover control in case of error.
    
      For reporting problems without terminating the execution of the
    current command, consider issuing a warning instead.  @xref{Warnings}.
    
      Resist the temptation to use error handling to transfer control from
    one part of the program to another; use @code{catch} and @code{throw}
    instead.  @xref{Catch and Throw}.
    
    @menu
    * Signaling Errors::      How to report an error.
    * Processing of Errors::  What Emacs does when you report an error.
    * Handling Errors::       How you can trap errors and continue execution.
    * Error Symbols::         How errors are classified for trapping them.
    @end menu

Here are options, I can see:

- Change the manual's text to use "condition" instead of "error" pretty
  much everywhere.
- Use a naming based on `error` instead of `condition` (optionally with
  `error-case(-unless-debug)` as aliases for `condition-case`?).
- Keep a mix, where we add to the manual a paragraph explaining that
  `signal` really causes a "condition" but that most conditions (tho not
  all, `quit` being the main(sole?) exception) are subtypes of the
  `error` condition so we usually refer to conditions as "errors".

I'm leaning towards the third option, because I think straightening out
the mix of "conditions" and "errors" we have is fairly difficult.

        Stefan