new repository

1 files changed, 34 insertions, 0 deletions

diff --git a/devdocs/elisp/common-keywords.html b/devdocs/elisp/common-keywords.html
new file mode 100644
index 00000000..a9cfa354
--- /dev/null
+++ b/devdocs/elisp/common-keywords.html
@@ -0,0 +1,34 @@
+ <h3 class="section">Common Item Keywords</h3>  <p>The customization declarations that we will describe in the next few sections—<code>defcustom</code>, <code>defgroup</code>, etc.—all accept keyword arguments (see <a href="constant-variables">Constant Variables</a>) for specifying various information. This section describes keywords that apply to all types of customization declarations. </p> <p>All of these keywords, except <code>:tag</code>, can be used more than once in a given item. Each use of the keyword has an independent effect. The keyword <code>:tag</code> is an exception because any given item can only display one name. </p> <dl compact> <dt><code>:tag <var>label</var></code></dt> <dd>
+ <p>Use <var>label</var>, a string, instead of the item’s name, to label the item in customization menus and buffers. <strong>Don’t use a tag which is substantially different from the item’s real name; that would cause confusion.</strong> </p>  </dd> <dt><code>:group <var>group</var></code></dt> <dd>
+<p>Put this customization item in group <var>group</var>. If this keyword is missing from a customization item, it’ll be placed in the same group that was last defined (in the current file). </p> <p>When you use <code>:group</code> in a <code>defgroup</code>, it makes the new group a subgroup of <var>group</var>. </p> <p>If you use this keyword more than once, you can put a single item into more than one group. Displaying any of those groups will show this item. Please don’t overdo this, since the result would be annoying. </p> </dd> <dt><code>:link <var>link-data</var></code></dt> <dd>
+ <p>Include an external link after the documentation string for this item. This is a sentence containing a button that references some other documentation. </p> <p>There are several alternatives you can use for <var>link-data</var>: </p> <dl compact> <dt><code>(custom-manual <var>info-node</var>)</code></dt> <dd>
+<p>Link to an Info node; <var>info-node</var> is a string which specifies the node name, as in <code>"(emacs)Top"</code>. The link appears as ‘<samp>[Manual]</samp>’ in the customization buffer and enters the built-in Info reader on <var>info-node</var>. </p> </dd> <dt><code>(info-link <var>info-node</var>)</code></dt> <dd>
+<p>Like <code>custom-manual</code> except that the link appears in the customization buffer with the Info node name. </p> </dd> <dt><code>(url-link <var>url</var>)</code></dt> <dd>
+<p>Link to a web page; <var>url</var> is a string which specifies the <acronym>URL</acronym>. The link appears in the customization buffer as <var>url</var> and invokes the WWW browser specified by <code>browse-url-browser-function</code>. </p> </dd> <dt><code>(emacs-commentary-link <var>library</var>)</code></dt> <dd>
+<p>Link to the commentary section of a library; <var>library</var> is a string which specifies the library name. See <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Library-Headers.html">Library Headers</a>. </p> </dd> <dt><code>(emacs-library-link <var>library</var>)</code></dt> <dd>
+<p>Link to an Emacs Lisp library file; <var>library</var> is a string which specifies the library name. </p> </dd> <dt><code>(file-link <var>file</var>)</code></dt> <dd>
+<p>Link to a file; <var>file</var> is a string which specifies the name of the file to visit with <code>find-file</code> when the user invokes this link. </p> </dd> <dt><code>(function-link <var>function</var>)</code></dt> <dd>
+<p>Link to the documentation of a function; <var>function</var> is a string which specifies the name of the function to describe with <code>describe-function</code> when the user invokes this link. </p> </dd> <dt><code>(variable-link <var>variable</var>)</code></dt> <dd>
+<p>Link to the documentation of a variable; <var>variable</var> is a string which specifies the name of the variable to describe with <code>describe-variable</code> when the user invokes this link. </p> </dd> <dt><code>(face-link <var>face</var>)</code></dt> <dd>
+<p>Link to the documentation of a face; <var>face</var> is a string which specifies the name of the face to describe with <code>describe-face</code> when the user invokes this link. </p> </dd> <dt><code>(custom-group-link <var>group</var>)</code></dt> <dd><p>Link to another customization group. Invoking it creates a new customization buffer for <var>group</var>. </p></dd> </dl> <p>You can specify the text to use in the customization buffer by adding <code>:tag <var>name</var></code> after the first element of the <var>link-data</var>; for example, <code>(info-link :tag "foo" "(emacs)Top")</code> makes a link to the Emacs manual which appears in the buffer as ‘<samp>foo</samp>’. </p> <p>You can use this keyword more than once, to add multiple links. </p> </dd> <dt><code>:load <var>file</var></code></dt> <dd>
+ <p>Load file <var>file</var> (a string) before displaying this customization item (see <a href="loading">Loading</a>). Loading is done with <code>load</code>, and only if the file is not already loaded. </p> </dd> <dt><code>:require <var>feature</var></code></dt> <dd>
+ <p>Execute <code>(require '<var>feature</var>)</code> when your saved customizations set the value of this item. <var>feature</var> should be a symbol. </p> <p>The most common reason to use <code>:require</code> is when a variable enables a feature such as a minor mode, and just setting the variable won’t have any effect unless the code which implements the mode is loaded. </p> </dd> <dt><code>:version <var>version</var></code></dt> <dd>
+ <p>This keyword specifies that the item was first introduced in Emacs version <var>version</var>, or that its default value was changed in that version. The value <var>version</var> must be a string. </p> </dd> <dt><code>:package-version '(<var>package</var> . <var>version</var>)</code></dt> <dd>
+ <p>This keyword specifies that the item was first introduced in <var>package</var> version <var>version</var>, or that its meaning or default value was changed in that version. This keyword takes priority over <code>:version</code>. </p> <p><var>package</var> should be the official name of the package, as a symbol (e.g., <code>MH-E</code>). <var>version</var> should be a string. If the package <var>package</var> is released as part of Emacs, <var>package</var> and <var>version</var> should appear in the value of <code>customize-package-emacs-version-alist</code>. </p>
+</dd> </dl> <p>Packages distributed as part of Emacs that use the <code>:package-version</code> keyword must also update the <code>customize-package-emacs-version-alist</code> variable. </p> <dl> <dt id="customize-package-emacs-version-alist">Variable: <strong>customize-package-emacs-version-alist</strong>
+</dt> <dd>
+<p>This alist provides a mapping for the versions of Emacs that are associated with versions of a package listed in the <code>:package-version</code> keyword. Its elements are: </p> <div class="example"> <pre class="example">(<var>package</var> (<var>pversion</var> . <var>eversion</var>)…)
+</pre>
+</div> <p>For each <var>package</var>, which is a symbol, there are one or more elements that contain a package version <var>pversion</var> with an associated Emacs version <var>eversion</var>. These versions are strings. For example, the MH-E package updates this alist with the following: </p> <div class="example"> <pre class="example">(add-to-list 'customize-package-emacs-version-alist
+             '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
+                    ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
+                    ("7.4" . "22.1") ("8.0" . "22.1")))
+</pre>
+</div> <p>The value of <var>package</var> needs to be unique and it needs to match the <var>package</var> value appearing in the <code>:package-version</code> keyword. Since the user might see the value in an error message, a good choice is the official name of the package, such as MH-E or Gnus. </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/Common-Keywords.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Common-Keywords.html</a>
+  </p>
+</div>