Общие ключевые слова для элементов

Объявления настройки, которые мы опишем в следующих разделах — defcustom, defgroup, и т.д. — все принимают ключевые аргументы (см. Постоянные переменные) для указания различной информации. Этот раздел описывает ключевые слова, применимые ко всем типам объявлений настройки.

Все эти ключевые слова, за исключением :tag, могут использоваться более одного раза в данном элементе. Каждое использование ключевого слова имеет независимый эффект. Ключевое слово :tag является исключением, так как любой данный элемент может отображать только одно имя.

:tag label

Используйте label, строку, вместо имени элемента для обозначения элемента в меню настройки и буферах. Не используйте тег, существенно отличающийся от реального имени элемента; это может вызвать путаницу.

:group group

Разместите этот элемент настройки в группе group. Если это ключевое слово отсутствует в элементе настройки, он будет размещен в той же группе, что была определена последней (в текущем файле).

Когда вы используете :group в defgroup, это делает новую группу подгруппой group.

Если вы используете это ключевое слово более одного раза, вы можете поместить один элемент в более чем одну группу. Отображение любой из этих групп покажет этот элемент. Пожалуйста, не злоупотребляйте этим, так как результат может быть раздражающим.

:link link-data

Включите внешнюю ссылку после строки документации для этого элемента. Это предложение, содержащее кнопку, которая ссылается на другую документацию.

Существует несколько альтернатив, которые вы можете использовать для link-data:

(custom-manual info-node)

Ссылка на узел Info; info-node — это строка, которая указывает имя узла, как в "(emacs)Top". Ссылка отображается как ‘[Справочник]’ в буфере настроек и переходит к встроенному читателю Info по info-node.

(info-link info-node)

Подобно custom-manual, за исключением того, что ссылка отображается в буфере настроек с именем узла Info.

(url-link url)

Ссылка на веб-страницу; url — это строка, которая указывает URL. Ссылка отображается в буфере настроек как url и вызывает веб-браузер, указанный в browse-url-browser-function.

(emacs-commentary-link library)

Ссылка на раздел комментариев библиотеки; library — это строка, которая указывает имя библиотеки. См. Заголовки библиотек.

(emacs-library-link library)

Ссылка на файл библиотеки Emacs Lisp; library — это строка, которая указывает имя библиотеки.

(file-link file)

Ссылка на файл; file — это строка, которая указывает имя файла, который будет посещен с помощью find-file, когда пользователь вызовет эту ссылку.

(function-link function)

Ссылка на документацию функции; function — это строка, которая указывает имя функции, которое будет описано с помощью describe-function, когда пользователь вызовет эту ссылку.

(variable-link variable)

Ссылка на документацию переменной; variable — это строка, которая указывает имя переменной, которая будет описана с помощью describe-variable, когда пользователь вызовет эту ссылку.

(face-link face)

Ссылка на документацию внешнего вида; face — это строка, которая указывает имя внешнего вида, которое будет описано с помощью describe-face, когда пользователь вызовет эту ссылку.

(custom-group-link group)

Ссылка на другую группу настроек. Вызов создаст новый буфер настроек для group.

Вы можете указать текст, используемый в буфере настроек, добавив :tag name после первого элемента link-data; например, (info-link :tag "foo" "(emacs)Top") создает ссылку на руководство Emacs, которая отображается в буфере как ‘foo’.

Вы можете использовать это ключевое слово более одного раза для добавления нескольких ссылок.

:load file

Загрузить файл file (строка) перед отображением этого элемента настройки (см. Загрузка). Загрузка выполняется с помощью load, и только если файл еще не загружен.

:require feature

Выполнить (require 'feature) при установке сохраненных настроек значения этого элемента. feature должен быть символом.

Наиболее распространенная причина использования :require — это когда переменная включает функцию, например, вспомогательный режим, и просто установка переменной не оказывает никакого эффекта, пока не загрузится код, реализующий режим.

:version version

Это ключевое слово указывает, что элемент впервые был представлен в версии Emacs version или что его значение по умолчанию было изменено в этой версии. Значение version должно быть строкой.

:package-version '(package . version)

Это ключевое слово указывает, что элемент впервые был представлен в версии пакета package version или что его значение или значение по умолчанию были изменены в этой версии. Это ключевое слово имеет приоритет над :version.

package должен быть официальным именем пакета, как символ (например, MH-E). version должна быть строкой. Если пакет package выпущен как часть Emacs, package и version должны появиться в значении customize-package-emacs-version-alist.

Пакеты, распространяемые в составе Emacs и использующие ключевое слово :package-version, также должны обновлять переменную customize-package-emacs-version-alist.

Переменная: customize-package-emacs-version-alist

Этот список ассоциаций предоставляет отображение версий Emacs, которые связаны с версиями пакета, перечисленного в ключевом слове :package-version.

(package (pversion . eversion)…)

Для каждого package, являющегося символом, есть один или несколько элементов, содержащих версию пакета pversion с соответствующей версией Emacs eversion. Эти версии являются строками. Например, пакет MH-E обновляет этот список ассоциаций следующим образом:

(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")))

Значение package должно быть уникальным и должно соответствовать значению package в ключевом слове :package-version. Поскольку пользователь может увидеть это значение в сообщении об ошибке, хорошим выбором является официальное имя пакета, например, MH-E или Gnus.