new repository

1 files changed, 23 insertions, 0 deletions

diff --git a/devdocs/elisp/multiline-font-lock.html b/devdocs/elisp/multiline-font-lock.html
new file mode 100644
index 00000000..a4ec6888
--- /dev/null
+++ b/devdocs/elisp/multiline-font-lock.html
@@ -0,0 +1,23 @@
+ <h4 class="subsection">Multiline Font Lock Constructs</h4>  <p>Normally, elements of <code>font-lock-keywords</code> should not match across multiple lines; that doesn’t work reliably, because Font Lock usually scans just part of the buffer, and it can miss a multi-line construct that crosses the line boundary where the scan starts. (The scan normally starts at the beginning of a line.) </p> <p>Making elements that match multiline constructs work properly has two aspects: correct <em>identification</em> and correct <em>rehighlighting</em>. The first means that Font Lock finds all multiline constructs. The second means that Font Lock will correctly rehighlight all the relevant text when a multiline construct is changed—for example, if some of the text that was previously part of a multiline construct ceases to be part of it. The two aspects are closely related, and often getting one of them to work will appear to make the other also work. However, for reliable results you must attend explicitly to both aspects. </p> <p>There are three ways to ensure correct identification of multiline constructs: </p> <ul> <li> Add a function to <code>font-lock-extend-region-functions</code> that does the <em>identification</em> and extends the scan so that the scanned text never starts or ends in the middle of a multiline construct. </li>
+<li> Use the <code>font-lock-fontify-region-function</code> hook similarly to extend the scan so that the scanned text never starts or ends in the middle of a multiline construct. </li>
+<li> Somehow identify the multiline construct right when it gets inserted into the buffer (or at any point after that but before font-lock tries to highlight it), and mark it with a <code>font-lock-multiline</code> which will instruct font-lock not to start or end the scan in the middle of the construct. </li>
+</ul> <p>There are several ways to do rehighlighting of multiline constructs: </p> <ul> <li> Place a <code>font-lock-multiline</code> property on the construct. This will rehighlight the whole construct if any part of it is changed. In some cases you can do this automatically by setting the <code>font-lock-multiline</code> variable, which see. </li>
+<li> Make sure <code>jit-lock-contextually</code> is set and rely on it doing its job. This will only rehighlight the part of the construct that follows the actual change, and will do it after a short delay. This only works if the highlighting of the various parts of your multiline construct never depends on text in subsequent lines. Since <code>jit-lock-contextually</code> is activated by default, this can be an attractive solution. </li>
+<li> Place a <code>jit-lock-defer-multiline</code> property on the construct. This works only if <code>jit-lock-contextually</code> is used, and with the same delay before rehighlighting, but like <code>font-lock-multiline</code>, it also handles the case where highlighting depends on subsequent lines. </li>
+<li> If parsing the <em>syntax</em> of a construct depends on it being parsed in one single chunk, you can add the <code>syntax-multiline</code> text property over the construct in question. The most common use for this is when the syntax property to apply to ‘<samp>FOO</samp>’ depend on some later text ‘<samp>BAR</samp>’: By placing this text property over the whole of ‘<samp>FOO...BAR</samp>’, you make sure that any change of ‘<samp>BAR</samp>’ will also cause the syntax property of ‘<samp>FOO</samp>’ to be recomputed. Note: For this to work, the mode needs to add <code>syntax-propertize-multiline</code> to <code>syntax-propertize-extend-region-functions</code>. </li>
+</ul> <table class="menu" border="0" cellspacing="0"> <tr>
+<td align="left" valign="top">• <a href="font-lock-multiline" accesskey="1">Font Lock Multiline</a>
+</td>
+<td> </td>
+<td align="left" valign="top">Marking multiline chunks with a text property. </td>
+</tr> <tr>
+<td align="left" valign="top">• <a href="region-to-refontify" accesskey="2">Region to Refontify</a>
+</td>
+<td> </td>
+<td align="left" valign="top">Controlling which region gets refontified after a buffer change. </td>
+</tr> </table><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/Multiline-Font-Lock.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Multiline-Font-Lock.html</a>
+  </p>
+</div>