Misleading docs about special characters in selectors

[breilly]

I think that the documentation about "Special characters in selectors" (at the bottom of ​http://docs.jquery.com/Selectors) is misleading. In reality, the special characters only need a single preceeding backslash; the need for a double backslash is to represent a single backslash in a javascript string literal.

Knowing that I needed to escape backslashes in javascript string literals, I was putting '

' in my javascript code so that I would be sending a double backslash to jQuery and was confused when it wasn't working. A little experimenting showed that I only needed '
' in my code.

[dmethvin]

I've edited the docs to clarify, thanks!

[Chealer]

This problem has come back. It can now be seen at the top of ​http://api.jquery.com/category/selectors/

I crafted the following which could be used as a replacement:

If you wish to use any of the meta-characters #;&,.+*~':"^$[]()=>|/ inside of an attribute selector, you must escape the character with a backslash. A literal backslash needs to be escaped with another backslash. In JavaScript string literals, \ is a special character, and as such, to include a literal backslash in a string, it must be escaped as "
". Therefore, for example, matching an element with the name "Tricky!" could be done with $('input[name=Tricky
!]'). Matching an element with the name "ProgramFiles\OpenOffice" could be done with $('input[name=ProgramFiles

OpenOffice]').

Note that current documentation doesn't explain how to escape a backslash. #jquery's ajpiano explained that, and I verified that is the actual behavior.

This is clearly fairly complicated and could use a full-fledged example.

[paul.irish]

I respectfully disagree.

The documentation explains how to do everything, with the exception of escaping a backslash, which is such an edge case it does not deserve to push down the contents of the page another four lines of text.

In my opinion, the docs should be explaining HOW to use jQUERY and not middling in the javascript internals that affect the API.

Tonight I added an example to the page and consider it completely sufficient.

[Chealer]

I disagree.

The problem that brought me here isn't the lack of documentation about backslashes, it's the claim that meta-characters need to be escaped with *2* backslashes. As the original reporter explained, jQuery only needs *1* backslash. Another backslash is typically used to escape the jQuery backslash when entering the selector as a JavaScript string literal, but this is just a JavaScript language requirement. Even though it is friendly to mention that for beginners, this shouldn't be done at the price of exactitude.

As for pushing down the page, this could be explained in a separate page. It might in fact be ideal to remove this paragraph and move it or refer to it from the pages about the selector forms using values that could need escaping (such as #id). If not, the page is already 5 pages long, adding a few lines won't make much difference.

BTW, I've been wondering how "&" and "/" are meta-characters for selectors.

[snover]

The documentation in its current state seems abundantly clear on how this works, with the provided example resolving any ambiguity about what to do.

As far as & and / go, the issue is actually much more complicated than it is described and has to do with the CSS selectors grammar. CSS does not specify which characters are metacharacters, but rather specifies the grammar of an IDENT, which is what most things are (IDs, classes, attribute names, attribute values, etc.); this grammar is significantly more complicated, and most users do not need to understand exactly how it works, so we gloss over it and just provide the short list of characters that are not allowed to exist unescaped.