From: Lars Ingebrigtsen Date: Sat, 30 Apr 2016 14:08:07 +0000 (+0200) Subject: Fill the doc string of font-lock-keywords X-Git-Tag: emacs-25.0.94~92 X-Git-Url: https://code.delx.au/gnu-emacs/commitdiff_plain/925af7e0bec15151149a2132d203753ad7610182 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) --- diff --git a/lisp/font-lock.el b/lisp/font-lock.el index 634073c286..8ee9f69fc1 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): + + \"\\\\\\=\" + 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'. - \"\\\\\\=\" 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): - - (\"\\\\\\=\" (0 anchor-face) (\"\\\\\\=\" 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): + + (\"\\\\\\=\" (0 anchor-face) + (\"\\\\\\=\" 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