None
closed
9
2014-03-02
2013-11-16
No

Seems to me that have something not good here:

the default value. default is optional and defaults to false.

The context is

http://maxima.sourceforge.net/docs/manual/en/maxima_5.html#IDX121

Function: assoc (key, list, default)
Function: assoc (key, list)

This function searches for the key in the left hand side of
the input list of the form [x,y,z,...] where each of the
list elements is an expression of a binary operand and 2
elements. For example x=1, 2^3, [a,b] etc. The key is
checked against the first operand. assoc returns the second
operand if the key is found. If the key is not found it either returns
the default value. default is optional and defaults to false..

## Discussion

• Rupert Swarbrick - 2013-11-16

Good point. And "operand" is wrong here (the author wanted operator, but I think the whole explanation could be clearer).

I've just written a revised version, which I think is much easier to understand and pushed it to HEAD. The text renders as

``` -- Function: assoc (<key>, <list>, <default>)
-- Function: assoc (<key>, <list>)

This function searches for <key> in the left hand side of the input
<list>.  The <list> argument should be a list, each of whose
elements is an expression with exactly two parts.  Most usually,
the elements of <list> are themselves lists, each with two
elements.

The 'assoc' function iterates along <list>, checking the first part
of each element for equality with <key>.  If an element is found
where the comparison is true, 'assoc' returns the second part of
that element.  If there is no such element in the list, 'assoc'
returns either 'false' or <default>, if given.

For example, in the expression 'assoc (y, [[x,1], [y,2], [z,3]])',
the 'assoc' function searches for 'x' in the left hand side of the
list '[[y,1],[x,2]]' and finds it at the second term, returning
'2'.  In 'assoc (z, [[x,1], [z,2], [z,3]])', the search stops at
the first term starting with 'z' and returns '2'.  In 'assoc(x,
[[y,1]])', there is no matching element, so 'assoc' returns
'false'.
```

No doubt it could be clearer yet, but I'm closing this bug as fixed for now. If you think my attempt is an absolute disaster, feel free to re-open the bug and suggest a better wording :-)

• Rupert Swarbrick - 2013-11-16
• status: open --> closed

• Robert Dodier - 2014-03-02

Well, since you asked for comments. I'll recommend the following, which I've tried to apply throughout the documentation. (I didn't write the existing description of assoc.)

• This function searches ... --> @code{assoc} searches ... (more concrete to use name)
• <list> argument should be ... --> <list> is ... ("should" is ambiguous)
• Most usually ... --> (nuke it, doesn't matter what people usually do)
• The @code{assoc} function iterates --> @code{assoc} returns @code{second{@var{e})} where @var{e} is the first element such that the @code{@var{key} = first(@var{e})}. If there is no such element, @code{assoc} returns @var{default}, if specified, otherwise it returns @code{false}. If there is more than one such element, @code{assoc} ignores all but the first. (rephrase in hope of greater precision)
• For example, ... --> (split examples into @example / @end example blocks, putting the descriptive text before each block)