Подстановка привязок клавиш в документации

Если в строках документации упоминаются последовательности клавиш, в них следует использовать текущие фактические привязки клавиш. Для этого можно использовать специальные текстовые последовательности, описанные ниже. При обычном обращении к строкам документации эти специальные последовательности заменяются сведениями о текущих привязках клавиш. Это выполняется вызовом substitute-command-keys. Вы также можете вызвать эту функцию самостоятельно.

Ниже приведен список специальных последовательностей и их значений:

\[command]

обозначает последовательность клавиш, которая вызывает command, или «M-x command», если для command не задано привязок клавиш.

\{mapvar}

обозначает краткое описание карты клавиш, являющейся значением переменной mapvar. Краткое описание создается с помощью describe-bindings. Обычно в него не включаются привязки меню, но если аргумент include-menus функции substitute-command-keys не равен nil, привязки меню будут включены.

\<mapvar>

не обозначает никакого текста. Эта последовательность используется только для побочного эффекта: она указывает, что значение mapvar следует использовать как карту клавиш для любых последующих последовательностей «\[command]» в этой строке документации.

\`KEYSEQ'

обозначает последовательность клавиш KEYSEQ, для которой используется тот же шрифт, что и для подстановки команды. Ее следует использовать только тогда, когда последовательности клавиш не соответствует команда, например если она считывается напрямую с помощью read-key-sequence. Она должна быть допустимой последовательностью клавиш согласно key-valid-p. Ее также можно использовать с именами команд, например «\`M-x foo'», если нужно, чтобы текст был выделен как последовательность клавиш, но при этом не преобразовывался в последовательность клавиш, как это происходит с «\[foo]».

`

(обратный апостроф) обозначает открывающую кавычку. В зависимости от значения text-quoting-style он преобразуется в левую одиночную кавычку, апостроф или обратный апостроф. См. Стиль кавычек в тексте.

'

(апостроф) обозначает закрывающую кавычку. В зависимости от значения text-quoting-style он преобразуется в правую одиночную кавычку или апостроф.

\=

экранирует следующий символ и отбрасывается; поэтому «\=`» вставляет в вывод «`», «\=\[» вставляет в вывод «\[», а «\=\=» вставляет в вывод «\=».

\+

указывает, что символ, непосредственно следующий за ним, не следует оформлять как ссылку в буфере *Help*.

Обратите внимание: каждый символ «\» при записи в строке Emacs Lisp необходимо удваивать (см. Синтаксис строк).

Функция: substitute-command-keys string &optional no-face include-menus

Эта функция просматривает string, находит описанные выше специальные последовательности и заменяет их соответствующими значениями, возвращая результат в виде строки. Это позволяет отображать документацию с привязками клавиш, соответствующими настройкам конкретного пользователя. По умолчанию привязки клавиш выделяются специальным шрифтом help-key-binding, но если необязательный аргумент no-face не равен nil, функция не добавляет этот шрифт в полученную строку.

Если у команды несколько привязок, эта функция обычно использует первую найденную. Вы можете указать конкретную привязку клавиш, присвоив команде свойство символа :advertised-binding, как показано ниже:

(put 'undo :advertised-binding [?\C-/])

Свойство :advertised-binding также влияет на привязку, отображаемую в пунктах меню (см. Строка меню). Свойство игнорируется, если в нем указана привязка клавиш, которой у команды на самом деле нет.

Ниже приведены примеры специальных последовательностей:

(substitute-command-keys
   "To abort recursive edit, type `\\[abort-recursive-edit]'.")
⇒ "To abort recursive edit, type ‘C-]’."

(substitute-command-keys
   "The keys that are defined for the minibuffer here are:
  \\{minibuffer-local-must-match-map}")
⇒ "The keys that are defined for the minibuffer here are:

?               minibuffer-completion-help
SPC             minibuffer-complete-word
TAB             minibuffer-complete
C-j             minibuffer-complete-and-exit
RET             minibuffer-complete-and-exit
C-g             abort-recursive-edit
"

The keymap description will normally exclude menu items, but if
include-menus is non-nil, include them.

(substitute-command-keys
   "To abort a recursive edit from the minibuffer, type \
`\\<minibuffer-local-must-match-map>\\[abort-recursive-edit]'.")
⇒ "To abort a recursive edit from the minibuffer, type ‘C-g’."

Функция: substitute-quotes string

Эта функция работает так же, как substitute-command-keys, но заменяет только символы кавычек.

Для текста в строках документации существуют и другие специальные соглашения — например, можно ссылаться на функции, переменные и разделы этого руководства. Подробнее см. Советы по написанию строк документации.