Confusing example in documentation for url template tag

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

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.

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

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.

stripped the project_name

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''')

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.

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.

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

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 :)

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.