emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] /srv/bzr/emacs/trunk r109430: Doc fixes and improvements f


From: Chong Yidong
Subject: [Emacs-diffs] /srv/bzr/emacs/trunk r109430: Doc fixes and improvements for syntax tables.
Date: Sat, 04 Aug 2012 22:33:00 +0800
User-agent: Bazaar (2.5.0)

------------------------------------------------------------
revno: 109430
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2012-08-04 22:33:00 +0800
message:
  Doc fixes and improvements for syntax tables.
  
  * src/syntax.c (Fmodify_syntax_entry): Doc fix.
  
  * doc/lispref/syntax.texi (Syntax Basics): Rearrange the text for clarity.
  Fix description of syntax table inheritance.
  (Syntax Table Functions): Don't refer to internal contents of
  syntax table, since that is not explained yet.  Copyedits.
  (Standard Syntax Tables): Node deleted.
  (Syntax Table Internals): Misc clarifications.  Improve table
  formatting.
  
  * doc/lispref/keymaps.texi (Inheritance and Keymaps):
  * doc/lispref/text.texi (Sticky Properties): Tweak index entry.
modified:
  doc/lispref/ChangeLog
  doc/lispref/elisp.texi
  doc/lispref/keymaps.texi
  doc/lispref/syntax.texi
  doc/lispref/text.texi
  src/ChangeLog
  src/syntax.c
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-08-01 02:14:20 +0000
+++ b/doc/lispref/ChangeLog     2012-08-04 14:33:00 +0000
@@ -1,3 +1,16 @@
+2012-08-04  Chong Yidong  <address@hidden>
+
+       * syntax.texi (Syntax Basics): Rearrange the text for clarity.
+       Fix description of syntax table inheritance.
+       (Syntax Table Functions): Don't refer to internal contents of
+       syntax table, since that is not explained yet.  Copyedits.
+       (Standard Syntax Tables): Node deleted.
+       (Syntax Table Internals): Misc clarifications.  Improve table
+       formatting.
+
+       * keymaps.texi (Inheritance and Keymaps):
+       * text.texi (Sticky Properties): Tweak index entry.
+
 2012-07-28  Eli Zaretskii  <address@hidden>
 
        * nonascii.texi (Character Sets): Fix a typo.  (Bug#12062)

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-07-25 05:48:19 +0000
+++ b/doc/lispref/elisp.texi    2012-08-04 14:33:00 +0000
@@ -1241,7 +1241,6 @@
 * Motion and Syntax::       Moving over characters with certain syntaxes.
 * Parsing Expressions::     Parsing balanced expressions
                               using the syntax table.
-* Standard Syntax Tables::  Syntax tables used by various major modes.
 * Syntax Table Internals::  How syntax table information is stored.
 * Categories::              Another way of classifying character syntax.
 

=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi  2012-07-21 14:48:17 +0000
+++ b/doc/lispref/keymaps.texi  2012-08-04 14:33:00 +0000
@@ -371,7 +371,7 @@
 @node Inheritance and Keymaps
 @section Inheritance and Keymaps
 @cindex keymap inheritance
address@hidden inheriting a keymap's bindings
address@hidden inheritance, keymap
 
   A keymap can inherit the bindings of another keymap, which we call the
 @dfn{parent keymap}.  Such a keymap looks like this:

=== modified file 'doc/lispref/syntax.texi'
--- a/doc/lispref/syntax.texi   2012-05-27 01:34:14 +0000
+++ b/doc/lispref/syntax.texi   2012-08-04 14:33:00 +0000
@@ -23,7 +23,6 @@
 * Motion and Syntax::        Moving over characters with certain syntaxes.
 * Parsing Expressions::      Parsing balanced expressions
                                 using the syntax table.
-* Standard Syntax Tables::   Syntax tables used by various major modes.
 * Syntax Table Internals::   How syntax table information is stored.
 * Categories::               Another way of classifying character syntax.
 @end menu
@@ -31,43 +30,65 @@
 @node Syntax Basics
 @section Syntax Table Concepts
 
-  A syntax table is a char-table (@pxref{Char-Tables}).  The element at
-index @var{c} describes the character with code @var{c}.  The element's
-value should be a list that encodes the syntax of the character in
-question.
-
-  Syntax tables are used only for moving across text, not for the Emacs
-Lisp reader.  Emacs Lisp uses built-in syntactic rules when reading Lisp
-expressions, and these rules cannot be changed.  (Some Lisp systems
-provide ways to redefine the read syntax, but we decided to leave this
-feature out of Emacs Lisp for simplicity.)
-
-  Each buffer has its own major mode, and each major mode has its own
-idea of the syntactic class of various characters.  For example, in
-Lisp mode, the character @samp{;} begins a comment, but in C mode, it
-terminates a statement.  To support these variations, Emacs makes the
-syntax table local to each buffer.  Typically, each major mode has its
-own syntax table and installs that table in each buffer that uses that
-mode.  Changing this table alters the syntax in all those buffers as
-well as in any buffers subsequently put in that mode.  Occasionally
-several similar modes share one syntax table.  @xref{Example Major
-Modes}, for an example of how to set up a syntax table.
-
-A syntax table can inherit the data for some characters from the
-standard syntax table, while specifying other characters itself.  The
-``inherit'' syntax class means ``inherit this character's syntax from
-the standard syntax table''.  Just changing the standard syntax for a
-character affects all syntax tables that inherit from it.
+  A syntax table is a data structure which can be used to look up the
address@hidden class} and other syntactic properties of each character.
+Syntax tables are used by Lisp programs for scanning and moving across
+text.
+
+  Internally, a syntax table is a char-table (@pxref{Char-Tables}).
+The element at index @var{c} describes the character with code
address@hidden; its value is a cons cell which specifies the syntax of the
+character in question.  @xref{Syntax Table Internals}, for details.
+However, instead of using @code{aset} and @code{aref} to modify and
+inspect syntax table contents, you should usually use the higher-level
+functions @code{char-syntax} and @code{modify-syntax-entry}, which are
+described in @ref{Syntax Table Functions}.
 
 @defun syntax-table-p object
 This function returns @code{t} if @var{object} is a syntax table.
 @end defun
 
+  Each buffer has its own major mode, and each major mode has its own
+idea of the syntax class of various characters.  For example, in Lisp
+mode, the character @samp{;} begins a comment, but in C mode, it
+terminates a statement.  To support these variations, the syntax table
+is local to each buffer.  Typically, each major mode has its own
+syntax table, which it installs in all buffers that use that mode.
+For example, the variable @code{emacs-lisp-mode-syntax-table} holds
+the syntax table used by Emacs Lisp mode, and
address@hidden holds the syntax table used by C mode.
+Changing a major mode's syntax table alters the syntax in all of that
+mode's buffers, as well as in any buffers subsequently put in that
+mode.  Occasionally, several similar modes share one syntax table.
address@hidden Major Modes}, for an example of how to set up a syntax
+table.
+
address@hidden standard syntax table
address@hidden inheritance, syntax table
+  A syntax table can @dfn{inherit} from another syntax table, which is
+called its @dfn{parent syntax table}.  A syntax table can leave the
+syntax class of some characters unspecified, by giving them the
+``inherit'' syntax class; such a character then acquires the syntax
+class specified by the parent syntax table (@pxref{Syntax Class
+Table}).  Emacs defines a @dfn{standard syntax table}, which is the
+default parent syntax table, and is also the syntax table used by
+Fundamental mode.
+
address@hidden standard-syntax-table
+This function returns the standard syntax table, which is the syntax
+table used in Fundamental mode.
address@hidden defun
+
+  Syntax tables are not used by the Emacs Lisp reader, which has its
+own built-in syntactic rules which cannot be changed.  (Some Lisp
+systems provide ways to redefine the read syntax, but we decided to
+leave this feature out of Emacs Lisp for simplicity.)
+
 @node Syntax Descriptors
 @section Syntax Descriptors
 @cindex syntax class
 
-  The syntactic role of a character is called its @dfn{syntax class}.
+  The @dfn{syntax class} of a character describes its syntactic role.
 Each syntax table specifies the syntax class of each character.  There
 is no necessary relationship between the class of a character in one
 syntax table and its class in any other table.
@@ -81,21 +102,23 @@
 syntax, regardless of whether the @samp{\} character actually has that
 syntax in the current syntax table.
 @ifnottex
address@hidden Class Table}, for a list of syntax classes.
address@hidden Class Table}, for a list of syntax classes and their
+designator characters.
 @end ifnottex
 
 @cindex syntax descriptor
   A @dfn{syntax descriptor} is a Lisp string that describes the syntax
-classes and other syntactic properties of a character.  When you want
-to modify the syntax of a character, that is done by calling the
-function @code{modify-syntax-entry} and passing a syntax descriptor as
-one of its arguments (@pxref{Syntax Table Functions}).
+class and other syntactic properties of a character.  When you want to
+modify the syntax of a character, that is done by calling the function
address@hidden and passing a syntax descriptor as one of
+its arguments (@pxref{Syntax Table Functions}).
 
-  The first character in a syntax descriptor designates the syntax
-class.  The second character specifies a matching character (e.g.@: in
-Lisp, the matching character for @samp{(} is @samp{)}); if there is no
-matching character, put a space there.  Then come the characters for
-any desired flags.
+  The first character in a syntax descriptor must be a syntax class
+designator character.  The second character, if present, specifies a
+matching character (e.g.@: in Lisp, the matching character for
address@hidden(} is @samp{)}); a space specifies that there is no matching
+character.  Then come characters specifying additional syntax
+properties (@pxref{Syntax Flags}).
 
   If no matching character or flags are needed, only one character
 (specifying the syntax class) is sufficient.
@@ -348,7 +371,6 @@
 @end table
 
 @item
address@hidden Emacs 19 feature
 @samp{p} identifies an additional ``prefix character'' for Lisp syntax.
 These characters are treated as whitespace when they appear between
 expressions.  When they appear within an expression, they are handled
@@ -366,21 +388,20 @@
 altering syntax tables.
 
 @defun make-syntax-table &optional table
-This function creates a new syntax table, with all values initialized
-to @code{nil}.  If @var{table} is address@hidden, 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}.
+This function creates a new syntax table.  If @var{table} is
address@hidden, the parent of the new syntax table is @var{table};
+otherwise, the parent is the standard syntax table.
 
-Most major mode syntax tables are created in this way.
+In the new syntax table, all characters are initially given the
+``inherit'' (@samp{@@}) syntax class, i.e.@: their syntax is inherited
+from the parent table (@pxref{Syntax Class Table}).
 @end defun
 
 @defun copy-syntax-table &optional table
 This function constructs a copy of @var{table} and returns it.  If
address@hidden is not supplied (or is @code{nil}), it returns a copy of the
-standard syntax table.  Otherwise, an error is signaled if @var{table} is
-not a syntax table.
address@hidden is omitted or @code{nil}, it returns a copy of the
+standard syntax table.  Otherwise, an error is signaled if @var{table}
+is not a syntax table.
 @end defun
 
 @deffn Command modify-syntax-entry char syntax-descriptor  &optional table
@@ -393,11 +414,11 @@
 The syntax is changed only for @var{table}, which defaults to the
 current buffer's syntax table, and not in any other syntax table.
 
-The argument @var{syntax-descriptor} is a syntax descriptor for the
-desired syntax (i.e.@: a string beginning with a class designator
-character, and optionally containing a matching character and syntax
-flags).  An error is signaled if the first character is not one of the
-seventeen syntax class designators.  @xref{Syntax Descriptors}.
+The argument @var{syntax-descriptor} is a syntax descriptor, i.e.@: a
+string whose first character is a syntax class designator and whose
+second and subsequent characters optionally specify a matching
+character and syntax flags.  @xref{Syntax Descriptors}.  An error is
+signaled if @var{syntax-descriptor} is not a valid syntax descriptor.
 
 This function always returns @code{nil}.  The old syntax information in
 the table for this character is discarded.
@@ -438,38 +459,37 @@
 
 @defun char-syntax character
 This function returns the syntax class of @var{character}, represented
-by its mnemonic designator character.  This returns @emph{only} the
-class, not any matching parenthesis or flags.
-
-An error is signaled if @var{char} is not a character.
-
-The following examples apply to C mode.  The first example shows that
-the syntax class of space is whitespace (represented by a space).  The
-second example shows that the syntax of @samp{/} is punctuation.  This
-does not show the fact that it is also part of comment-start and -end
-sequences.  The third example shows that open parenthesis is in the class
-of open parentheses.  This does not show the fact that it has a matching
-character, @samp{)}.
+by its designator character (@pxref{Syntax Class Table}).  This
+returns @emph{only} the class, not its matching character or syntax
+flags.
+
+The following examples apply to C mode.  (We use @code{string} to make
+it easier to see the character returned by @code{char-syntax}.)
 
 @example
 @group
+;; Space characters have whitespace syntax class.
 (string (char-syntax ?\s))
      @result{} " "
 @end group
 
 @group
+;; Forward slash characters have punctuation syntax.  Note that this
+;; @code{char-syntax} call does not reveal that it is also part of
+;; comment-start and -end sequences.
 (string (char-syntax ?/))
      @result{} "."
 @end group
 
 @group
+;; Open parenthesis characters have open parenthesis syntax.  Note
+;; that this @code{char-syntax} call does not reveal that it has a
+;; matching character, @samp{)}.
 (string (char-syntax ?\())
      @result{} "("
 @end group
 @end example
 
-We use @code{string} to make it easier to see the character returned by
address@hidden
 @end defun
 
 @defun set-syntax-table table
@@ -905,135 +925,70 @@
 You can use @code{forward-comment} to move forward or backward over
 one comment or several comments.
 
address@hidden Standard Syntax Tables
address@hidden Some Standard Syntax Tables
-
-  Most of the major modes in Emacs have their own syntax tables.  Here
-are several of them:
-
address@hidden standard-syntax-table
-This function returns the standard syntax table, which is the syntax
-table used in Fundamental mode.
address@hidden defun
-
address@hidden text-mode-syntax-table
-The value of this variable is the syntax table used in Text mode.
address@hidden defvar
-
address@hidden c-mode-syntax-table
-The value of this variable is the syntax table for C-mode buffers.
address@hidden defvar
-
address@hidden emacs-lisp-mode-syntax-table
-The value of this variable is the syntax table used in Emacs Lisp mode
-by editing commands.  (It has no effect on the Lisp @code{read}
-function.)
address@hidden defvar
-
 @node Syntax Table Internals
 @section Syntax Table Internals
 @cindex syntax table internals
 
-  Lisp programs don't usually work with the elements directly; the
-Lisp-level syntax table functions usually work with syntax descriptors
-(@pxref{Syntax Descriptors}).  Nonetheless, here we document the
-internal format.  This format is used mostly when manipulating
-syntax properties.
-
-  Each element of a syntax table is a cons cell of the form
address@hidden(@var{syntax-code} . @var{matching-char})}.  The @sc{car},
address@hidden, is an integer that encodes the syntax class, and any
-flags.  The @sc{cdr}, @var{matching-char}, is address@hidden if
-a character to match was specified.
-
-  This table gives the value of @var{syntax-code} which corresponds
-to each syntactic type.
-
address@hidden @columnfractions .05 .3 .3 .31
address@hidden
address@hidden
address@hidden @i{Class}
address@hidden
address@hidden @i{Class}
address@hidden
address@hidden @i{Class}
address@hidden
address@hidden
-0 @ @  whitespace
address@hidden
-5 @ @  close parenthesis
address@hidden
-10 @ @  character quote
address@hidden
address@hidden
-1 @ @  punctuation
address@hidden
-6 @ @  expression prefix
address@hidden
-11 @ @  comment-start
address@hidden
address@hidden
-2 @ @  word
address@hidden
-7 @ @  string quote
address@hidden
-12 @ @  comment-end
address@hidden
address@hidden
-3 @ @  symbol
address@hidden
-8 @ @  paired delimiter
address@hidden
-13 @ @  inherit
address@hidden
address@hidden
-4 @ @  open parenthesis
address@hidden
-9 @ @  escape
address@hidden
-14 @ @  generic comment
address@hidden
address@hidden
-15 @  generic string
+  Syntax tables are implemented as char-tables (@pxref{Char-Tables}),
+but most Lisp programs don't work directly with their elements.
+Syntax tables do not store syntax data as syntax descriptors
+(@pxref{Syntax Descriptors}); they use an internal format, which is
+documented in this section.  This internal format can also be assigned
+as syntax properties (@pxref{Syntax Properties}).
+
address@hidden syntax code
+  Each entry in a syntax table is a cons cell of the form
address@hidden(@var{syntax-code} . @var{matching-char})}.  @var{syntax-code}
+is an integer that encodes the syntax class and syntax flags,
+according to the table below.  @var{matching-char}, if address@hidden,
+specifies a matching character (similar to the second character in a
+syntax descriptor).
+
address@hidden @columnfractions .2 .3 .2 .3
address@hidden
address@hidden code} @tab @i{Class} @tab @i{Syntax code} @tab @i{Class}
address@hidden
+0 @tab whitespace @tab 8 @tab paired delimiter
address@hidden
+1 @tab punctuation @tab 9 @tab escape
address@hidden
+2 @tab word @tab 10 @tab character quote
address@hidden
+3 @tab symbol @tab 11 @tab comment-start
address@hidden
+4 @tab open parenthesis @tab 12 @tab comment-end
address@hidden
+5 @tab close parenthesis @tab 13 @tab inherit
address@hidden
+6 @tab expression prefix @tab 14 @tab generic comment
address@hidden
+7 @tab string quote @tab 15 @tab generic string
 @end multitable
 
-  For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
-(41 is the character code for @samp{)}.)
address@hidden
+For example, in the standard syntax table, the entry for @samp{(} is
address@hidden(4 . 41)}.  (41 is the character code for @samp{)}.)
 
-  The flags are encoded in higher order bits, starting 16 bits from the
-least significant bit.  This table gives the power of two which
+  Syntax flags are encoded in higher order bits, starting 16 bits from
+the least significant bit.  This table gives the power of two which
 corresponds to each syntax flag.
 
address@hidden @columnfractions .05 .3 .3 .3
address@hidden
address@hidden
address@hidden @i{Flag}
address@hidden
address@hidden @i{Flag}
address@hidden
address@hidden @i{Flag}
address@hidden
address@hidden
address@hidden @ @  @code{(lsh 1 16)}
address@hidden
address@hidden @ @  @code{(lsh 1 19)}
address@hidden
address@hidden @ @  @code{(lsh 1 21)}
address@hidden
address@hidden
address@hidden @ @  @code{(lsh 1 17)}
address@hidden
address@hidden @ @  @code{(lsh 1 20)}
address@hidden
address@hidden @ @  @code{(lsh 1 22)}
address@hidden
address@hidden
address@hidden @ @  @code{(lsh 1 18)}
address@hidden @columnfractions .15 .3 .15 .3
address@hidden
address@hidden @tab @i{Flag} @tab @i{Prefix} @tab @i{Flag}
address@hidden
address@hidden @tab @code{(lsh 1 16)} @tab @samp{p} @tab @code{(lsh 1 20)}
address@hidden
address@hidden @tab @code{(lsh 1 17)} @tab @samp{b} @tab @code{(lsh 1 21)}
address@hidden
address@hidden @tab @code{(lsh 1 18)} @tab @samp{n} @tab @code{(lsh 1 22)}
address@hidden
address@hidden @tab @code{(lsh 1 19)}
 @end multitable
 
 @defun string-to-syntax @var{desc}
-This function returns the internal form corresponding to the syntax
-descriptor @var{desc}, a cons cell @code{(@var{syntax-code}
+Given a syntax descriptor @var{desc}, this function returns the
+corresponding internal form, a cons cell @code{(@var{syntax-code}
 . @var{matching-char})}.
 @end defun
 

=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi     2012-07-17 07:43:01 +0000
+++ b/doc/lispref/text.texi     2012-08-04 14:33:00 +0000
@@ -3382,7 +3382,7 @@
 @node Sticky Properties
 @subsection Stickiness of Text Properties
 @cindex sticky text properties
address@hidden inheritance of text properties
address@hidden inheritance, text property
 
   Self-inserting characters normally take on the same properties as the
 preceding character.  This is called @dfn{inheritance} of properties.

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-08-04 14:17:10 +0000
+++ b/src/ChangeLog     2012-08-04 14:33:00 +0000
@@ -1,3 +1,7 @@
+2012-08-04  Chong Yidong  <address@hidden>
+
+       * syntax.c (Fmodify_syntax_entry): Doc fix.
+
 2012-08-04  Eli Zaretskii  <address@hidden>
 
        Fix startup warnings about ../site-lisp on MS-Windows.  (Bug#11959)

=== modified file 'src/syntax.c'
--- a/src/syntax.c      2012-07-30 18:56:42 +0000
+++ b/src/syntax.c      2012-08-04 14:33:00 +0000
@@ -1009,7 +1009,7 @@
   "           string quote.         \\   escape.
   $           paired delimiter.     '   expression quote or prefix operator.
   <           comment starter.      >   comment ender.
-  /           character-quote.      @   inherit from `standard-syntax-table'.
+  /           character-quote.      @   inherit from parent table.
   |           generic string fence. !   generic comment fence.
 
 Only single-character comment start and end sequences are represented thus.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]