bug#15558: [gnu.org #859332] Error in elisp on line documentation

bug#15558: [gnu.org #859332] Error in elisp on line documentation

[Robert Musial via RT]

Emacs team:

Below is another documentation improvement suggestion.

Thanks!


> [ke1g.nh@gmail.com - Thu Sep 26 12:06:21 2013]:
> 
> (Please forward to the appropriate document maintainer.)
> 
> I believe that I have found  an error in the description of cond at:
> 
> 
> http://www.gnu.org/software/emacs/manual/html_node/elisp/Conditionals.html
> 
> The description implies that the "condition" element of a clause is not
> included in "body-forms".  This is a reasonable separation, since (if the
> clause is reached) the condition is evaluated while the body-forms may or
> may not be (depending upon the condition's value).
> 
> But it goes on to say that the value (of the cond) is that of the last of
> the body-forms to be evaluated.  Yet it is perfectly legal for a clause to
> have no body-forms, only a condition.  In this case, if the condition is
> non-nil, that is, if the clause succeeds, the value of the cond will
be the
> value of the condition.  This is the last form evaluated, not the last of
> the body-forms evaluated (since none of the body-forms were evaluated).
> 
> You can confirm this behavior by evaluating the following (the result will
> be 3):
> 
> > (cond (3)(1 4))
> 
> The current text actually leaves the value undefined for this case.  It is
> a useful case, and should be correctly documented.
> 
> Perhaps something  like:
> 
> > ...and the value of the last of body-forms, or, if there are no
> body-forms in the clause, the value of the condition, becomes the value of
> the cond.
> 
> Bill (formerly f@ai. "Hi" to RMS if he's about)
> 
> 
-- 
Robert Musial - musial at gnu dot org - GPG key 533A1341
Join the FSF! http://www.fsf.org/register_form?referrer=9143

bug#15558: [gnu.org #859332] Error in elisp on line documentation

[Glenn Morris]

"Robert Musial via RT" wrote:

>> Yet it is perfectly legal for a clause to have no body-forms, only a
>> condition.
[...]
>> The current text actually leaves the value undefined for this case.  It is
>> a useful case, and should be correctly documented.

It is documented (if a little clunkily):

    A clause may also look like this:

    (condition)

    Then, if condition is non-nil when tested, the value of condition
    becomes the value of the cond form. 


PS: Please report Emacs documentation issues via M-x report-emacs-bug
(or mail to bug-gnu-emacs@gnu.org) rather than emailing GNU webmasters.

bug#15558: [gnu.org #859332] Error in elisp on line documentation

[Bill Freeman]

[-- Attachment #1: Type: text/plain, Size: 1049 bytes --]

Yes, thanks, I see that now.  (And I thought I was reading carefully.)

But might I suggest that the line:

    If every condition evaluates to nil, so that every clause fails,
condreturns
nil.
be placed after the line:

    Then, if condition is non-nil when tested, the value of
conditionbecomes the value of the
cond form.

Bill


On Tue, Oct 8, 2013 at 12:17 PM, Glenn Morris <rgm@gnu.org> wrote:

>
> "Robert Musial via RT" wrote:
>
> >> Yet it is perfectly legal for a clause to have no body-forms, only a
> >> condition.
> [...]
> >> The current text actually leaves the value undefined for this case.  It
> is
> >> a useful case, and should be correctly documented.
>
> It is documented (if a little clunkily):
>
>     A clause may also look like this:
>
>     (condition)
>
>     Then, if condition is non-nil when tested, the value of condition
>     becomes the value of the cond form.
>
>
> PS: Please report Emacs documentation issues via M-x report-emacs-bug
> (or mail to bug-gnu-emacs@gnu.org) rather than emailing GNU webmasters.
>

[-- Attachment #2: Type: text/html, Size: 1688 bytes --]

bug#15558: [gnu.org #859332] Error in elisp on line documentation

[Glenn Morris]

(Please keep the debbugs address included in any replies.)

Bill Freeman wrote:

> But might I suggest that the line:
>
>     If every condition evaluates to nil, so that every clause fails,
> condreturns
> nil.
> be placed after the line:
>
>     Then, if condition is non-nil when tested, the value of
> conditionbecomes the value of the
> cond form.

OK, done in the Emacs sources. The online version will be regenerated at
time of next Emacs release.