Confusing example in documentation for url template tag

[Collin Grady <cgrady@…>]

The documentation for the url template tag shows it linking to a view as 'app_name.client' which would require a very abnormal project setup to be valid - because of this, it can be confusing to newer django users - I was helping someone on IRC that thought the tag did some translation from app.viewname to project.app.views.viewname :)

[Marc Fargas <telenieko@…>]

Yes, it's better to stay consistent across the documentation!

[Malcolm Tredinnick]

Leave the project name out of the change, though, that makes things less portable (because if you move the app to somewhere else on your Python path, you have to change every URLConf entry that refers to it). Including "viewe" makes sense, though.

[Collin Grady <cgrady@…>]

project_name is used elsewhere though, including in that very same example (the include line) - should that be changed also?

[Marc Fargas <telenieko@…>]

Replying to mtredinnick:

Leave the project name out of the change, though, that makes things less portable (because if you move the app to somewhere else on your Python path, you have to change every URLConf entry that refers to it). Including "viewe" makes sense, though.

I agree that including the project name makes things less portable but starting at the tutorial 01 ​http://www.djangoproject.com/documentation/tutorial01/#playing-with-the-api we are telling newcomers to include it (mysite in this case) so we should a) recommend it b) don't do it. But being consistent as much as possible on all the docs/

I'd rather go for the "do not recommend including the project name on imports" but on the whole docs ;)

Anyway, updated patch follows.

[Marc Fargas <telenieko@…>]

stripped the project_name

[Marc Fargas <telenieko@…>]

Replying to Collin Grady <cgrady@the-magi.us>:

project_name is used elsewhere though, including in that very same example (the include line) - should that be changed also?

You're right, project_name is used in the middle of the section the patch correct which makes it sound strange. Let's let triagers decide whether to apply the first patch or making a new one changing all project_name references on templates.txt

(which means: do not apply the second patch as it makes the section sound strange''')

[Chris Beaven]

Consistency is good. I say apply the first patch and open a new ticket to remove the project_name references throughout the templates doc file.

[Malcolm Tredinnick]

Replying to Marc Fargas <telenieko@telenieko.com>:

... decide whether to apply the first patch or making a new one changing all project_name references on templates.txt

The only other reference to project_name in that whole file is in a completely different context: it's two lines later showing how the project-wide !URLConf file might include the app-specific !URLConf. Not a bad place to use the project name.

There's no inconsistency at all here (tutorials are not the same as reference document; don't conflate the two). Using project name sometimes and not others is not a disaster. Certainly not in this case.

[Malcolm Tredinnick]

(In [5353]) Fixed #4355 -- Clarified a confusing example in the use of the url template
tag. Based on a patch from Collin Grady.

[Collin Grady <cgrady@…>]

But won't only one of the two methods work depending on your pythonpath setup? (unless you're in a file in the project root)

Seems like an important bit of inconsistency :)

[Malcolm Tredinnick]

The first line is in the app dir, the second line is in the project's URL conf -- that is clear in the example -- so both have their own directory in their effective Python import path. The docs say "if is is included like this", setting up the precondition. It doesn't say you have to import it like that. We are not spoon-feeding here, intentionally; that drags down the quality of the docs for the other 90% of readers. If somebody need to stop and think for a minute to get the example straight, no harm is done.

There really are far more important problems to fix than going around and around on this. Let's move on, please.