[ python-Bugs-1511911 ] vague xref in description of sorted() builtin

[SourceForge.net]

Bugs item #1511911, was opened at 2006-06-24 16:12
Message generated for change (Comment added) made by akuchling
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1511911&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: None
>Status: Closed
>Resolution: Fixed
Priority: 5
Submitted By: rurpy (rurpy)
>Assigned to: A.M. Kuchling (akuchling)
Summary: vague xref in description of sorted() builtin

Initial Comment:
In section 2.1, "Builtin Functions", in the 
description of function sorted(), it says:

The optional arguments cmp, key, and reverse have the 
same meaning as those for the list.sort() method. 

For someone not already very familiar with the 
organiztion of the Library Reference, a reference to 
list.sort() is not very useful.  If one looks in the 
index one sees "List Object" and "List, operations 
on".  Although the latter link does bring one to the 
right page (2.3.6.4 "Mutable Sequence Types") it is 
not obvious to those not yet used to the loose use of 
terms in the Puython docs, that "operation" 
and "method" are synonymous.  And God help the poor 
newbie who forgets the index and tries to find the 
relevent page using the ToC.

I suggest:
1) In sec. 2.1, explicity describe sorted()'s 
arguments rather than referencing list.sort().  Cut 
and paste from list.sort.  Mention (as a helpful "see 
also") the existence of the list.sort() method with a 
link.

If that is not acceptable than, 

2a) In sec 2.1, change word "method" to "operation", or
2b) In the index under "List", add a link "methods" 
pointing to section 2.1, (i.e. same target as the 
currently existing "operations" entry under List.
And, 
3) In sec 2.1 make the text "List.sorted()" a link to
to the List.sorted() page (2.3.6.4 "Mutable Sequence 
Types")

----------------------------------------------------------------------

>Comment By: A.M. Kuchling (akuchling)
Date: 2006-07-03 10:19

Message:
Logged In: YES 
user_id=11375

Thanks for your comment!

In rev. 47220, I've copied the description of cmp, reverse,
and key, and also improved the xref to give the actual
section number.  Rev. 47222 applies the change to the 2.4
maintenance branch.


----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1511911&group_id=5470