Try to explain syntax-tables a little bit more.

1 files changed, 24 insertions, 0 deletions

diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index 6cf42f9454e..e4c0384ccff 100644
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -600,6 +600,30 @@ these functions can be used for Lisp expressions when in Lisp mode and
 for C expressions when in C mode.  @xref{List Motion}, for convenient
 higher-level functions for moving over balanced expressions.
 
+A syntax table only describes how each character changes the state of
+the parser, rather than describing the state itself.  For example, a string
+delimiter character toggles the parser state between ``in-string'' and
+``in-code'' but the characters inside the string do not have any particular
+syntax to identify them as such.
+
+For example (note: 15 is the syntax-code of generic string delimiters):
+
+@example
+(put-text-property 1 9 'syntax-table '(15 . nil))
+@end example
+
+does not tell Emacs that the first eight chars of the current buffer
+are a string, but rather that they are all string delimiters and thus
+Emacs should treat them as four adjacent empty strings.
+
+The state of the parser is transient (i.e. not stored in the buffer for
+example).  Instead, every time the parser is used, it is given not just
+a starting position but a starting state.  If the starting state is not
+specified explicitly, Emacs assumes we are at the top level of parenthesis
+structure, such as the beginning of a function definition (this is the case
+for @code{forward-sexp} which blindly assumes that the starting point is in
+such a state.)
+
 @defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment
 This function parses a sexp in the current buffer starting at
 @var{start}, not scanning past @var{limit}.  It stops at position