*** empty log message ***

[bpt/emacs.git] / lispref / syntax.texi

diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index e4c0384..8c95e78 100644 (file)
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999

-@c   Free Software Foundation, Inc. 
+@c   Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/syntax
 @node Syntax Tables, Abbrevs, Searching and Matching, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/syntax
 @node Syntax Tables, Abbrevs, Searching and Matching, Top


@@ -135,10 +135,10 @@ modes.
 @end deffn
 
 @deffn {Syntax class} @w{word constituent}
 @end deffn
 
 @deffn {Syntax class} @w{word constituent}

-@dfn{Word constituents} (designated by @samp{w}) are parts of normal
-English words and are typically used in variable and command names in
-programs.  All upper- and lower-case letters, and the digits, are typically
-word constituents.
+@dfn{Word constituents} (designated by @samp{w}) are parts of words in
+human languages, and are typically used in variable and command names
+in programs.  All upper- and lower-case letters, and the digits, are
+typically word constituents.

 @end deffn
 
 @deffn {Syntax class} @w{symbol constituent}
 @end deffn
 
 @deffn {Syntax class} @w{symbol constituent}


@@ -397,10 +397,13 @@ prefix (@samp{'}).  @xref{Motion and Syntax}.
   In this section we describe functions for creating, accessing and
 altering syntax tables.
 
   In this section we describe functions for creating, accessing and
 altering syntax tables.
 

-@defun make-syntax-table
-This function creates a new syntax table.  It inherits the syntax for
-letters and control characters from the standard syntax table.  For
-other characters, the syntax is copied from the standard syntax table.
+@defun make-syntax-table &optional table
+This function creates a new syntax table, with all values initialized
+to @code{nil}.  If @var{table} is non-@code{nil}, it becomes the
+parent of the new syntax table, otherwise the standard syntax table is
+the parent.  Like all char-tables, a syntax table inherits from its
+parent.  Thus the original syntax of all characters in the returned
+syntax table is determined by the parent.  @xref{Char-Tables}.

 
 Most major mode syntax tables are created in this way.
 @end defun
 
 Most major mode syntax tables are created in this way.
 @end defun


@@ -408,7 +411,7 @@ Most major mode syntax tables are created in this way.
 @defun copy-syntax-table &optional table
 This function constructs a copy of @var{table} and returns it.  If
 @var{table} is not supplied (or is @code{nil}), it returns a copy of the
 @defun copy-syntax-table &optional table
 This function constructs a copy of @var{table} and returns it.  If
 @var{table} is not supplied (or is @code{nil}), it returns a copy of the

-current syntax table.  Otherwise, an error is signaled if @var{table} is
+standard syntax table.  Otherwise, an error is signaled if @var{table} is

 not a syntax table.
 @end defun
 
 not a syntax table.
 @end defun
 


@@ -425,7 +428,7 @@ This function always returns @code{nil}.  The old syntax information in
 the table for this character is discarded.
 
 An error is signaled if the first character of the syntax descriptor is not
 the table for this character is discarded.
 
 An error is signaled if the first character of the syntax descriptor is not

-one of the twelve syntax class designator characters.  An error is also
+one of the seventeen syntax class designator characters.  An error is also

 signaled if @var{char} is not a character.
 
 @example
 signaled if @var{char} is not a character.
 
 @example


@@ -433,7 +436,7 @@ signaled if @var{char} is not a character.
 @exdent @r{Examples:}
 
 ;; @r{Put the space character in class whitespace.}
 @exdent @r{Examples:}
 
 ;; @r{Put the space character in class whitespace.}

-(modify-syntax-entry ?\  " ")
+(modify-syntax-entry ?\s " ")

      @result{} nil
 @end group
 
      @result{} nil
 @end group
 


@@ -479,7 +482,7 @@ character, @samp{)}.
 
 @example
 @group
 
 @example
 @group

-(string (char-syntax ?\ ))
+(string (char-syntax ?\s))

      @result{} " "
 @end group
 
      @result{} " "
 @end group
 


@@ -559,10 +562,11 @@ table.
 have certain syntax classes.
 
 @defun skip-syntax-forward syntaxes &optional limit
 have certain syntax classes.
 
 @defun skip-syntax-forward syntaxes &optional limit

-This function moves point forward across characters having syntax classes
-mentioned in @var{syntaxes}.  It stops when it encounters the end of
-the buffer, or position @var{limit} (if specified), or a character it is
-not supposed to skip.
+This function moves point forward across characters having syntax
+classes mentioned in @var{syntaxes} (a string of syntax code
+characters).  It stops when it encounters the end of the buffer, or
+position @var{limit} (if specified), or a character it is not supposed
+to skip.

 
 If @var{syntaxes} starts with @samp{^}, then the function skips
 characters whose syntax is @emph{not} in @var{syntaxes}.
 
 If @var{syntaxes} starts with @samp{^}, then the function skips
 characters whose syntax is @emph{not} in @var{syntaxes}.


@@ -594,35 +598,39 @@ expression prefix syntax class, and characters with the @samp{p} flag.
 @section Parsing Balanced Expressions
 
   Here are several functions for parsing and scanning balanced
 @section Parsing Balanced Expressions
 
   Here are several functions for parsing and scanning balanced

-expressions, also known as @dfn{sexps}, in which parentheses match in
-pairs.  The syntax table controls the interpretation of characters, so
-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
+expressions, also known as @dfn{sexps}.  Basically, a sexp is either a
+balanced parenthetical grouping, or a symbol name (a sequence of
+characters whose syntax is either word constituent or symbol
+constituent).  However, characters whose syntax is expression prefix
+are treated as part of the sexp if they appear next to it.
+
+  The syntax table controls the interpretation of characters, so 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.
 
 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):
+  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 that 15 is the syntax code for generic string delimiters),

 
 @example
 (put-text-property 1 9 'syntax-table '(15 . nil))
 @end example
 
 
 @example
 (put-text-property 1 9 'syntax-table '(15 . nil))
 @end example
 

+@noindent

 does not tell Emacs that the first eight chars of the current buffer
 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.
+are a string, but rather that they are all string delimiters.  As a
+result, Emacs treats them as four consecutive empty string constants.

 
 

-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.)
+  Every time you use the parser, you specify it a starting state as
+well as a starting position.  If you omit the starting state, the
+default is ``top level in parenthesis structure,'' as it would be at
+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
 
 @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


@@ -660,42 +668,43 @@ The result is a list of nine elements describing the final state of
 the parse:
 
 @enumerate 0
 the parse:
 
 @enumerate 0

-@item 
+@item

 The depth in parentheses, counting from 0.
 
 The depth in parentheses, counting from 0.
 

-@item 
+@item

 @cindex innermost containing parentheses
 The character position of the start of the innermost parenthetical
 grouping containing the stopping point; @code{nil} if none.
 
 @cindex innermost containing parentheses
 The character position of the start of the innermost parenthetical
 grouping containing the stopping point; @code{nil} if none.
 

-@item 
+@item

 @cindex previous complete subexpression
 The character position of the start of the last complete subexpression
 terminated; @code{nil} if none.
 
 @cindex previous complete subexpression
 The character position of the start of the last complete subexpression
 terminated; @code{nil} if none.
 

-@item 
+@item

 @cindex inside string
 Non-@code{nil} if inside a string.  More precisely, this is the
 character that will terminate the string, or @code{t} if a generic
 string delimiter character should terminate it.
 
 @cindex inside string
 Non-@code{nil} if inside a string.  More precisely, this is the
 character that will terminate the string, or @code{t} if a generic
 string delimiter character should terminate it.
 

-@item 
+@item

 @cindex inside comment
 @code{t} if inside a comment (of either style),
 or the comment nesting level if inside a kind of comment
 that can be nested.
 
 @cindex inside comment
 @code{t} if inside a comment (of either style),
 or the comment nesting level if inside a kind of comment
 that can be nested.
 

-@item 
+@item

 @cindex quote character
 @code{t} if point is just after a quote character.
 
 @cindex quote character
 @code{t} if point is just after a quote character.
 

-@item 
+@item

 The minimum parenthesis depth encountered during this scan.
 
 @item
 The minimum parenthesis depth encountered during this scan.
 
 @item

-What kind of comment is active: @code{nil} for a comment of style ``a'',
-@code{t} for a comment of style ``b'', and @code{syntax-table} for
-a comment that should be ended by a generic comment delimiter character.
+What kind of comment is active: @code{nil} for a comment of style
+``a'' or when not inside a comment, @code{t} for a comment of style
+``b'', and @code{syntax-table} for a comment that should be ended by a
+generic comment delimiter character.

 
 @item
 The string or comment start position.  While inside a comment, this is
 
 @item
 The string or comment start position.  While inside a comment, this is


@@ -706,6 +715,12 @@ this element is @code{nil}.
 
 Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.
 
 
 Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.
 

+Actually, the return value is currently a list of ten, rather than
+nine, elements and @var{state} is allowed to be a list of ten elements
+as well.  However, the meaning of the tenth element is subject to
+change and only the first eight elements of @var{state} need to be
+specified.
+

 @cindex indenting with parentheses
 This function is most often used to compute indentation for languages
 that have nested parentheses.
 @cindex indenting with parentheses
 This function is most often used to compute indentation for languages
 that have nested parentheses.


@@ -748,31 +763,40 @@ before count is used up, @code{nil} is returned.
 @defvar multibyte-syntax-as-symbol
 @tindex multibyte-syntax-as-symbol
 If this variable is non-@code{nil}, @code{scan-sexps} treats all
 @defvar multibyte-syntax-as-symbol
 @tindex multibyte-syntax-as-symbol
 If this variable is non-@code{nil}, @code{scan-sexps} treats all

-non-@sc{ascii} characters as symbol constituents regardless
+non-@acronym{ASCII} characters as symbol constituents regardless

 of what the syntax table says about them.  (However, text properties
 can still override the syntax.)
 @end defvar
 
 of what the syntax table says about them.  (However, text properties
 can still override the syntax.)
 @end defvar
 

-@defvar parse-sexp-ignore-comments
+@defopt parse-sexp-ignore-comments

 @cindex skipping comments
 If the value is non-@code{nil}, then comments are treated as
 whitespace by the functions in this section and by @code{forward-sexp}.
 @cindex skipping comments
 If the value is non-@code{nil}, then comments are treated as
 whitespace by the functions in this section and by @code{forward-sexp}.

+@end defopt

 
 

-In older Emacs versions, this feature worked only when the comment
-terminator is something like @samp{*/}, and appears only to end a
-comment.  In languages where newlines terminate comments, it was
-necessary make this variable @code{nil}, since not every newline is the
-end of a comment.  This limitation no longer exists.
-@end defvar
+@vindex parse-sexp-lookup-properties
+The behaviour of @code{parse-partial-sexp} is also affected by
+@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).

 
 You can use @code{forward-comment} to move forward or backward over
 one comment or several comments.
 
 @defun forward-comment count
 
 You can use @code{forward-comment} to move forward or backward over
 one comment or several comments.
 
 @defun forward-comment count

-This function moves point forward across @var{count} comments (backward,
-if @var{count} is negative).  If it finds anything other than a comment
-or whitespace, it stops, leaving point at the place where it stopped.
-It also stops after satisfying @var{count}.
+This function moves point forward across @var{count} complete comments
+(that is, including the starting delimiter and the terminating
+delimiter if any), plus any whitespace encountered on the way.  It
+moves backward if @var{count} is negative.  If it encounters anything
+other than a comment or whitespace, it stops, leaving point at the
+place where it stopped.  This includes (for instance) finding the end
+of a comment when moving forward and expecting the beginning of one.
+The function also stops immediately after moving over the specified
+number of complete comments.  If @var{count} comments are found as
+expected, with nothing except whitespace between them, it returns
+@code{t}; otherwise it returns @code{nil}.
+
+This function cannot tell whether the ``comments'' it traverses are
+embedded within a string.  If they look like comments, it treats them
+as comments.

 @end defun
 
 To move forward over all comments and whitespace following point, use
 @end defun
 
 To move forward over all comments and whitespace following point, use


@@ -866,10 +890,10 @@ to each syntactic type.
 @tab
 9 @ @  escape
 @tab
 @tab
 9 @ @  escape
 @tab

-14 @ @  comment-fence
+14 @ @  generic comment

 @item
 @tab
 @item
 @tab

-15 @  string-fence
+15 @  generic string

 @end multitable
 
   For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
 @end multitable
 
   For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.


@@ -927,7 +951,7 @@ category table defines its own categories, but normally these are
 initialized by copying from the standard categories table, so that the
 standard categories are available in all modes.
 
 initialized by copying from the standard categories table, so that the
 standard categories are available in all modes.
 

-  Each category has a name, which is an @sc{ascii} printing character in
+  Each category has a name, which is an @acronym{ASCII} printing character in

 the range @w{@samp{ }} to @samp{~}.  You specify the name of a category
 when you define it with @code{define-category}.
 
 the range @w{@samp{ }} to @samp{~}.  You specify the name of a category
 when you define it with @code{define-category}.
 


@@ -938,12 +962,12 @@ belongs to.  In this category set, if the element at index @var{cat} is
 @code{t}, that means category @var{cat} is a member of the set, and that
 character @var{c} belongs to category @var{cat}.
 
 @code{t}, that means category @var{cat} is a member of the set, and that
 character @var{c} belongs to category @var{cat}.
 

+For the next three functions, the optional argument @var{table}
+defaults to the current buffer's category table.
+

 @defun define-category char docstring &optional table
 This function defines a new category, with name @var{char} and
 @defun define-category char docstring &optional table
 This function defines a new category, with name @var{char} and

-documentation @var{docstring}.
-
-The new category is defined for category table @var{table}, which
-defaults to the current buffer's category table.
+documentation @var{docstring}, for the category table @var{table},

 @end defun
 
 @defun category-docstring category &optional table
 @end defun
 
 @defun category-docstring category &optional table


@@ -958,7 +982,7 @@ in category table @var{table}.
 @end example
 @end defun
 
 @end example
 @end defun
 

-@defun get-unused-category table
+@defun get-unused-category &optional table

 This function returns a category name (a character) which is not
 currently defined in @var{table}.  If all possible categories are in use
 in @var{table}, it returns @code{nil}.
 This function returns a category name (a character) which is not
 currently defined in @var{table}.  If all possible categories are in use
 in @var{table}, it returns @code{nil}.


@@ -980,7 +1004,7 @@ This function returns the standard category table.
 @defun copy-category-table &optional table
 This function constructs a copy of @var{table} and returns it.  If
 @var{table} is not supplied (or is @code{nil}), it returns a copy of the
 @defun copy-category-table &optional table
 This function constructs a copy of @var{table} and returns it.  If
 @var{table} is not supplied (or is @code{nil}), it returns a copy of the

-current category table.  Otherwise, an error is signaled if @var{table}
+standard category table.  Otherwise, an error is signaled if @var{table}

 is not a category table.
 @end defun
 
 is not a category table.
 @end defun
 


@@ -1010,11 +1034,11 @@ other categories.
 @end defun
 
 @defun char-category-set char
 @end defun
 
 @defun char-category-set char

-This function returns the category set for character @var{char}.  This
-is the bool-vector which records which categories the character
-@var{char} belongs to.  The function @code{char-category-set} does not
-allocate storage, because it returns the same bool-vector that exists in
-the category table.
+This function returns the category set for character @var{char} in the
+current buffer's category table.  This is the bool-vector which
+records which categories the character @var{char} belongs to.  The
+function @code{char-category-set} does not allocate storage, because
+it returns the same bool-vector that exists in the category table.

 
 @example
 (char-category-set ?a)
 
 @example
 (char-category-set ?a)


@@ -1043,8 +1067,13 @@ But if @var{reset} is non-@code{nil}, then it deletes @var{category}
 instead.
 @end defun
 
 instead.
 @end defun
 

-@deffn Command describe-categories
+@deffn Command describe-categories &optional buffer-or-name

 This function describes the category specifications in the current
 This function describes the category specifications in the current

-category table.  The descriptions are inserted in a buffer, which is
-then displayed.
+category table.  It inserts the descriptions in a buffer, and then
+displays that buffer.  If @var{buffer-or-name} is non-@code{nil}, it
+describes the category table of that buffer instead.

 @end deffn
 @end deffn

+
+@ignore
+   arch-tag: 4d914e96-0283-445c-9233-75d33662908c
+@end ignore