bug#59325: The documentation of `map` is confusing

bug#59325: The documentation of `map` is confusing

[Jacob Hrbek]

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

The sentence '-- Scheme Procedure: map' is defined twice each with different inputs and explanation:

-- Scheme Procedure: map proc arg1 arg2 ...
-- Scheme Procedure: map-in-order proc arg1 arg2 ...
-- C Function: scm_map (proc, arg1, args)
Apply PROC to each element of the list ARG1 (if only two arguments
are given), or to the corresponding elements of the argument lists
(if more than two arguments are given). The result(s) of the
procedure applications are saved and returned in a list. For
‘map’, the order of procedure applications is not specified,
‘map-in-order’ applies the procedure from left to right to the list
elements.
...

-- Scheme Procedure: map f lst1 lst2 ...
Map the procedure over the list(s) LST1, LST2, ... and return a
list containing the results of the procedure applications. This
procedure is extended with respect to R5RS, because the argument
lists may have different lengths. The result list will have the
same length as the shortest argument lists. The order in which F
will be applied to the list element(s) is not specified.

Thus proposing:

- Take inspiration from racket[https://docs.racket-lang.org/guide/Lists__Iteration__and_Recursion.html] and add a sensible example code e.g:

(map sqrt '(1 4 9 16))
=> (1 2 3 4)

- Keep only one

-- Jacob "Kreyren" Hrbek

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