On Mon, Dec 13, 2010 at 8:58 PM, Vinay Sajip wrote:

Nick Coghlan writes:

...

Vinay is currently working on updates to the logging documentation, and this is one of the things that is likely to change (with the table of attributes moved to the LogRecord section and referenced from the sections on Formatter and Filter objects).

Yes, and to compound matters, the LogRecord constructor documentation lists the attribute values in the place you'd expect the parameters to appear, using the doc markup for attributes. This I think is what causes the confusion, although the markup is different to that used for parameters it's not clear at first glance.

However, these changes are after 2.7 and 3.1: In 2.6 documentation the parameters are named as in the source, but there's no reference in the LogRecord reference documentation about any attributes of the LogRecord.

That's the problem though - if you don't read the intro paragraph closely (which I didn't do), it's easy to jump to the conclusion that those are also the attributes (since there is nothing else in the section).

Perhaps it would be best to do the following:

- Add constructor params using normal parameter markup (:param:) - Create a separate section "LogRecord Attributes" with a table containing attr name, description, how to use with % formatting and how to use with {}-formatting. There is some overlap here with the parameter documentation for the LogRecord constructor, but I can put in a rider which explains that the param names and attr names are slightly different. (I could kick myself now for not being more scrupulous originally, but I'm not sure I can go back and change the param names in the source code now because in theory, someone might be constructing a LogRecord using LogRecord(**kwargs)).

- Link to the latter section from the Formatter, Filter sections.

Anyone see problems with this, or have a better suggestion?

Yep, that's what I had assumed you were going to do (this did come up in the big thread about the logging docs, but you may have missed it). You're also right about the backwards compatibility problem with changing the parameter names. It's the one downside of keyword arguments - it makes the parameter names part of a function's public API, so they are much harder to fix when you make a mistake. That said, you can't get a one-to-one correspondence in this case anyway, since some of the parameters relate to multiple attributes (e.g. "lvl" becomes both "levelNo" and "levelName"). It is rare that anyone will be constructing a LogRecord manually though, so I don't think the parameter names matter all that much in practice. It is far more common that people will be creating them implicitly through the Logger event notification methods or by deserialising them. Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

Nick Coghlan writes:

Yep, that's what I had assumed you were going to do (this did come up in the big thread about the logging docs, but you may have missed it).

Ok, I've now checked in this change, and would be grateful for any feedback. Time for a break :-) Thanks a lot for all your patience and valuable feedback, Nick. It's been very helpful, and I hope it will make the logging docs more accessible to those who've been put off in the past. I've emailed Georg about how best to reorganise into: intro + basic tutorial (at current location) advanced tutorial reference cookbook and I'm waiting for his suggestions on how best to implement (in terms of breaking up into different files etc). Thanks and regards, Vinay

Nick Coghlan writes:

Hmm, that may not have built correctly, since it isn't showing up in the web version of the dev docs yet. I skimmed the diff on python-checkins though, and it looked good to me.

I'll keep an eye on the build (built OK on my machine but I'm not sure what the build trigger is for docs.python.org).

I think the revised docs should make it *much* easier for people to get a handle on how the logging system works (I know my own understanding of it is significantly better than it was a couple of weeks ago).

Glad to hear that.

P.S. I'm off visiting family for a couple of weeks, so my email access is going to be sketchy for a while.

Have a nice time, and thanks for all the help. Regards, Vinay

On 13/12/2010 10:31, Vinay Sajip wrote: [...]

Ideally, link to the wrong doc section on docs.python.org in your bug report.

Now that's not a piece of advice you see very often :) TJG

On Mon, Dec 13, 2010 at 9:04 PM, Vinay Sajip wrote:

Tim Golden writes:

...

On 13/12/2010 10:31, Vinay Sajip wrote: [...]

...

Ideally, link to the wrong doc section on docs.python.org in your bug report.

Now that's not a piece of advice you see very often :)

True, but this area changed after 2.6 was released (after even 2.7, IIRC), so I want to be sure that if I'm going to change the doc sources on release26-maint, I'm doing the right thing.

It was more a comment on the fact that, at first glance, that sentence looks like an instuction to provide an incorrect link, rather than to provide a link to the section of the docs that is incorrect. Just a quirk of English grammar :) Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

Tim Golden writes:

...

It was more a comment on the fact that, at first glance, that sentence looks like an instuction to provide an incorrect link, rather than to provide a link to the section of the docs that is incorrect. Just a quirk of English grammar :)

Thanks, Nick. That is what I meant. I wanted to indicate that it was tongue-in-cheek, but I never can remember the sequence of characters which means that...

Aaargh! You're right of course, I was too hasty in typing "link to the wrong doc section" rather than the only slightly longer "link to the doc section which is wrong". Tim - when you find those emoticons, be sure to let me know the one for "facepalm" ;-) Regards, Vinay

On Tue, Dec 14, 2010 at 5:34 AM, Terry Reedy wrote:

On 12/13/2010 6:04 AM, Vinay Sajip wrote:

True, but this area changed after 2.6 was released (after even 2.7, IIRC),

...

so I want to be sure that if I'm going to change the doc sources on release26-maint,

2.6 is in security-fix only mode. I am not sure if that precludes doc fixes, on the chance that there will ever be a security fix, as it does non-security bug fixes, but is it hardly worth the bother compared to improving active releases.

Fixing it in the 2.7 maintenance branch will be sufficient to modify docs.python.org, which is likely the most important place to update. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia