Steven Bethard wrote:
> Skip Montanaro wrote:
>
>> Mike> Given that Python hides the difference between user-defined
>> Mike> objects and built-in objects, it's not clear to me that anything
>> Mike> other than the current system, with all the classes/types in one
>> Mike> place, makes sense.
>>
>>Maybe the Module Index should be renamed "Module/Type Index" and embellished
>>with the builtin types, so that you'd find "float (builtin)", "string
>>(builtin)", "dict (builtin)", etc. in the appropriate alphabetical
>>positions.
>
>
> +1
>
> Yeah, I'd love to see something like this. My preference would actually
> to be to leave the "Global Module Index" the same and add a "Builtin
> Type Index" along the lines of the module index.
>
> One of my current problems with the documentation is that, for builtin
> types, the constructor is found in "Built-in Functions"[1], but the
> methods are found in some subsection of "Built-in Types"[2].
> Additionally, the "Built-in Types"[2] section mixes protocols like the
> Sequence, Iterator and Mapping protocols with the methods of some of the
> builtin types that implement these protocols.
The two manuals on my book shelf that are the most worn are Alex
Martelli's "Python in a Nutshell", (A 2.5 version would be really nice..
hint to Alex), and a C pocket reference. Both are organized by
*subject* and not by library/include.
What I would like to see is something like the following for each item:
0. reference @ sequence code
2. "Builtin" | "import <library>"
3. Type/class: Name/Syntax
4. Description with examples
6. Links to other references of this item in docs
7. Links to related functions or objects in same doc type
8. Keywords
In this way, each item can be a complete entry in a data base that can
be sorted in different ways. Alphabetical, by subject, by library, etc...
The quick reference guide description should mirror the doc strings.
Short but sweet if possible. Any changes to one should be made to the other.
An advanced technical language manual would also be nice for both those
who are interested, and to record implementing details. To start it
could just be any current technical details that do not fit well in the
other categories.
So summing up:
+ Each item/object in a database in a consistent way.
+ Four main categories: Tutor, Quick Ref, Full Ref, and Technical Ref.
+ Cross reference links in each item.
+ Dependency, ie... "from <library> import <name> listed with each item.
+ keywords enabling look up and searches by subject
As it's been pointed out several times, most of this is already there.
The hard part, and it may not be as hard as I think, is generating the
web pages from this in a nice way, and to create a good search interface
that can create a list of links by a chosen reference selection.
The rest of this is a matter of presentation and details. Which I think
can be worked out, and done to be very similar to the existing pages.
Example from Python Docs:
4.1.3 String functions
The following functions are available to operate on string and Unicode
objects. They are not available as string methods.
capwords( s)
Split the argument into words using split(), capitalize each word
using capitalize(), and join the capitalized words using join(). Note
that this replaces runs of whitespace characters by a single space, and
removes leading and trailing whitespace.
maketrans( from, to)
Return a translation table suitable for passing to translate() or
regex.compile(), that will map each character in from into the character
at the same position in to; from and to must have the same length.
Warning: Don't use strings derived from lowercase and uppercase as
arguments; in some locales, these don't have the same length. For case
conversions, always use lower() and upper().
Could become something like:
"""
Python Quick Ref: 4.1.3.1
import string
Function: capwords(s) -> string
Returns a copy of string <s> with the first letter of each word capitalized.
S = string.capwords("a lowercase string")
Also see capwords: |tutor|full_docs|tech_docs|
Related to: |string.swapcase|string.title|string.capitalize|
Keywords: |standard library|string module|function|string|capital
"""
"""
Python Quick Ref: 4.1.3.2
import string
Function: maketrans(from, to) -> table
Return a translation table suitable for passing to translate() or
regex.compile(), that will map each character in <from> into the
character at the same position in <to>; <from> and <to> must have the
same length.
table = maketrans('abcdefg', 'ABCDEFG')
Also see maketrans: |tutor|full_docs|tech_docs|
Related to:|regex.compile|string.translate||string.strip|string.replace|
Keywords: |standard library|string module|function|string|change
"""
Note that each individual record is complete and stands alone, with
links to a few other relavant items. The keywords allow for some nice
search results. The notes left off would be in the full docs reference.
(They would be included in the quick ref if they also are in the doc
string.)
A tutorial link may not be available for everthing, but everything that
is in the tutorial could have that link included.
Cheer's _Ron
--
http://mail.python.org/mailman/listinfo/python-list
