[issue22702] to improve documentation for join() (str method)
New submission from Van Ly: This issue should go in the Documentation component but that is not an option in the issue tracker. Suggestion to improve documentation for join() (str method). Applies to versions 2.7.5, 3.3.6, 3.5.0a0. --quote str.join(iterable) Returns a string. Uses the string str to join strings from iterable. Raises TypeError for non-string found in iterable including object of bytes. >>> # the iterable consists of number >>> try: >>> print "-".join([0, 1, 2, 3]) >>> except TypeError: >>> print "A non-string is found in the iterable." A non-string is found in the iterable. >>> # the iterable consists of string >>> try: >>> print ", ".join(["x", "y", "z", "0", "1", "2", "3"]) >>> print " - ".join(["x", "y", "z", "0", "1", "2", "3"]) >>> print " + ".join(["x", "y", "z", "0", "1", "2", "3"]) >>> except TypeError: >>> print "A non-string is found in the iterable." x, y, z, 0, 1, 2, 3 x - y - z - 0 - 1 - 2 - 3 x + y + z + 0 + 1 + 2 + 3 --quote-- -- components: Macintosh files: documentationForJoin.rtf messages: 229841 nosy: ned.deily, ronaldoussoren, vy0123 priority: normal severity: normal status: open title: to improve documentation for join() (str method) type: enhancement versions: Python 2.7, Python 3.3, Python 3.5 Added file: http://bugs.python.org/file36995/documentationForJoin.rtf ___ Python tracker <http://bugs.python.org/issue22702> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22702] to improve documentation for join() (str method)
Van Ly added the comment: The improvement on the original (doc v.2.7.5) lies in the removal of the repeated 'iterable' in the first sentence, and I have also shortened it to deliver only what is returned by the builtin method which was what I wanted to know without knowing how. I wrote up this reformulation as I would have like to read it. I believe the word "concatenation" is off putting to beginners without a formal background or wanting to acquire that, and there are people like me who prefer plain and simple words. "concatenation" could be used in a footnote to guide readers to more depth if that is something they want to have. The inline usage example serves to confirm what has been described/claimed. --original: doc v.2.7.5 str.join(iterable) Return a string which is the concatenation of the strings in the iterable iterable. The separator between elements is the string providing this method. -- ___ Python tracker <http://bugs.python.org/issue22702> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22702] to improve documentation for join() (str method)
Van Ly added the comment: Aim for the fewest syllables in the words without losing meaning or good taste. -- ___ Python tracker <http://bugs.python.org/issue22702> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22714] target of 'import statement' entry in general index for 'i' is wrong
New submission from Van Ly: The target points to within '__import__()' but should point to 'import()' method function. For example, # 'import statement' entry at index for 'i' on the following page python-2.7.5-docs-html/genindex-I.html # points to python-2.7.5-docs-html/library/functions.html#index-8 # but should point to python-2.7.5-docs-html/reference/simple_stmts.html#import -- assignee: docs@python components: Documentation messages: 229914 nosy: docs@python, vy0123 priority: normal severity: normal status: open title: target of 'import statement' entry in general index for 'i' is wrong type: enhancement versions: Python 2.7, Python 3.3, Python 3.5 ___ Python tracker <http://bugs.python.org/issue22714> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22725] improve documentation for enumerate() (built-in function)
New submission from Van Ly: The existing documentation is confusing. — improve wording as follows enumerate(sequence, start=0) Returns pairings of index into sequence[link to glossary.html#term-sequence] with the object at that index in the sequence. — wording as found in v.2.7.5 enumerate(sequence, start=0) Return an enumerate object. sequence must be a sequence, an iterator, or some other object which supports iteration. The next() method of the iterator returned by enumerate() returns a tuple containing a count (from start which defaults to 0) and the values obtained from iterating over sequence: -- assignee: docs@python components: Documentation messages: 229979 nosy: docs@python, vy0123 priority: normal severity: normal status: open title: improve documentation for enumerate() (built-in function) type: enhancement versions: Python 2.7, Python 3.3, Python 3.5 ___ Python tracker <http://bugs.python.org/issue22725> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22725] improve documentation for enumerate() (built-in function)
Van Ly added the comment: I don't want to argue. Ask a 12-year old and their English teacher, "Does the second sentence qualify as gobbledygook even if it is technically correct and complete and not verbose?" To be constructive and take on what has been said, an iteration on improving the wording: -- improve wording as follows: enumerate(iteratable, start=0) Accepts an iteratable[typo for iterable?] and returns an iterator, a special case 'enumerate object'. The method iterator.next() returns a tuple which pairs an index counter with the object at the index in iterable. >>> led = ['red', 'green', 'blue'] led = ['red', 'green', 'blue'] >>> iter = enumerate(led) iter = enumerate(led) >>> iter.next() iter.next() (0, 'red') >>> iter.next() iter.next() (1, 'green') >>> iter.next() iter.next() (2, 'blue') # While enumerate does not return a list of pairs, # it is easy to collect the pairs and construct a list as follows >>> list(enumerate(led)) list(enumerate(led)) [(0, 'red'), (1, 'green'), (2, 'blue')] -- ___ Python tracker <http://bugs.python.org/issue22725> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22725] improve documentation for enumerate() (built-in function)
Van Ly added the comment: Understood. I felt the problem was self evident with "sequence must be a sequence". -- ___ Python tracker <http://bugs.python.org/issue22725> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22725] improve documentation for enumerate() (built-in function)
Van Ly added the comment: > "sequence must be a sequence" The subtle minutiae of aficionados necessary to interpret the meaning of those two words in their distinct relation is opaque to a new comer and doesn’t serve the widest possible audience usefully to get the job done quick. The second placed sense has a range of possibility narrower than iterable as has been said, all sequences are iterables but not all iterables sequences. -- ___ Python tracker <http://bugs.python.org/issue22725> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22725] improve documentation for enumerate() (built-in function)
Van Ly added the comment: The first mention of iterator should link to 'glossary.html#term-iterator'. There is a builtin iter() function. This may cause confusion in earlier suggested inline sample code. -- Use the following inline sample code -- in place of 'iter = enumerate(led)'to avoid confusion with iter() builtin: led = ['red', 'green', 'blue'] iterator = enumerate(led) try: while True: print iterator.next() except StopIteration: print 'End of iterator has been reached.' -- ___ Python tracker <http://bugs.python.org/issue22725> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22736] tutorial links at top, book recommendations at bottom of module documentation
New submission from Van Ly: IMO the box highlight at the top of module documentation, for example, re module (library/re.html#module-re), ought to place book recommendations at the very bottom in a section called 'Further Readings'. Why? Because being at the top of the documentation should mean it is instantly accessible. The box highlight of tutorials at the top is a nice touch. -- assignee: docs@python components: Documentation messages: 230052 nosy: docs@python, vy0123 priority: normal severity: normal status: open title: tutorial links at top, book recommendations at bottom of module documentation type: enhancement versions: Python 2.7, Python 3.5 ___ Python tracker <http://bugs.python.org/issue22736> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22725] improve documentation for enumerate() (built-in function)
Van Ly added the comment: Reference by the guide to next() should stay for the same reason in re.compile() a regular expression object is returned and the two methods are mentioned, match() and search(). They are useful to know in that context in as much as next() is useful to know here. IMO. -- ___ Python tracker <http://bugs.python.org/issue22725> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22738] improve sys.argv, 'python -h' documentation
New submission from Van Ly: I was looking at sys.argv from the reference guide. The font mix and change from v.2.7.5 to v.3.5.0a0 for sentence two of sys.argv (library/sys.html#module-sys) has made the second rendering of -c look capital when in fact it isn't. --quote: from v.3.5.0a0 at library/sys.html#module-sys If the command was executed using the -c command line option to the interpreter, argv[0] is set to the string '-c'. --quote-- --suggest: improve second sentence of sys.argv (v.2.7.5, v.3.5.0a0) Call the Python interpreter with the option, -c str, and the value of argv[0] is '-c'. --suggest-- --suggest: improve 'python -h' output -c str : feed in a string as program (terminates option list) --suggest-- -- assignee: docs@python components: Documentation messages: 230059 nosy: docs@python, vy0123 priority: normal severity: normal status: open title: improve sys.argv, 'python -h' documentation type: enhancement versions: Python 2.7, Python 3.5 ___ Python tracker <http://bugs.python.org/issue22738> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22725] improve documentation for enumerate() (built-in function)
Van Ly added the comment: While next() is rarely used directly on iterators, as you say, it may help to remind the experienced reader of the mechanical characteristic in essence which a new reader on first approach uses to construct a mental model. -- ___ Python tracker <http://bugs.python.org/issue22725> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22741] suggestion for improving wording on len(s) (built-in function)
New submission from Van Ly: -- suggest the following because -- the parenthetical parts interrupt the reading too often len(s) Returns a length count, the number of objects in argument s which may be a sequence, or mapping: a string, list or tuple, or a dictionary. -- assignee: docs@python components: Documentation messages: 230068 nosy: docs@python, vy0123 priority: normal severity: normal status: open title: suggestion for improving wording on len(s) (built-in function) type: enhancement versions: Python 2.7, Python 3.5 ___ Python tracker <http://bugs.python.org/issue22741> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22738] improve sys.argv, 'python -h' documentation
Van Ly added the comment: The font choice is a matter of style beyond me. I commented on it as I saw it. The second rendering looks in Capital relative to the first rendering. The problem wasn't there in v.2.7.5. In saying that, perhaps the information would be picked up by someone knowledgeable about the style sheet. The focus of the suggestion is in the head line about the wording. I chose 'feed' because it would align with the theme of python and pickling. 'interpret' isn't as nice a picture word. -- ___ Python tracker <http://bugs.python.org/issue22738> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22741] suggestion for improving wording on len(s) (built-in function)
Van Ly added the comment: (Well that is a stick in the mud and slap in the face attitude to different ways of describing what is there.) You have the documentation for len(s) perfect, __for_everyone__. -- ___ Python tracker <http://bugs.python.org/issue22741> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22738] improve 'python -h' documentation for '-c'
Van Ly added the comment: I don't know what you mean by optimal English. As is, the English is of the native English speaker's comfy couch guides speaking to guides kind rather than guides speaking to audience wanting to be guided by. The suggestion I offered is imperfect and can be improved or rejected. As communication, it is shorter than the original and applies the dry principle, don't repeat yourself. Command occurs twice and the native English speaker may feel they are different in their senses. As sequence was in another suggestion for enhancement (and not a bug). You have your point of view which is from the internal technical guts of this language. I am approaching the language from the fun of Monty Python and imagery of a python pickled in a jar. I have done a few tutorials and read code with this reference guide as I would use a dictionary to explain words in a passage. I expect in a final stage of approval an editor ensures correctness of English to whatever the standard is. -- ___ Python tracker <http://bugs.python.org/issue22738> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22738] improve 'python -h' documentation for '-c'
Van Ly added the comment: > -c str : interpret str as a program (terminates option list) +1 (feed is shorter) -- ___ Python tracker <http://bugs.python.org/issue22738> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
