new repository

1 files changed, 14 insertions, 0 deletions

diff --git a/devdocs/elisp/mode-line-data.html b/devdocs/elisp/mode-line-data.html
new file mode 100644
index 00000000..b2dd75de
--- /dev/null
+++ b/devdocs/elisp/mode-line-data.html
@@ -0,0 +1,14 @@
+ <h4 class="subsection">The Data Structure of the Mode Line</h4>  <p>The mode line contents are controlled by a data structure called a <em>mode line construct</em>, made up of lists, strings, symbols, and numbers kept in buffer-local variables. Each data type has a specific meaning for the mode line appearance, as described below. The same data structure is used for constructing frame titles (see <a href="frame-titles">Frame Titles</a>) and header lines (see <a href="header-lines">Header Lines</a>). </p> <p>A mode line construct may be as simple as a fixed string of text, but it usually specifies how to combine fixed strings with variables’ values to construct the text. Many of these variables are themselves defined to have mode line constructs as their values. </p> <p>Here are the meanings of various data types as mode line constructs: </p> <dl compact>  <dt><code><var>string</var></code></dt> <dd>
+<p>A string as a mode line construct appears verbatim except for <em><code>%</code>-constructs</em> in it. These stand for substitution of other data; see <a href="_0025_002dconstructs">%-Constructs</a>. </p> <p>If parts of the string have <code>face</code> properties, they control display of the text just as they would text in the buffer. Any characters which have no <code>face</code> properties are displayed, by default, in the face <code>mode-line</code> or <code>mode-line-inactive</code> (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Standard-Faces.html#Standard-Faces">Standard Faces</a> in <cite>The GNU Emacs Manual</cite>). The <code>help-echo</code> and <code>keymap</code> properties in <var>string</var> have special meanings. See <a href="properties-in-mode">Properties in Mode</a>. </p> </dd> <dt><code><var>symbol</var></code></dt> <dd>
+<p>A symbol as a mode line construct stands for its value. The value of <var>symbol</var> is used as a mode line construct, in place of <var>symbol</var>. However, the symbols <code>t</code> and <code>nil</code> are ignored, as is any symbol whose value is void. </p> <p>There is one exception: if the value of <var>symbol</var> is a string, it is displayed verbatim: the <code>%</code>-constructs are not recognized. </p> <p>Unless <var>symbol</var> is marked as risky (i.e., it has a non-<code>nil</code> <code>risky-local-variable</code> property), all text properties specified in <var>symbol</var>’s value are ignored. This includes the text properties of strings in <var>symbol</var>’s value, as well as all <code>:eval</code> and <code>:propertize</code> forms in it. (The reason for this is security: non-risky variables could be set automatically from file variables without prompting the user.) </p> </dd> <dt><code>(<var>string</var> <var>rest</var>…)</code></dt> <dt><code>(<var>list</var> <var>rest</var>…)</code></dt> <dd>
+<p>A list whose first element is a string or list means to process all the elements recursively and concatenate the results. This is the most common form of mode line construct. (Note that text properties are handled specially (for reasons of efficiency) when displaying strings in the mode line: Only the text property on the first character of the string are considered, and they are then used over the entire string. If you need a string with different text properties, you have to use the special <code>:propertize</code> mode line construct.) </p> </dd> <dt><code>(:eval <var>form</var>)</code></dt> <dd>
+<p>A list whose first element is the symbol <code>:eval</code> says to evaluate <var>form</var>, and use the result as a string to display. Make sure this evaluation cannot load any files, as doing so could cause infinite recursion. </p> </dd> <dt><code>(:propertize <var>elt</var> <var>props</var>…)</code></dt> <dd>
+<p>A list whose first element is the symbol <code>:propertize</code> says to process the mode line construct <var>elt</var> recursively, then add the text properties specified by <var>props</var> to the result. The argument <var>props</var> should consist of zero or more pairs <var>text-property</var> <var>value</var>. If <var>elt</var> is or produces a string with text properties, all the characters of that string should have the same properties, or else some of them might be removed by <code>:propertize</code>. </p> </dd> <dt><code>(<var>symbol</var> <var>then</var> <var>else</var>)</code></dt> <dd>
+<p>A list whose first element is a symbol that is not a keyword specifies a conditional. Its meaning depends on the value of <var>symbol</var>. If <var>symbol</var> has a non-<code>nil</code> value, the second element, <var>then</var>, is processed recursively as a mode line construct. Otherwise, the third element, <var>else</var>, is processed recursively. You may omit <var>else</var>; then the mode line construct displays nothing if the value of <var>symbol</var> is <code>nil</code> or void. </p> </dd> <dt><code>(<var>width</var> <var>rest</var>…)</code></dt> <dd>
+<p>A list whose first element is an integer specifies truncation or padding of the results of <var>rest</var>. The remaining elements <var>rest</var> are processed recursively as mode line constructs and concatenated together. When <var>width</var> is positive, the result is space filled on the right if its width is less than <var>width</var>. When <var>width</var> is negative, the result is truncated on the right to -<var>width</var> columns if its width exceeds -<var>width</var>. </p> <p>For example, the usual way to show what percentage of a buffer is above the top of the window is to use a list like this: <code>(-3 "%p")</code>. </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/Mode-Line-Data.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Mode-Line-Data.html</a>
+  </p>
+</div>