Author vinay.sajip
Recipients Kylotan, facundobatista, vinay.sajip
Date 2008-03-30.00:56:32
SpamBayes Score 8.6517e-05
Marked as misclassified No
Message-id <1206838598.71.0.533666809889.issue1579@psf.upfronthosting.co.za>
In-reply-to
Content
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.
History
Date User Action Args
2008-03-30 00:56:39vinay.sajipsetspambayes_score: 8.6517e-05 -> 8.6517e-05
recipients: + vinay.sajip, facundobatista, Kylotan
2008-03-30 00:56:38vinay.sajipsetspambayes_score: 8.6517e-05 -> 8.6517e-05
messageid: <1206838598.71.0.533666809889.issue1579@psf.upfronthosting.co.za>
2008-03-30 00:56:36vinay.sajiplinkissue1579 messages
2008-03-30 00:56:32vinay.sajipcreate