classification
Title: Tweak sorting howto to eliminate redundancy
Type: Stage: commit review
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, eric.araujo, georg.brandl, rhettinger
Priority: normal Keywords: patch

Created on 2011-01-12 10:29 by eric.araujo, last changed 2011-02-06 06:16 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
minor-sorting-changes.diff eric.araujo, 2011-01-12 10:29
Messages (4)
msg126083 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-01-12 10:29
When reading over the sorting howto, I noticed redundancy of the form “the list.sort() method of a list”.  Raymond, if you approve the attached patch, please assign back to me.  There were no warnings during doc build and no link was broken.

Note that :meth:`list.sort` (or :meth:`~list.sort`) does not trigger a link to the doc of the method, since sort is not marked up with a method directive but listed in a table alongside other list and bytearray methods (http://docs.python.org/dev/library/stdtypes#typesseq-mutable).  This table is preceded by index-generating markup, but it does not create a target for :meth:`list.sort`; that’s a separate issue.  Until it’s solved, the sorting howto could turn the first occurrence of “list” into a link to the right section, using :ref:`typesseq-mutable <list>`, or continue to live without a link to list or list.sort.
msg127589 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-01-31 10:14
You can put in the backslashes before the two periods, but not the other changes.  I want the method names to continue to be spelled-out in full so that it is more clear what they are referring to.  Even in spoken English, I typically say "list sort" or "sort method of the builtin list type".  This helps distinguish it from the sorted() builtin.
msg127902 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-02-04 16:28
I do think that "list.sort() method of a list" is a bit too much.
msg128043 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-02-06 06:16
Made some tweaks r88358.  Sorry, I'm leaving the list.sort references as-is.  I consider them to be important in a document that needs to clearly differentiate list.sort from __builtin__.sorted().
History
Date User Action Args
2011-02-06 06:16:44rhettingersetstatus: open -> closed
nosy: georg.brandl, rhettinger, eric.araujo, docs@python
messages: + msg128043

assignee: eric.araujo -> rhettinger
resolution: fixed
2011-02-04 16:28:27georg.brandlsetnosy: + georg.brandl
messages: + msg127902
2011-01-31 10:14:45rhettingersetassignee: rhettinger -> eric.araujo
messages: + msg127589
2011-01-12 10:29:44eric.araujocreate