Re: Better documentation for non-binding clauses of if-let and friends

[Alfred M. Szmidt]

   I rather agree with Joost on that other thread regarding the
   usefulness of the FOO-let macros and their condition-only,
   non-binding clauses.

I don't think anyone is arguing about their usefulness, only that the
macros are too smart for their own good.

   > There is no mention of this in the manual, that only says that SPEC is
   > like the one in LET*.

   But I agree with you that the manual is incomplete or even
   wrong here.

   How about the following in section "Conditionals" instead
   of what there currently is about these:

     There's a number of variations on this theme, and they're briefly
     described below.

     For all of these SPEC is similar to what let* offers, with a few
     extensions useful in the context of testing conditions: As with
     let*, an element of SPEC which is a list (SYMBOL VALUEFORM) binds
     SYMBOL to the value of VALUEFORM.  An element can additionally be
     of the form (VALUEFORM), which is evaluated and checked for nil;
     i.e. SYMBOL can be omitted if only the test result is of
     interest.  It can also be of the form SYMBOL, then the binding of
     SYMBOL is checked for nil.


     For all of these SPEC is similar to what let* offers, with a few
     extensions useful in the context of testing conditions:

That sentence doesn't add much, and will make the user guess if there
are other useful extentions -- "with the following extension" would
suffice I think.

     As with
     let*, an element of SPEC which is a list (SYMBOL VALUEFORM) binds
     SYMBOL to the value of VALUEFORM.  An element can additionally be
     of the form (VALUEFORM), 
     which is evaluated and checked for nil;
     i.e. SYMBOL can be omitted if only the test result is of
     interest.  It can also be of the form SYMBOL, then the binding of
     SYMBOL is checked for nil.


      -- Macro: if-let spec then-form else-forms...
          Evaluate each binding in SPEC in turn, stopping if a binding
          value or value form is ‘nil’.  If all are non-‘nil’, return
          the value of THEN-FORM, otherwise the last form in
          ELSE-FORMS.

The description here should explicitly mention that SPEC is _NOT_ a
binding if the spec only contains the VALUEFORM.  And so should all
other descriptions.

      -- ...

   If needed, I can provide that or something similar as a patch ...