Функции справки

Emacs предоставляет различные встроенные функции справки, доступные пользователю как подкоманды префикса C-h. Более подробную информацию о них можно найти в Справке в Руководстве по GNU Emacs. Здесь мы опишем некоторые интерфейсы на уровне программы для доступа к этой информации.

Команда: apropos pattern &optional do-all

Эта функция находит все значимые символы, имена которых содержат соответствие шаблону поиска apropos pattern. Шаблон apropos может представлять собой слово для поиска, список слов, разделенных пробелами (при этом должно совпасть как минимум два слова), или регулярное выражение (если используются специальные символы регулярных выражений). Символ считается значимым, если он определён как функция, переменная или вид, или если он обладает свойствами.

Функция возвращает список элементов следующего вида:

(symbol score function-doc variable-doc
 plist-doc widget-doc face-doc group-doc)

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

Функция также отображает символы в буфере с именем *Apropos*, каждый с однострочным описанием, взятым из начала строки документации.

Если do-all не nil, или если пользовательский параметр apropos-do-all не nil, то apropos также отобразит сочетания клавиш для найденных функций; он также отобразит *все* интернированные символы, а не только значимые (и включит их в значение возврата).

Переменная: help-map

Значение этой переменной — локальная карта клавиш для символов, следующих за клавишей справки C-h.

Команда-префикс: help-command

Этот символ не является функцией; его ячейка определения функции содержит карту клавиш, известную как help-map. Она определена в help.el следующим образом:

(define-key global-map (string help-char) 'help-command)
(fset 'help-command help-map)

Пользовательский параметр: help-char

Значение этой переменной — символ справки — символ, распознаваемый Emacs как символ справки. По умолчанию его значение равно 8, что соответствует C-h. При чтении Emacs этого символа, если help-form является выражением Lisp, отличным от nil, оно вычисляется, а результат отображается в окне, если это строка.

Обычно значение help-form равно nil. В таком случае символ справки не имеет специального значения на уровне ввода команд и становится частью последовательности клавиш обычным образом. Стандартное сочетание клавиш C-h является префиксом для нескольких функций справки общего назначения.

Символ справки также является специальным после префиксных клавиш. Если у него нет привязки в качестве подкоманды префикса, он выполняет describe-prefix-bindings, который отображает список всех подкоманд префикса.

Пользовательский параметр: help-event-list

Значение этой переменной — список типов событий, которые служат альтернативными символами справки. Эти события обрабатываются так же, как событие, указанное help-char.

Переменная: help-form

Если эта переменная не nil, её значение — выражение, которое вычисляется всякий раз, когда считывается символ help-char. Если вычисление выражения даёт строку, эта строка отображается.

Команда, вызывающая read-event, read-char-choice, read-char, read-char-from-minibuffer, или y-or-n-p, вероятно, должна привязать help-form к выражению, отличному от nil, пока происходит ввод. (Время, когда это не следует делать, — это время, когда у C-h есть другое значение.) Вычисление этого выражения должно привести к строке, которая объясняет, для чего предназначен ввод, и как его правильно ввести.

Ввод в минибуфер привязывает эту переменную к значению minibuffer-help-form (см. Определение minibuffer-help-form).

Переменная: prefix-help-command

Эта переменная хранит функцию для вывода справки по префиксной клавише. Функция вызывается, когда пользователь набирает префиксную клавишу, за которой следует символ справки, а символ справки не имеет привязки после этого префикса. Значение по умолчанию переменной — describe-prefix-bindings.

Команда: describe-prefix-bindings

Эта функция вызывает describe-bindings для отображения списка всех подкоманд префиксной клавиши последней последовательности клавиш. Описанный префикс состоит из всех событий, кроме последнего, в этой последовательности клавиш. (Последнее событие, по-видимому, это символ справки.)

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

Команда: Helper-describe-bindings

Эта команда открывает окно с отображением буфера справки, содержащего список всех сочетаний клавиш из локальных и глобальных карт клавиш. Она работает путём вызова describe-bindings.

Команда: Helper-help

Эта команда предоставляет справку по текущему режиму. Она запрашивает пользователя в минибуфере сообщением ‘Справка (введите ? для дополнительных вариантов)’, а затем помогает узнать, какие сочетания клавиш используются, и для чего предназначен режим. Она возвращает nil.

Это можно настроить, изменив карту Helper-help-map.

Переменная: data-directory

Эта переменная содержит имя каталога, в котором Emacs находит определённые файлы документации и текстовые файлы, поставляемые с Emacs.

Функция: help-buffer

Эта функция возвращает имя буфера справки, которое обычно *Help*; если такого буфера не существует, он сначала создаётся.

Макрос: with-help-window buffer-or-name body…

Этот макрос вычисляет body как with-output-to-temp-buffer (см. Временные отображения), вставляя любой вывод, производимый его выражениями, в буфер, заданный buffer-or-name, который может быть буфером или именем буфера. (Часто buffer-or-name — значение, возвращаемое функцией help-buffer.) Этот макрос помещает указанный буфер в режим справки и отображает сообщение, объясняющее пользователю, как выйти и прокрутить окно справки. Он выбирает окно справки, если текущее значение пользовательского параметра help-window-select было соответствующим образом установлено. Он возвращает последнее значение в body.

Функция: help-setup-xref item interactive-p

Эта функция обновляет данные перекрёстной ссылки в буфере *Help*, которые используются для перегенерации информации о справке, когда пользователь нажимает кнопки «Назад» или «Вперёд». Большинство команд, использующих буфер *Help*, должны вызывать эту функцию перед очисткой буфера. Аргумент item должен иметь вид (function . args), где function — функция для вызова со списком аргументов args, для перегенерации буфера справки. Аргумент interactive-p — не nil, если вызывающая команда была вызвана интерактивно; в этом случае стек элементов для кнопок «Назад» буфера *Help* очищается.

См. пример describe-symbols для примера использования help-buffer, with-help-window, и help-setup-xref.

Макрос: make-help-screen fname help-line help-text help-map

Этот макрос определяет команду справки с именем fname, которая действует как префиксная клавиша, отображающая список предлагаемых ею подкоманд.

При вызове fname отображает help-text в окне, затем считывает и выполняет последовательность клавиш согласно help-map. Строка help-text должна описывать доступные привязки в help-map.

Команда fname сама обрабатывает несколько событий, прокручивая отображение help-text. Когда fname считывает одно из этих специальных событий, она выполняет прокрутку и затем считывает другое событие. Когда она считывает событие, которое не является одним из этих нескольких и у которого есть привязка в help-map, она выполняет привязку клавиши и затем возвращается.

Аргумент help-line должен быть кратким описанием альтернатив в help-map. В текущей версии Emacs этот аргумент используется только если вы установили параметр three-step-help в t.

Этот макрос используется в команде help-for-help, которая является привязкой C-h C-h.

Пользовательский параметр: three-step-help

Если эта переменная не nil, команды, определённые с помощью make-help-screen, сначала отображают свои строки help-line в области эха, а строки help-text большей длины отображаются только если пользователь снова вводит символ справки.