id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
6752	"Documentation slightly  unclear about ""safe"" strings in filters"	<removed at reporter's request>	Joshua Russo	"My objective here is to prevent somebody else from falling into the same trap as I. 

This is with regard to auto-escaping, the safe filter, and escapejs. I had auto-escaping on and tried the following:

template_string|safe|escape

I now now this is clearly wrong because in the docs it states. ""This does /not/ make the string safe for use in HTML."" But when I first read it, I thought this was perfect and that all I need to do is the above statement. I would use safe to clear the auto-escaping and the escape the string for javascript. But this is not how it works. Albeit, I might have over-thinked it but I figured that ""safe"" either set a bit in the template context so that auto-escaping would not happen at the end. I didn't realize that ""This does /not/ make the string safe for use in HTML"" meaning that auto-escaping would pick up on this fact and escape the string. The output of another filter might make the string unsafe again. 

So the logic is correct. I would like to see a change to the docs here are some ideas:

1. Update the documentation for Safe to be something like the following:
""Marks a string as not requiring further HTML escaping prior to output. When this filter is not the last filter applied, subsequent filters might make string /not/ safe for HTML output and the string will be escaped if auto-escaping is on. When autoescaping is off, this filter has no effect.""

That's obviously too wordy but I think it brings across the point.

2. Update auto-escaping docs to mention that safe will turn off auto-escaping unless a filter that follows safe makes the string unsafe for HTML output.

3. Or maybe just a more technical explaination of how safe, escape, and auto-escape work under the covers.

Thanks."		closed	Documentation	dev		fixed	safe, auto-escape, escapejs		Ready for checkin	1	0	0	0	0	0