Vinay Sajip <[EMAIL PROTECTED]> added the comment: In your original submission, you said:
"... the front page has a rather confusing example of the named hierarchy system, which might mislead the reader by making them think it's about file types (perhaps for log output) rather than just arbitrary naming conventions." What the front page says is: "Each [Logger] instance has a name, and they are conceptually arranged in a name space hierarchy using dots (periods) as separators. For example, a logger named "scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want, and indicate the area of an application in which a logged message originates." Notice the last sentence, which clearly (to me) states that logger names can by anything you want, i.e. an arbitrary naming convention. Although the examples given were "scan.text", "scan.html" and "scan.pdf", I don't believe the average user would confuse this with file types for log output, unless they skimmed the paragraph. The paragraph does not mention file types anywhere else, and nor do the next few paragraphs. The example in section 14.5.3 is fairly well commented, so IMO it's misrepresenting it a little to call it a "code dump". It's not the first example, either - a number of shorter examples are shown earlier in the documentation. When the logging package was introduced into Python back in version 2.3, there were some valid comments from people about lack of examples and lack of clarity in the documentation. This was rectified over time, and your comment is the first one for several months about documentation clarity. About documentation, it could always be argued that it could be clearer, because there's bound to be someone who doesn't understand it. But maintenance of this package (and Python) is a spare-time activity for most of us, and a number of competing priorities have to be traded off when deciding how to spend that time. I have spent a fair amount of time over the months improving the documentation, as have others, to the point where we don't get many comments about it; hence, it's time, from my point of view, to scratch other itches. If people feel strongly enough about it, they'll submit specific ideas or patches, which can be easily incorporated into the documentation. (You can look at the history of changes to the logging documentation in SVN to see that it updated reasonably often.) Simply stating that it "is quite confusing" is so open ended that an effort to make it less confusing could take a very long time, and that's why I invited a patch: I got the impression that you now understand how the hierarchy etc. works, even if you didn't straight away. If you are still having difficulty understanding some aspects of the package, please post on comp.lang.python: you will see that queries are reasonably promptly answered, not always by core developers but often by other users of the logging package. __________________________________ Tracker <[EMAIL PROTECTED]> <http://bugs.python.org/issue1579> __________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
