new repository

1 files changed, 58 insertions, 0 deletions

diff --git a/devdocs/elisp/search_002dbased-fontification.html b/devdocs/elisp/search_002dbased-fontification.html
new file mode 100644
index 00000000..b02b4a26
--- /dev/null
+++ b/devdocs/elisp/search_002dbased-fontification.html
@@ -0,0 +1,58 @@
+ <h4 class="subsection">Search-based Fontification</h4> <p>The variable which directly controls search-based fontification is <code>font-lock-keywords</code>, which is typically specified via the <var>keywords</var> element in <code>font-lock-defaults</code>. </p> <dl> <dt id="font-lock-keywords">Variable: <strong>font-lock-keywords</strong>
+</dt> <dd><p>The value of this variable is a list of the keywords to highlight. Lisp programs should not set this variable directly. Normally, the value is automatically set by Font Lock mode, using the <var>keywords</var> element in <code>font-lock-defaults</code>. The value can also be altered using the functions <code>font-lock-add-keywords</code> and <code>font-lock-remove-keywords</code> (see <a href="customizing-keywords">Customizing Keywords</a>). </p></dd>
+</dl> <p>Each element of <code>font-lock-keywords</code> specifies how to find certain cases of text, and how to highlight those cases. Font Lock mode processes the elements of <code>font-lock-keywords</code> one by one, and for each element, it finds and handles all matches. Ordinarily, once part of the text has been fontified already, this cannot be overridden by a subsequent match in the same text; but you can specify different behavior using the <var>override</var> element of a <var>subexp-highlighter</var>. </p> <p>Each element of <code>font-lock-keywords</code> should have one of these forms: </p> <dl compact> <dt><code><var>regexp</var></code></dt> <dd>
+<p>Highlight all matches for <var>regexp</var> using <code>font-lock-keyword-face</code>. For example, </p> <div class="example"> <pre class="example">;; <span class="roman">Highlight occurrences of the word ‘<samp>foo</samp>’</span>
+;; <span class="roman">using <code>font-lock-keyword-face</code>.</span>
+"\\&lt;foo\\&gt;"
+</pre>
+</div> <p>Be careful when composing these regular expressions; a poorly written pattern can dramatically slow things down! The function <code>regexp-opt</code> (see <a href="regexp-functions">Regexp Functions</a>) is useful for calculating optimal regular expressions to match several keywords. </p> </dd> <dt><code><var>function</var></code></dt> <dd>
+<p>Find text by calling <var>function</var>, and highlight the matches it finds using <code>font-lock-keyword-face</code>. </p> <p>When <var>function</var> is called, it receives one argument, the limit of the search; it should begin searching at point, and not search beyond the limit. It should return non-<code>nil</code> if it succeeds, and set the match data to describe the match that was found. Returning <code>nil</code> indicates failure of the search. </p> <p>Fontification will call <var>function</var> repeatedly with the same limit, and with point where the previous invocation left it, until <var>function</var> fails. On failure, <var>function</var> need not reset point in any particular way. </p> </dd> <dt><code>(<var>matcher</var> . <var>subexp</var>)</code></dt> <dd>
+<p>In this kind of element, <var>matcher</var> is either a regular expression or a function, as described above. The <small>CDR</small>, <var>subexp</var>, specifies which subexpression of <var>matcher</var> should be highlighted (instead of the entire text that <var>matcher</var> matched). </p> <div class="example"> <pre class="example">;; <span class="roman">Highlight the ‘<samp>bar</samp>’ in each occurrence of ‘<samp>fubar</samp>’,</span>
+;; <span class="roman">using <code>font-lock-keyword-face</code>.</span>
+("fu\\(bar\\)" . 1)
+</pre>
+</div> </dd> <dt><code>(<var>matcher</var> . <var>facespec</var>)</code></dt> <dd>
+<p>In this kind of element, <var>facespec</var> is an expression whose value specifies the face to use for highlighting. In the simplest case, <var>facespec</var> is a Lisp variable (a symbol) whose value is a face name. </p> <div class="example"> <pre class="example">;; <span class="roman">Highlight occurrences of ‘<samp>fubar</samp>’,</span>
+;; <span class="roman">using the face which is the value of <code>fubar-face</code>.</span>
+("fubar" . fubar-face)
+</pre>
+</div> <p>However, <var>facespec</var> can also evaluate to a list of this form: </p> <div class="example"> <pre class="example">(<var>subexp</var>
+(face <var>face</var> <var>prop1</var> <var>val1</var> <var>prop2</var> <var>val2</var>…))
+</pre>
+</div> <p>to specify the face <var>face</var> and various additional text properties to put on the text that matches. If you do this, be sure to add the other text property names that you set in this way to the value of <code>font-lock-extra-managed-props</code> so that the properties will also be cleared out when they are no longer appropriate. Alternatively, you can set the variable <code>font-lock-unfontify-region-function</code> to a function that clears these properties. See <a href="other-font-lock-variables">Other Font Lock Variables</a>. </p> </dd> <dt><code>(<var>matcher</var> . <var>subexp-highlighter</var>)</code></dt> <dd>
+<p>In this kind of element, <var>subexp-highlighter</var> is a list which specifies how to highlight matches found by <var>matcher</var>. It has the form: </p> <div class="example"> <pre class="example">(<var>subexp</var> <var>facespec</var> [<var>override</var> [<var>laxmatch</var>]])
+</pre>
+</div> <p>The <small>CAR</small>, <var>subexp</var>, is an integer specifying which subexpression of the match to fontify (0 means the entire matching text). The second subelement, <var>facespec</var>, is an expression whose value specifies the face, as described above. </p> <p>The last two values in <var>subexp-highlighter</var>, <var>override</var> and <var>laxmatch</var>, are optional flags. If <var>override</var> is <code>t</code>, this element can override existing fontification made by previous elements of <code>font-lock-keywords</code>. If it is <code>keep</code>, then each character is fontified if it has not been fontified already by some other element. If it is <code>prepend</code>, the face specified by <var>facespec</var> is added to the beginning of the <code>font-lock-face</code> property. If it is <code>append</code>, the face is added to the end of the <code>font-lock-face</code> property. </p> <p>If <var>laxmatch</var> is non-<code>nil</code>, it means there should be no error if there is no subexpression numbered <var>subexp</var> in <var>matcher</var>. Obviously, fontification of the subexpression numbered <var>subexp</var> will not occur. However, fontification of other subexpressions (and other regexps) will continue. If <var>laxmatch</var> is <code>nil</code>, and the specified subexpression is missing, then an error is signaled which terminates search-based fontification. </p> <p>Here are some examples of elements of this kind, and what they do: </p> <div class="example"> <pre class="example">;; <span class="roman">Highlight occurrences of either ‘<samp>foo</samp>’ or ‘<samp>bar</samp>’, using</span>
+;; <span class="roman"><code>foo-bar-face</code>, even if they have already been highlighted.</span>
+;; <span class="roman"><code>foo-bar-face</code> should be a variable whose value is a face.</span>
+("foo\\|bar" 0 foo-bar-face t)
+
+;; <span class="roman">Highlight the first subexpression within each occurrence</span>
+;; <span class="roman">that the function <code>fubar-match</code> finds,</span>
+;; <span class="roman">using the face which is the value of <code>fubar-face</code>.</span>
+(fubar-match 1 fubar-face)
+</pre>
+</div> </dd> <dt><code>(<var>matcher</var> . <var>anchored-highlighter</var>)</code></dt> <dd>
+<p>In this kind of element, <var>anchored-highlighter</var> specifies how to highlight text that follows a match found by <var>matcher</var>. So a match found by <var>matcher</var> acts as the anchor for further searches specified by <var>anchored-highlighter</var>. <var>anchored-highlighter</var> is a list of the following form: </p> <div class="example"> <pre class="example">(<var>anchored-matcher</var> <var>pre-form</var> <var>post-form</var>
+                        <var>subexp-highlighters</var>…)
+</pre>
+</div> <p>Here, <var>anchored-matcher</var>, like <var>matcher</var>, is either a regular expression or a function. After a match of <var>matcher</var> is found, point is at the end of the match. Now, Font Lock evaluates the form <var>pre-form</var>. Then it searches for matches of <var>anchored-matcher</var> and uses <var>subexp-highlighters</var> to highlight these. A <var>subexp-highlighter</var> is as described above. Finally, Font Lock evaluates <var>post-form</var>. </p> <p>The forms <var>pre-form</var> and <var>post-form</var> can be used to initialize before, and cleanup after, <var>anchored-matcher</var> is used. Typically, <var>pre-form</var> is used to move point to some position relative to the match of <var>matcher</var>, before starting with <var>anchored-matcher</var>. <var>post-form</var> might be used to move back, before resuming with <var>matcher</var>. </p> <p>After Font Lock evaluates <var>pre-form</var>, it does not search for <var>anchored-matcher</var> beyond the end of the line. However, if <var>pre-form</var> returns a buffer position that is greater than the position of point after <var>pre-form</var> is evaluated, then the position returned by <var>pre-form</var> is used as the limit of the search instead. It is generally a bad idea to return a position greater than the end of the line; in other words, the <var>anchored-matcher</var> search should not span lines. </p> <p>For example, </p> <div class="example"> <pre class="example">;; <span class="roman">Highlight occurrences of the word ‘<samp>item</samp>’ following</span>
+;; <span class="roman">an occurrence of the word ‘<samp>anchor</samp>’ (on the same line)</span>
+;; <span class="roman">in the value of <code>item-face</code>.</span>
+("\\&lt;anchor\\&gt;" "\\&lt;item\\&gt;" nil nil (0 item-face))
+</pre>
+</div> <p>Here, <var>pre-form</var> and <var>post-form</var> are <code>nil</code>. Therefore searching for ‘<samp>item</samp>’ starts at the end of the match of ‘<samp>anchor</samp>’, and searching for subsequent instances of ‘<samp>anchor</samp>’ resumes from where searching for ‘<samp>item</samp>’ concluded. </p> </dd> <dt><code>(<var>matcher</var> <var>highlighters</var>…)</code></dt> <dd>
+<p>This sort of element specifies several <var>highlighter</var> lists for a single <var>matcher</var>. A <var>highlighter</var> list can be of the type <var>subexp-highlighter</var> or <var>anchored-highlighter</var> as described above. </p> <p>For example, </p> <div class="example"> <pre class="example">;; <span class="roman">Highlight occurrences of the word ‘<samp>anchor</samp>’ in the value</span>
+;; <span class="roman">of <code>anchor-face</code>, and subsequent occurrences of the word</span>
+;; <span class="roman">‘<samp>item</samp>’ (on the same line) in the value of <code>item-face</code>.</span>
+("\\&lt;anchor\\&gt;" (0 anchor-face)
+                ("\\&lt;item\\&gt;" nil nil (0 item-face)))
+</pre>
+</div> </dd> <dt><code>(eval . <var>form</var>)</code></dt> <dd><p>Here <var>form</var> is an expression to be evaluated the first time this value of <code>font-lock-keywords</code> is used in a buffer. Its value should have one of the forms described in this table. </p></dd> </dl> <p><strong>Warning:</strong> Do not design an element of <code>font-lock-keywords</code> to match text which spans lines; this does not work reliably. For details, see <a href="multiline-font-lock">Multiline Font Lock</a>. </p> <p>You can use <var>case-fold</var> in <code>font-lock-defaults</code> to specify the value of <code>font-lock-keywords-case-fold-search</code> which says whether search-based fontification should be case-insensitive. </p> <dl> <dt id="font-lock-keywords-case-fold-search">Variable: <strong>font-lock-keywords-case-fold-search</strong>
+</dt> <dd><p>Non-<code>nil</code> means that regular expression matching for the sake of <code>font-lock-keywords</code> should be case-insensitive. </p></dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Search_002dbased-Fontification.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Search_002dbased-Fontification.html</a>
+  </p>
+</div>