syntax-ppss (was: imenu fails in mode without comment-start-skip defined)

[Stefan Monnier]

> I think basically all it needs is to say that it's a more efficient
> version of parse-partial-sexp (using a cache) with the restrictions
> mentioned in the doc string (and any others?).

Other restriction: it does not notice when the syntax-table is changed
between two calls, so it might use cache data that was obtained with an
other syntax-table.  E.g. the cache is often filled by syntax-ppss being
called from font-lock where the syntax-table can be slightly different.
It usually doesn't matter, luckily.

> Warn that it might clobber the match data via syntax-begin-function and
> maybe also mention syntax-ppss-context.

I wouldn't bother with syntax-ppss-context (and syntax-ppss-depth).
These are just functions I'd originally written for XEmacs compatibility,
but it turns out that they really aren't much use in my experience.
It's just as easy to test (nth 8 (syntax-ppss)) or (nth 3 (syntax-ppss)).


        Stefan