X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/0ad8cce8a4ff36fd03c0a4994a6fd8d15d3ec5bd..71d5a208a41e0982a9565d8cc215bd110fcac864:/lispref/modes.texi

diff --git a/lispref/modes.texi b/lispref/modes.texi
index 0668e04c17..d92ea309ed 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -26,6 +26,8 @@ user.  For related topics such as keymaps and syntax tables, see
 * Imenu::              How a mode can provide a menu
                          of definitions in the buffer.
 * Font Lock Mode::     How modes can highlight text according to syntax.
+* Desktop Save Mode::  How modes can have buffer state saved between
+                         Emacs sessions.
 * Hooks::              How to use hooks; how to write code that provides hooks.
 @end menu
 
@@ -203,7 +205,7 @@ a newline.  The command to insert a newline and then indent is
 @kbd{C-j}.  Please keep this distinction uniform for all major modes.
 
 @item
-Major modes should not alter options that are primary a matter of user
+Major modes should not alter options that are primarily a matter of user
 preference, such as whether Auto-Fill mode is enabled.  Leave this to
 each user to decide.  However, a major mode should customize other
 variables so that Auto-Fill mode will work usefully @emph{if} the user
@@ -423,7 +425,7 @@ correspondingly more complicated.  Here are excerpts from
 @group
       ;; @r{Set syntax of chars up to 0 to class of chars that are}
       ;;   @r{part of symbol names but not words.}
-      ;;   @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
+      ;;   @r{(The number 0 is @code{48} in the @acronym{ASCII} character set.)}
       (while (< i ?0)
         (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
         (setq i (1+ i)))
@@ -1452,11 +1454,12 @@ enabled separately in each buffer.
 @end defvar
 
 @defvar global-mode-string
-This variable holds a mode-line spec that appears in the mode line by
-default, just after the buffer name.  The command @code{display-time}
+This variable holds a mode-line spec that, by default, appears in the
+mode line just after the @code{which-func-mode} minor mode if set,
+else after @code{mode-line-modes}.  The command @code{display-time}
 sets @code{global-mode-string} to refer to the variable
-@code{display-time-string}, which holds a string containing the time and
-load information.
+@code{display-time-string}, which holds a string containing the time
+and load information.
 
 The @samp{%M} construct substitutes the value of
 @code{global-mode-string}, but that is obsolete, since the variable is
@@ -1998,7 +2001,7 @@ Find text by calling @var{function}, and highlight the matches
 it finds using @code{font-lock-keyword-face}.
 
 When @var{function} is called, it receives one argument, the limit of
-the search; it should searching at point, and not search beyond the
+the search; it should begin searching at point, and not search beyond the
 limit.  It should return non-@code{nil} if it succeeds, and set the
 match data to describe the match that was found.  Returning @code{nil}
 indicates failure of the search.
@@ -2024,9 +2027,10 @@ If you use @code{regexp-opt} to produce the regular expression
 @var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
 of Regexps}) to calculate the value for @var{match}.
 
-@item (@var{matcher} . @var{facename})
-In this kind of element, @var{facename} is an expression whose value
-specifies the face name to use for highlighting.
+@item (@var{matcher} . @var{facespec})
+In this kind of element, @var{facespec} is an object which specifies
+the face variable to use for highlighting.  In the simplest case, it
+is a Lisp variable (a symbol), whose value should be a face name.
 
 @example
 ;; @r{Highlight occurrences of @samp{fubar},}
@@ -2034,8 +2038,7 @@ specifies the face name to use for highlighting.
 ("fubar" . fubar-face)
 @end example
 
-The value of @var{facename} is usually a face name (a symbol), but it
-can also be a list of the form
+However, @var{facespec} can also be a list of the form
 
 @example
 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
@@ -2053,21 +2056,21 @@ which specifies how to highlight matches found by @var{matcher}.
 It has the form
 
 @example
-(@var{subexp} @var{facename} @var{override} @var{laxmatch})
+(@var{subexp} @var{facespec} @var{override} @var{laxmatch})
 @end example
 
 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
 of the match to fontify (0 means the entire matching text).  The second
-subelement, @var{facename}, specifies the face, as described above.
+subelement, @var{facespec}, specifies the face, as described above.
 
 The last two values in @var{highlighter}, @var{override} and
 @var{laxmatch}, are flags.  If @var{override} is @code{t}, this
 element can override existing fontification made by previous elements
 of @code{font-lock-keywords}.  If it is @code{keep}, then each
 character is fontified if it has not been fontified already by some
-other element.  If it is @code{prepend}, the face @var{facename} is
-added to the beginning of the @code{font-lock-face} property.  If it
-is @code{append}, the face @var{facename} is added to the end of the
+other element.  If it is @code{prepend}, the face specified by
+@var{facespec} is added to the beginning of the @code{font-lock-face}
+property.  If it is @code{append}, the face is added to the end of the
 @code{font-lock-face} property.
 
 If @var{laxmatch} is non-@code{nil}, it means there should be no error
@@ -2161,7 +2164,11 @@ Its value should have one of the forms described in this table.
 to match text which spans lines; this does not work reliably.  While
 @code{font-lock-fontify-buffer} handles multi-line patterns correctly,
 updating when you edit the buffer does not, since it considers text one
-line at a time.
+line at a time.  If you have patterns that typically only span one
+line but can occasionally span two or three, such as
+@samp{<title>...</title>}, you can ask font-lock to be more careful by
+setting @code{font-lock-multiline} to @code{t}.  But it still will not
+work in all cases.
 
 @node Other Font Lock Variables
 @subsection Other Font Lock Variables
@@ -2227,10 +2234,24 @@ textual modes.
 Additional properties (other than @code{font-lock-face}) that are
 being managed by Font Lock mode.  Font Lock mode normally manages only
 the @code{font-lock-face} property; if you want it to manage others as
-well, you must specify them in a @var{facename} in
+well, you must specify them in a @var{facespec} in
 @code{font-lock-keywords} as well as adding them to this list.
 @end defvar
 
+@defvar font-lock-syntactic-face-function
+A function to determine which face to use for a given syntactic
+element (a string or a comment).  The function is called with one
+argument, the parse state at point returned by
+@code{parse-partial-sexp}, and should return a face.  The default
+value returns @code{font-lock-comment-face} for comments and
+@code{font-lock-string-face} for strings.
+
+This can be used to highlighting different kinds of strings or
+comments differently.  It is also sometimes abused together with
+@code{font-lock-syntactic-keywords} to highlight elements that span
+multiple lines, but this is too obscure to document in this manual.
+@end defvar
+
 @node Levels of Font Lock
 @subsection Levels of Font Lock
 
@@ -2408,6 +2429,59 @@ strings.
 
 @end defvar
 
+@node Desktop Save Mode
+@section Desktop Save Mode
+@cindex desktop save mode
+
+@dfn{Desktop Save Mode} is a feature to save the state of Emacs from
+one session to another.  The user-level commands for using Desktop
+Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs
+Sessions,,, emacs, the GNU Emacs Manual}).  Modes whose buffers visit
+a file, don't have to do anything to use this feature.
+
+For buffers not visiting a file to have their state saved, the major
+mode must bind the buffer local variable @code{desktop-save-buffer} to
+a non-nil value.
+
+@defvar desktop-save-buffer
+If this buffer-local variable is non-@code{nil}, the buffer will have
+its state saved in the desktop file at desktop save.  If the value is
+a function, it is called at desktop save with argument
+@var{desktop-dirname}, and its value is saved in the desktop file along
+with the state of the buffer for which it was called.  When file names
+are returned as part of the auxiliary information, they should be
+formatted using the call
+
+@example
+(desktop-file-name @var{file-name} @var{desktop-dirname})
+@end example
+
+@end defvar
+
+For buffers not visiting a file to be restored, the major mode must
+define a function to do the job, and that function must be listed in
+the alist @code{desktop-buffer-mode-handlers}.
+
+@defvar desktop-buffer-mode-handlers
+Alist with elements
+
+@example
+(@var{major-mode} . @var{restore-buffer-function})
+@end example
+
+The function @var{restore-buffer-function} will be called with
+argument list
+
+@example
+(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc})
+@end example
+
+and it should return the restored buffer.
+Here @var{desktop-buffer-misc} is the value returned by the function
+optionally bound to @code{desktop-save-buffer}.
+
+@end defvar
+
 @node Hooks
 @section Hooks
 @cindex hooks