Замена сочетаний клавиш в документации

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

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

\[command]

обозначает последовательность клавиш, которая вызовет команду, или ‘M-x команда’, если у команды нет сочетаний клавиш.

\{mapvar}

обозначает сводку ключевой карты, которая является значением переменной mapvar. Сводка создается с помощью describe-bindings.

\<mapvar>

не означает сам текст. Используется только для побочного эффекта: указывает значение mapvar в качестве ключевой карты для всех последующих последовательностей ‘\[команда]’ в этой строке документации.

`

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

'

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

\=

цитирует следующий символ и отбрасывается; таким образом, ‘\=`’ помещает ‘`’ в вывод, ‘\=\[’ помещает ‘\[’ в вывод, а ‘\=\=’ помещает ‘\=’ в вывод.

Примечание: Каждый ‘\’ должен быть удвоен при написании в строке в Emacs Lisp.

Параметр пользователя: text-quoting-style

Значение этой переменной — символ, который определяет стиль, который Emacs должен использовать для одинарных кавычек в формулировке справки и сообщений. Если значение переменной равно curve, стиль — ‘так’ с изогнутыми одинарными кавычками. Если значение равно straight, стиль — 'так' с прямыми апострофами. Если значение равно grave, кавычки не переводятся, и стиль — `так' с грависом и апострофом, стандартный стиль до версии Emacs 25. Значение по умолчанию nil действует как curve , если изогнутые одинарные кавычки кажутся отображаемыми, и как grave в противном случае.

Этот параметр полезен на платформах, имеющих проблемы с изогнутыми кавычками. Вы можете настроить его по своему усмотрению.

Функция: substitute-command-keys строка &опционально без-лица

Эта функция сканирует строку на предмет вышеупомянутых специальных последовательностей и заменяет их соответствующими значениями, возвращая результат как строку. Это позволяет отображать документацию, которая точно ссылается на настроенные пользователем сочетания клавиш. По умолчанию сочетания клавиш имеют специальное лицо help-key-binding, но если необязательный аргумент без-лица не 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
"

(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’."

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