Mailing List Archive: Python: Bugs

[issue6486] Library doc introduction strangely points to "Built-in Objects" as a starting point

Index | Next | Previous | View Threaded

report at bugs

Jul 14, 2009, 3:50 PM

Post #1 of 3 (197 views)
Permalink

[issue6486] Library doc introduction strangely points to "Built-in Objects" as a starting point

New submission from Mitchell Model <mlm [at] acm>:

At the end of the introduction page of the library documentation there
is a strange suggestion to begin with "Built-in Objects" as a starting
point. The "Built-in Objects" page consists of two paragraphs that will
surely mystify people new to Python. I'm not sure where it was supposed
to point -- built-in functions? built-in types? But surely not "Built-in
Objects"?

Or another interpretation, which on deeper investigation, strikes me as
the correct one: "Built-in Objects", which references tables, operators,
etc. that don't appear on that page, is simply an introduction to
"Built-in Types", or an introduction to all the subsequent chapters. In
that case, I see the challenge for structuring the top-level chapters of
the library documentation, but perhaps these two paragraphs could simply
be moved to the introduction and the "Built-in Objects" eliminated.
Besides, aren't built-in functions and constants, which come before this
page, built-in objects too?

----------
assignee: georg.brandl
components: Documentation
messages: 90524
nosy: MLModel, georg.brandl
severity: normal
status: open
title: Library doc introduction strangely points to "Built-in Objects" as a starting point
versions: Python 2.7, Python 3.0, Python 3.1, Python 3.2

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue6486>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com

report at bugs

Jul 14, 2009, 4:55 PM

Post #2 of 3 (168 views)
Permalink

[issue6486] Library doc introduction strangely points to "Built-in Objects" as a starting point [In reply to]

Ezio Melotti <ezio.melotti [at] gmail> added the comment:

I agree, the built-in functions page [1] is a good place where to start
and indeed it's the page that follows the introduction [2].
The built-in object page/section [3] should be probably
included/integrated with one of the other pages (and possibly rephrased
too - it's not immediately clear what this "symbol table" is. If it
refers to the __builtins__ namespace it should be stated clearly,
possibly pointing to a glossary entry or to another section).

[1]: http://docs.python.org/library/functions.html
[2]: http://docs.python.org/library/intro.html
[3]: http://docs.python.org/library/objects.html

----------
nosy: +ezio.melotti
priority: -> normal

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue6486>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com

report at bugs

Jul 16, 2009, 12:34 AM

Post #3 of 3 (149 views)
Permalink

[issue6486] Library doc introduction strangely points to "Built-in Objects" as a starting point [In reply to]

Georg Brandl <georg [at] python> added the comment:

I moved the link target to the "built-in functions" section in r74021.
For the other issue, I wanted to restructure the builtins docs anyway
for a long time, this will be part of it.

----------
resolution: -> fixed
status: open -> closed

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue6486>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads