[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] emacs-25 925af7e 27/64: Fill the doc string of font-lock-k
From: |
Lars Ingebrigtsen |
Subject: |
[Emacs-diffs] emacs-25 925af7e 27/64: Fill the doc string of font-lock-keywords |
Date: |
Sun, 01 May 2016 18:18:40 +0000 |
branch: emacs-25
commit 925af7e0bec15151149a2132d203753ad7610182
Author: Lars Ingebrigtsen <address@hidden>
Commit: Lars Ingebrigtsen <address@hidden>
Fill the doc string of font-lock-keywords
* lisp/font-lock.el (font-lock-keywords): Fill the lines and
reorganise some explanations (bug#21427).
(cherry picked from commit c05716d3a26ea7518b89eacfccaf70c9d0731df7)
---
lisp/font-lock.el | 174 +++++++++++++++++++++++++++++------------------------
1 file changed, 97 insertions(+), 77 deletions(-)
diff --git a/lisp/font-lock.el b/lisp/font-lock.el
index 634073c..8ee9f69 100644
--- a/lisp/font-lock.el
+++ b/lisp/font-lock.el
@@ -364,105 +364,125 @@ Each element in a user-level keywords list should have
one of these forms:
(MATCHER HIGHLIGHT ...)
(eval . FORM)
-where MATCHER can be either the regexp to search for, or the function name to
-call to make the search (called with one argument, the limit of the search;
-it should return non-nil, move point, and set `match-data' appropriately if
-it succeeds; like `re-search-forward' would).
-MATCHER regexps can be generated via the function `regexp-opt'.
-
-FORM is an expression, whose value should be a keyword element, evaluated when
-the keyword is (first) used in a buffer. This feature can be used to provide a
-keyword that can only be generated when Font Lock mode is actually turned on.
+where MATCHER can be either the regexp to search for, or the
+function name to call to make the search (called with one
+argument, the limit of the search; it should return non-nil, move
+point, and set `match-data' appropriately if it succeeds; like
+`re-search-forward' would). MATCHER regexps can be generated via
+the function `regexp-opt'.
+
+FORM is an expression, whose value should be a keyword element,
+evaluated when the keyword is (first) used in a buffer. This
+feature can be used to provide a keyword that can only be
+generated when Font Lock mode is actually turned on.
HIGHLIGHT should be either MATCH-HIGHLIGHT or MATCH-ANCHORED.
-For highlighting single items, for example each instance of the word \"foo\",
-typically only MATCH-HIGHLIGHT is required.
-However, if an item or (typically) items are to be highlighted following the
-instance of another item (the anchor), for example each instance of the
-word \"bar\" following the word \"anchor\" then MATCH-ANCHORED may be required.
+For highlighting single items, for example each instance of the
+word \"foo\", typically only MATCH-HIGHLIGHT is required.
+However, if an item or (typically) items are to be highlighted
+following the instance of another item (the anchor), for example
+each instance of the word \"bar\" following the word \"anchor\"
+then MATCH-ANCHORED may be required.
MATCH-HIGHLIGHT should be of the form:
(SUBEXP FACENAME [OVERRIDE [LAXMATCH]])
-SUBEXP is the number of the subexpression of MATCHER to be highlighted.
+SUBEXP is the number of the subexpression of MATCHER to be
+highlighted.
FACENAME is an expression whose value is the face name to use.
-Instead of a face, FACENAME can evaluate to a property list
-of the form (face FACE PROP1 VAL1 PROP2 VAL2 ...)
-in which case all the listed text-properties will be set rather than
-just FACE. In such a case, you will most likely want to put those
-properties in `font-lock-extra-managed-props' or to override
+Instead of a face, FACENAME can evaluate to a property list of
+the form (face FACE PROP1 VAL1 PROP2 VAL2 ...) in which case all
+the listed text-properties will be set rather than just FACE. In
+such a case, you will most likely want to put those properties in
+`font-lock-extra-managed-props' or to override
`font-lock-unfontify-region-function'.
-OVERRIDE and LAXMATCH are flags. If OVERRIDE is t, existing fontification can
-be overwritten. If `keep', only parts not already fontified are highlighted.
-If `prepend' or `append', existing fontification is merged with the new, in
-which the new or existing fontification, respectively, takes precedence.
-If LAXMATCH is non-nil, that means don't signal an error if there is
+OVERRIDE and LAXMATCH are flags. If OVERRIDE is t, existing
+fontification can be overwritten. If `keep', only parts not
+already fontified are highlighted. If `prepend' or `append',
+existing fontification is merged with the new, in which the new
+or existing fontification, respectively, takes precedence. If
+LAXMATCH is non-nil, that means don't signal an error if there is
no match for SUBEXP in MATCHER.
-For example, an element of the form highlights (if not already highlighted):
+For example, an element of the form highlights (if not already
+highlighted):
+
+ \"\\\\\\=<foo\\\\\\=>\"
+ Discrete occurrences of \"foo\" in the value of the variable
+ `font-lock-keyword-face'.
+
+ (\"fu\\\\(bar\\\\)\" . 1)
+ Substring \"bar\" within all occurrences of \"fubar\" in the
+ value of `font-lock-keyword-face'.
+
+ (\"fubar\" . fubar-face)
+ Occurrences of \"fubar\" in the value of `fubar-face'.
- \"\\\\\\=<foo\\\\\\=>\" discrete occurrences of \"foo\" in the
value of the
- variable `font-lock-keyword-face'.
- (\"fu\\\\(bar\\\\)\" . 1) substring \"bar\" within all occurrences of
\"fubar\" in
- the value of `font-lock-keyword-face'.
- (\"fubar\" . fubar-face) Occurrences of \"fubar\" in the value of
`fubar-face'.
(\"foo\\\\|bar\" 0 foo-bar-face t)
- occurrences of either \"foo\" or \"bar\" in the value
- of `foo-bar-face', even if already highlighted.
+ Occurrences of either \"foo\" or \"bar\" in the value of
+ `foo-bar-face', even if already highlighted.
+
(fubar-match 1 fubar-face)
- the first subexpression within all occurrences of
- whatever the function `fubar-match' finds and matches
- in the value of `fubar-face'.
+ The first subexpression within all occurrences of whatever the
+ function `fubar-match' finds and matches in the value of
+ `fubar-face'.
MATCH-ANCHORED should be of the form:
(MATCHER PRE-MATCH-FORM POST-MATCH-FORM MATCH-HIGHLIGHT ...)
-where MATCHER is a regexp to search for or the function name to call to make
-the search, as for MATCH-HIGHLIGHT above, but with one exception; see below.
-PRE-MATCH-FORM and POST-MATCH-FORM are evaluated before the first, and after
-the last, instance MATCH-ANCHORED's MATCHER is used. Therefore they can be
-used to initialize before, and cleanup after, MATCHER is used. Typically,
-PRE-MATCH-FORM is used to move to some position relative to the original
-MATCHER, before starting with MATCH-ANCHORED's MATCHER. POST-MATCH-FORM might
-be used to move back, before resuming with MATCH-ANCHORED's parent's MATCHER.
-
-For example, an element of the form highlights (if not already highlighted):
-
- (\"\\\\\\=<anchor\\\\\\=>\" (0 anchor-face) (\"\\\\\\=<item\\\\\\=>\" nil nil
(0 item-face)))
-
- discrete occurrences of \"anchor\" in the value of `anchor-face', and
subsequent
- discrete occurrences of \"item\" (on the same line) in the value of
`item-face'.
- (Here PRE-MATCH-FORM and POST-MATCH-FORM are nil. Therefore \"item\" is
- initially searched for starting from the end of the match of \"anchor\", and
- searching for subsequent instances of \"anchor\" resumes from where searching
- for \"item\" concluded.)
-
-The above-mentioned exception is as follows. The limit of the MATCHER search
-defaults to the end of the line after PRE-MATCH-FORM is evaluated.
-However, if PRE-MATCH-FORM returns a position greater than the position after
-PRE-MATCH-FORM is evaluated, that position is used as the limit of the search.
-It is generally a bad idea to return a position greater than the end of the
-line, i.e., cause the MATCHER search to span lines.
-
-These regular expressions can match text which spans lines, although
-it is better to avoid it if possible since updating them while editing
-text is slower, and it is not guaranteed to be always correct when using
-support modes like jit-lock or lazy-lock.
-
-This variable is set by major modes via the variable `font-lock-defaults'.
-Be careful when composing regexps for this list; a poorly written pattern can
-dramatically slow things down!
-
-A compiled keywords list starts with t. It is produced internally
-by `font-lock-compile-keywords' from a user-level keywords list.
-Its second element is the user-level keywords list that was
-compiled. The remaining elements have the same form as
-user-level keywords, but normally their values have been
+where MATCHER is a regexp to search for or the function name to
+call to make the search, as for MATCH-HIGHLIGHT above, but with
+one exception; see below. PRE-MATCH-FORM and POST-MATCH-FORM are
+evaluated before the first, and after the last, instance
+MATCH-ANCHORED's MATCHER is used. Therefore they can be used to
+initialize before, and cleanup after, MATCHER is used.
+Typically, PRE-MATCH-FORM is used to move to some position
+relative to the original MATCHER, before starting with
+MATCH-ANCHORED's MATCHER. POST-MATCH-FORM might be used to move
+back, before resuming with MATCH-ANCHORED's parent's MATCHER.
+
+For example, an element of the form highlights (if not already
+highlighted):
+
+ (\"\\\\\\=<anchor\\\\\\=>\" (0 anchor-face)
+ (\"\\\\\\=<item\\\\\\=>\" nil nil (0 item-face)))
+
+ Discrete occurrences of \"anchor\" in the value of
+ `anchor-face', and subsequent discrete occurrences of
+ \"item\" (on the same line) in the value of `item-face'.
+ (Here PRE-MATCH-FORM and POST-MATCH-FORM are nil. Therefore
+ \"item\" is initially searched for starting from the end of the
+ match of \"anchor\", and searching for subsequent instances of
+ \"anchor\" resumes from where searching for \"item\" concluded.)
+
+The above-mentioned exception is as follows. The limit of the
+MATCHER search defaults to the end of the line after
+PRE-MATCH-FORM is evaluated. However, if PRE-MATCH-FORM returns
+a position greater than the position after PRE-MATCH-FORM is
+evaluated, that position is used as the limit of the search. It
+is generally a bad idea to return a position greater than the end
+of the line, i.e., cause the MATCHER search to span lines.
+
+These regular expressions can match text which spans lines,
+although it is better to avoid it if possible since updating them
+while editing text is slower, and it is not guaranteed to be
+always correct when using support modes like jit-lock or
+lazy-lock.
+
+This variable is set by major modes via the variable
+`font-lock-defaults'. Be careful when composing regexps for this
+list; a poorly written pattern can dramatically slow things down!
+
+A compiled keywords list starts with t. It is produced
+internally by `font-lock-compile-keywords' from a user-level
+keywords list. Its second element is the user-level keywords
+list that was compiled. The remaining elements have the same
+form as user-level keywords, but normally their values have been
optimized.")
(defvar font-lock-keywords-alist nil
- [Emacs-diffs] emacs-25 350792e 62/64: global-eldoc-mode doc fix, (continued)
- [Emacs-diffs] emacs-25 350792e 62/64: global-eldoc-mode doc fix, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 6b39501 55/64: Mention with-silent-modifications in the lispref manual, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 69f7940 63/64: cua-prefix-override-inhibit-delay doc fix, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 ad5572b 35/64: Fix custom types for cursor-in-non-selected-windows, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 8aa4147 64/64: tramp.texi: Revert last change due to backward compatibility, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 619f1ed 29/64: Move doc of backup-directory-alist to the Backup node, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 c3b3b90 61/64: normal-top-level-add-subdirs-to-load-path doc fix, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 2ef780f 34/64: Doc clarification to mwheel-scroll, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 1378680 31/64: Have the doc strings of `load-path' and `require' mention each other, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 ed8474e 33/64: Clarify the doc of eval-expression-print-format, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 925af7e 27/64: Fill the doc string of font-lock-keywords,
Lars Ingebrigtsen <=
- [Emacs-diffs] emacs-25 6d8c2d0 49/64: custom-buffer-style doc fix, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 3cbc1e3 07/64: Change all occurrences of "Mouse-[0-9]" to "mouse-[0-9]", Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 25b4cf3 56/64: Describe WHEN in all the define-obsolete- macros, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 9f27bcf 60/64: isearch-search-fun-function doc tweak, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 3bc26a7 53/64: clear-visited-file-modtime doc string fix, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 afb2257 46/64: completion-table-with-predicate doc string fix, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 d1ab001 58/64: Fmarker_position doc string clarification, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 ef32be6 48/64: Rearrange the doc of query-replace slightly, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 f3f4502 45/64: Fill the completion-table-with-predicate doc string, Lars Ingebrigtsen, 2016/05/01
- [Emacs-diffs] emacs-25 9722ae1 54/64: with-silent-modifications doc clarification, Lars Ingebrigtsen, 2016/05/01