new repository

1 files changed, 41 insertions, 0 deletions

diff --git a/devdocs/elisp/face-attributes.html b/devdocs/elisp/face-attributes.html
new file mode 100644
index 00000000..82ee939f
--- /dev/null
+++ b/devdocs/elisp/face-attributes.html
@@ -0,0 +1,41 @@
+ <h4 class="subsection">Face Attributes</h4>  <p><em>Face attributes</em> determine the visual appearance of a face. The following table lists all the face attributes, their possible values, and their effects. </p> <p>Apart from the values given below, each face attribute can have the value <code>unspecified</code>. This special value means that the face doesn’t specify that attribute directly. An <code>unspecified</code> attribute tells Emacs to refer instead to a parent face (see the description <code>:inherit</code> attribute below); or, failing that, to an underlying face (see <a href="displaying-faces">Displaying Faces</a>). The <code>default</code> face must specify all attributes. </p> <p>Some of these attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the attribute is ignored. </p> <dl compact> <dt><code>:family</code></dt> <dd>
+<p>Font family name (a string). See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Fonts.html#Fonts">Fonts</a> in <cite>The GNU Emacs Manual</cite>, for more information about font families. The function <code>font-family-list</code> (see below) returns a list of available family names. </p> </dd> <dt><code>:foundry</code></dt> <dd>
+<p>The name of the <em>font foundry</em> for the font family specified by the <code>:family</code> attribute (a string). See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Fonts.html#Fonts">Fonts</a> in <cite>The GNU Emacs Manual</cite>. </p> </dd> <dt><code>:width</code></dt> <dd>
+<p>Relative character width. This should be one of the symbols <code>ultra-condensed</code>, <code>extra-condensed</code>, <code>condensed</code>, <code>semi-condensed</code>, <code>normal</code>, <code>semi-expanded</code>, <code>expanded</code>, <code>extra-expanded</code>, or <code>ultra-expanded</code>. </p> </dd> <dt><code>:height</code></dt> <dd>
+<p>The height of the font. In the simplest case, this is an integer in units of 1/10 point. </p> <p>The value can also be floating point or a function, which specifies the height relative to an <em>underlying face</em> (see <a href="displaying-faces">Displaying Faces</a>). A floating-point value specifies the amount by which to scale the height of the underlying face. A function value is called with one argument, the height of the underlying face, and returns the height of the new face. If the function is passed an integer argument, it must return an integer. </p> <p>The height of the default face must be specified using an integer; floating point and function values are not allowed. </p> </dd> <dt><code>:weight</code></dt> <dd>
+<p>Font weight—one of the symbols (from densest to faintest) <code>ultra-bold</code>, <code>extra-bold</code>, <code>bold</code>, <code>semi-bold</code>, <code>normal</code>, <code>semi-light</code>, <code>light</code>, <code>extra-light</code>, or <code>ultra-light</code>. On text terminals which support variable-brightness text, any weight greater than normal is displayed as extra bright, and any weight less than normal is displayed as half-bright. </p>  </dd> <dt><code>:slant</code></dt> <dd>
+<p>Font slant—one of the symbols <code>italic</code>, <code>oblique</code>, <code>normal</code>, <code>reverse-italic</code>, or <code>reverse-oblique</code>. On text terminals that support variable-brightness text, slanted text is displayed as half-bright. </p> </dd> <dt><code>:foreground</code></dt> <dd>
+<p>Foreground color, a string. The value can be a system-defined color name, or a hexadecimal color specification. See <a href="color-names">Color Names</a>. On black-and-white displays, certain shades of gray are implemented by stipple patterns. </p> </dd> <dt><code>:distant-foreground</code></dt> <dd>
+<p>Alternative foreground color, a string. This is like <code>:foreground</code> but the color is only used as a foreground when the background color is near to the foreground that would have been used. This is useful for example when marking text (i.e., the region face). If the text has a foreground that is visible with the region face, that foreground is used. If the foreground is near the region face background, <code>:distant-foreground</code> is used instead so the text is readable. </p> </dd> <dt><code>:background</code></dt> <dd>
+<p>Background color, a string. The value can be a system-defined color name, or a hexadecimal color specification. See <a href="color-names">Color Names</a>. </p>  </dd> <dt><code>:underline</code></dt> <dd>
+<p>Whether or not characters should be underlined, and in what way. The possible values of the <code>:underline</code> attribute are: </p> <dl compact> <dt><code>nil</code></dt> <dd>
+<p>Don’t underline. </p> </dd> <dt><code>t</code></dt> <dd>
+<p>Underline with the foreground color of the face. </p> </dd> <dt><var>color</var></dt> <dd>
+<p>Underline in color <var>color</var>, a string specifying a color. </p> </dd> <dt><code>(:color <var>color</var> :style <var>style</var>)</code></dt> <dd><p><var>color</var> is either a string, or the symbol <code>foreground-color</code>, meaning the foreground color of the face. Omitting the attribute <code>:color</code> means to use the foreground color of the face. <var>style</var> should be a symbol <code>line</code> or <code>wave</code>, meaning to use a straight or wavy line. Omitting the attribute <code>:style</code> means to use a straight line. </p></dd> </dl>  </dd> <dt><code>:overline</code></dt> <dd>
+<p>Whether or not characters should be overlined, and in what color. If the value is <code>t</code>, overlining uses the foreground color of the face. If the value is a string, overlining uses that color. The value <code>nil</code> means do not overline. </p>  </dd> <dt><code>:strike-through</code></dt> <dd>
+<p>Whether or not characters should be strike-through, and in what color. The value is used like that of <code>:overline</code>. </p>   </dd> <dt><code>:box</code></dt> <dd>
+<p>Whether or not a box should be drawn around characters, its color, the width of the box lines, and 3D appearance. Here are the possible values of the <code>:box</code> attribute, and what they mean: </p> <dl compact> <dt><code>nil</code></dt> <dd>
+<p>Don’t draw a box. </p> </dd> <dt><code>t</code></dt> <dd>
+<p>Draw a box with lines of width 1, in the foreground color. </p> </dd> <dt><var>color</var></dt> <dd>
+<p>Draw a box with lines of width 1, in color <var>color</var>. </p> </dd> <dt><code>(:line-width (<var>vwidth</var> . <var>hwidth</var>) :color <var>color</var> :style <var>style</var>)</code></dt> <dd>
+<p>This way you can explicitly specify all aspects of the box. The values <var>vwidth</var> and <var>hwidth</var> specifies respectively the width of the vertical and horizontal lines to draw; they default to (1 . 1). A negative horizontal or vertical width -<var>n</var> means to draw a line of width <var>n</var> that occupies the space of the underlying text, thus avoiding any increase in the character height or width. For simplification the width could be specified with only a single number <var>n</var> instead of a list, such case is equivalent to <code>((abs <var>n</var>) . <var>n</var>)</code>. </p> <p>The value <var>style</var> specifies whether to draw a 3D box. If it is <code>released-button</code>, the box looks like a 3D button that is not being pressed. If it is <code>pressed-button</code>, the box looks like a 3D button that is being pressed. If it is <code>nil</code>, <code>flat-button</code> or omitted, a plain 2D box is used. </p> <p>The value <var>color</var> specifies the color to draw with. The default is the background color of the face for 3D boxes and <code>flat-button</code>, and the foreground color of the face for other boxes. </p>
+</dd> </dl> </dd> <dt><code>:inverse-video</code></dt> <dd>
+<p>Whether or not characters should be displayed in inverse video. The value should be <code>t</code> (yes) or <code>nil</code> (no). </p> </dd> <dt><code>:stipple</code></dt> <dd>
+<p>The background stipple, a bitmap. </p> <p>The value can be a string; that should be the name of a file containing external-format X bitmap data. The file is found in the directories listed in the variable <code>x-bitmap-file-path</code>. </p> <p>Alternatively, the value can specify the bitmap directly, with a list of the form <code>(<var>width</var> <var>height</var> <var>data</var>)</code>. Here, <var>width</var> and <var>height</var> specify the size in pixels, and <var>data</var> is a string containing the raw bits of the bitmap, row by row. Each row occupies <em>(<var>width</var> + 7) / 8</em> consecutive bytes in the string (which should be a unibyte string for best results). This means that each row always occupies at least one whole byte. </p> <p>If the value is <code>nil</code>, that means use no stipple pattern. </p> <p>Normally you do not need to set the stipple attribute, because it is used automatically to handle certain shades of gray. </p> </dd> <dt><code>:font</code></dt> <dd>
+<p>The font used to display the face. Its value should be a font object or a fontset. If it is a font object, it specifies the font to be used by the face for displaying ASCII characters. See <a href="low_002dlevel-font">Low-Level Font</a>, for information about font objects, font specs, and font entities. See <a href="fontsets">Fontsets</a>, for information about fontsets. </p> <p>When specifying this attribute using <code>set-face-attribute</code> or <code>set-face-font</code> (see <a href="attribute-functions">Attribute Functions</a>), you may also supply a font spec, a font entity, or a string. Emacs converts such values to an appropriate font object, and stores that font object as the actual attribute value. If you specify a string, the contents of the string should be a font name (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Fonts.html#Fonts">Fonts</a> in <cite>The GNU Emacs Manual</cite>); if the font name is an XLFD containing wildcards, Emacs chooses the first font matching those wildcards. Specifying this attribute also changes the values of the <code>:family</code>, <code>:foundry</code>, <code>:width</code>, <code>:height</code>, <code>:weight</code>, and <code>:slant</code> attributes. </p>  </dd> <dt><code>:inherit</code></dt> <dd>
+<p>The name of a face from which to inherit attributes, or a list of face names. Attributes from inherited faces are merged into the face like an underlying face would be, with higher priority than underlying faces (see <a href="displaying-faces">Displaying Faces</a>). If the face to inherit from is <code>unspecified</code>, it is treated the same as <code>nil</code>, since Emacs never merges <code>:inherit</code> attributes. If a list of faces is used, attributes from faces earlier in the list override those from later faces. </p> </dd> <dt><code>:extend</code></dt> <dd>
+<p>Whether or not this face will be extended beyond end of line and will affect the display of the empty space between the end of line and the edge of the window. The value should be <code>t</code> to display the empty space between end of line and edge of the window using this face, or <code>nil</code> to not use this face for the space between the end of the line and the edge of the window. When Emacs merges several faces for displaying the empty space beyond end of line, only those faces with <code>:extend</code> non-<code>nil</code> will be merged. By default, only a small number of faces, notably, <code>region</code>, have this attribute set. This attribute is different from the others in that when a theme doesn’t specify an explicit value for a face, the value from the original face definition by <code>defface</code> is inherited (see <a href="defining-faces">Defining Faces</a>). </p> <p>Some modes, like <code>hl-line-mode</code>, use a face with an <code>:extend</code> property to mark the entire current line. Note, however, that Emacs will always allow you to move point after the final character in a buffer, and if the buffer ends with a newline character, point can be placed on what is seemingly a line at the end of the buffer—but Emacs can’t highlight that “line”, because it doesn’t really exist. </p>
+</dd> </dl> <dl> <dt id="font-family-list">Function: <strong>font-family-list</strong> <em>&amp;optional frame</em>
+</dt> <dd><p>This function returns a list of available font family names. The optional argument <var>frame</var> specifies the frame on which the text is to be displayed; if it is <code>nil</code>, the selected frame is used. </p></dd>
+</dl> <dl> <dt id="underline-minimum-offset">User Option: <strong>underline-minimum-offset</strong>
+</dt> <dd><p>This variable specifies the minimum distance between the baseline and the underline, in pixels, when displaying underlined text. </p></dd>
+</dl> <dl> <dt id="x-bitmap-file-path">User Option: <strong>x-bitmap-file-path</strong>
+</dt> <dd><p>This variable specifies a list of directories for searching for bitmap files, for the <code>:stipple</code> attribute. </p></dd>
+</dl> <dl> <dt id="bitmap-spec-p">Function: <strong>bitmap-spec-p</strong> <em>object</em>
+</dt> <dd><p>This returns <code>t</code> if <var>object</var> is a valid bitmap specification, suitable for use with <code>:stipple</code> (see above). It returns <code>nil</code> otherwise. </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/Face-Attributes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Face-Attributes.html</a>
+  </p>
+</div>