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

Когда строки документации ссылаются на последовательности клавиш, они должны использовать текущие, фактические привязки клавиш. Они могут сделать это, используя определенные специальные текстовые последовательности, описанные ниже. Доступ к строкам документации обычным способом подставляет информацию о текущих привязках клавиш для этих специальных последовательностей. Это работает путем вызова 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
   "Чтобы отменить рекурсивное редактирование, введите `\\[abort-recursive-edit]'.")
⇒ "Чтобы отменить рекурсивное редактирование, введите ‘C-]’."

(substitute-command-keys
   "Клавиши, определенные для minibuffer здесь:
  \\{minibuffer-local-must-match-map}")
⇒ "Клавиши, определенные для minibuffer здесь:

?               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
"

Описание карты клавиш обычно исключает элементы меню, но если
include-menus не равен nil, включите их.

(substitute-command-keys
   "Чтобы отменить рекурсивное редактирование из minibuffer, введите \
`\\<minibuffer-local-must-match-map>\\[abort-recursive-edit]'.")
⇒ "Чтобы отменить рекурсивное редактирование из minibuffer, введите ‘C-g’."

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

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

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