Emacs предоставляет различные встроенные функции справки, все из которых доступны пользователю как подкоманды префикса C-h. Для получения дополнительной информации о них см. Справка в Руководстве GNU Emacs. Здесь мы описываем некоторые программные интерфейсы к этой информации.
Эта функция находит все значимые символы, имена которых содержат совпадение с шаблоном 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 также показывает привязки клавиш для найденных функций; он также показывает все интернированные символы, а не только значимые (и также перечисляет их в возвращаемом значении).
Значение этой переменной — это локальная карта клавиш для символов после клавиши Справка, C-h.
Этот символ не является функцией; его ячейка определения функции содержит карту клавиш под названием help-map. Он определен в help.el следующим образом:
(keymap-set global-map (key-description (string help-char)) 'help-command) (fset 'help-command help-map)
Значение этой переменной — это символ справки — символ, который Emacs распознает как означающий Справку. По умолчанию его значение равно 8, что соответствует C-h. Когда Emacs считывает этот символ, если help-form является не nil выражением Lisp, он вычисляет это выражение и отображает результат в окне, если это строка.
Обычно значение help-form равно nil. Тогда символ справки не имеет специального значения на уровне ввода команды и становится частью последовательности клавиш обычным образом. Стандартная привязка клавиш C-h является префиксной клавишей для нескольких общих функций справки.
Символ справки также является специальным после префиксных клавиш. Если у него нет привязки как подкоманды префиксной клавиши, он вызывает describe-prefix-bindings, который отображает список всех подкоманд префиксной клавиши.
Значение этой переменной — это список типов событий, которые служат альтернативными символами справки. Эти события обрабатываются так же, как и событие, указанное в help-char.
Если эта переменная не равна nil, ее значение — это форма для вычисления всякий раз, когда считывается символ help-char. Если вычисление формы приводит к строке, эта строка отображается.
Команда, вызывающая read-event, read-char-choice, read-char, read-char-from-minibuffer или y-or-n-p, вероятно, должна привязать help-form к не nil выражению во время ввода. (Время, когда этого не следует делать, — это когда C-h имеет другое значение.)
Вычисление этого выражения должно привести к строке, объясняющей, для чего предназначен ввод и как его правильно ввести.
Ввод в minibuffer привязывает эту переменную к значению minibuffer-help-form (см. Определение minibuffer-help-form).
Эта переменная содержит функцию для вывода справки для префиксной клавиши. Функция вызывается, когда пользователь вводит префиксную клавишу, за которой следует символ справки, и у этого символа справки нет привязки после этой префиксной клавиши. Значение по умолчанию переменной — describe-prefix-bindings.
Эта функция вызывает describe-bindings для отображения списка всех подкоманд префиксной клавиши последней последовательности клавиш. Описанный префикс состоит из всех, кроме последнего события этой последовательности клавиш. (Последнее событие, предположительно, — это символ справки.)
Следующие две функции предназначены для режимов, которые хотят предоставить справку, не отказываясь от контроля, например, для электрических режимов. Их названия начинаются со слова ‘Helper’ для отличия от обычных функций справки.
Эта команда выводит окно, отображающее буфер справки, содержащий список всех привязок клавиш как из локальной, так и из глобальной карт клавиш. Она работает, вызывая describe-bindings.
Эта команда предоставляет справку для текущего режима. Она запрашивает у пользователя в minibuffer сообщение ‘Help (Type ? for further options)’, а затем помогает узнать, какие привязки клавиш существуют и для чего предназначен режим. Она возвращает nil.
Это можно настроить, изменив карту Helper-help-map.
Эта переменная содержит имя каталога, в котором Emacs находит определенные файлы документации и текста, поставляемые с Emacs.
Эта функция возвращает имя буфера справки, который обычно называется *Help*»; если такой буфер не существует, он сначала создается.
Этот макрос вычисляет body подобно with-output-to-temp-buffer (см. Временные отображения), вставляя любой вывод, сгенерированный его формами, в буфер, указанный buffer-or-name, который может быть буфером или именем буфера. (Часто buffer-or-name — это значение, возвращаемое функцией help-buffer.) Этот макрос помещает указанный буфер в режим справки и отображает сообщение, сообщающее пользователю, как выйти и прокрутить окно справки. Он выбирает окно справки, если текущее значение пользовательской опции help-window-select было соответствующим образом установлено. Он возвращает последнее значение в body.
Эта функция обновляет данные перекрестных ссылок в буфере *Help*», который используется для повторной генерации информации справки, когда пользователь нажимает кнопки ‘Назад’ или ‘Вперед’. Большинство команд, использующих буфер *Help*», должны вызывать эту функцию перед очисткой буфера. Аргумент item должен иметь форму (function . args), где function — это функция для вызова, с списком аргументов args, для повторной генерации буфера справки. Аргумент interactive-p не равен nil, если вызывающая команда была вызвана интерактивно; в этом случае очищается стек элементов для кнопок ‘Назад’ буфера *Help*».
См. пример describe-symbols для примера использования help-buffer, with-help-window и help-setup-xref.
Этот макрос определяет команду справки с именем 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.
Если эта переменная не равна nil, команды, определенные с помощью make-help-screen, сначала отображают свои строки help-line в области вывода, а более длинные строки help-text отображают только в том случае, если пользователь снова вводит символ справки.