new repository

1 files changed, 10 insertions, 0 deletions

diff --git a/devdocs/elisp/font-lock-multiline.html b/devdocs/elisp/font-lock-multiline.html
new file mode 100644
index 00000000..d29627e0
--- /dev/null
+++ b/devdocs/elisp/font-lock-multiline.html
@@ -0,0 +1,10 @@
+ <h4 class="subsubsection">Font Lock Multiline</h4> <p>One way to ensure reliable rehighlighting of multiline Font Lock constructs is to put on them the text property <code>font-lock-multiline</code>. It should be present and non-<code>nil</code> for text that is part of a multiline construct. </p> <p>When Font Lock is about to highlight a range of text, it first extends the boundaries of the range as necessary so that they do not fall within text marked with the <code>font-lock-multiline</code> property. Then it removes any <code>font-lock-multiline</code> properties from the range, and highlights it. The highlighting specification (mostly <code>font-lock-keywords</code>) must reinstall this property each time, whenever it is appropriate. </p> <p><strong>Warning:</strong> don’t use the <code>font-lock-multiline</code> property on large ranges of text, because that will make rehighlighting slow. </p> <dl> <dt id="font-lock-multiline">Variable: <strong>font-lock-multiline</strong>
+</dt> <dd>
+<p>If the <code>font-lock-multiline</code> variable is set to <code>t</code>, Font Lock will try to add the <code>font-lock-multiline</code> property automatically on multiline constructs. This is not a universal solution, however, since it slows down Font Lock somewhat. It can miss some multiline constructs, or make the property larger or smaller than necessary. </p> <p>For elements whose <var>matcher</var> is a function, the function should ensure that submatch 0 covers the whole relevant multiline construct, even if only a small subpart will be highlighted. It is often just as easy to add the <code>font-lock-multiline</code> property by hand. </p>
+</dd>
+</dl> <p>The <code>font-lock-multiline</code> property is meant to ensure proper refontification; it does not automatically identify new multiline constructs. Identifying them requires that Font Lock mode operate on large enough chunks at a time. This will happen by accident on many cases, which may give the impression that multiline constructs magically work. If you set the <code>font-lock-multiline</code> variable non-<code>nil</code>, this impression will be even stronger, since the highlighting of those constructs which are found will be properly updated from then on. But that does not work reliably. </p> <p>To find multiline constructs reliably, you must either manually place the <code>font-lock-multiline</code> property on the text before Font Lock mode looks at it, or use <code>font-lock-fontify-region-function</code>. </p><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/Font-Lock-Multiline.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Font-Lock-Multiline.html</a>
+  </p>
+</div>