Справочное руководство по написанию, оформлению и структурированию файлов встроенной справки Vim (doc/*.txt).
Написание файлов справки
Создание файлов и типы файлов (filetype)
:edit doc/myplugin.txt
:set filetype=help " Предпросмотр форматирования и подсветка тегов
:set filetype=text " Удобный режим редактирования текста
Используйте ft=help для проверки внешнего вида и ft=text на этапе первоначального написания.
Пример структуры документа
*ack.txt* Plugin that integrates ack with Vim
==============================================================================
USAGE INSTRUCTIONS *ack-usage*
:Ack[!] {pattern} *:Ack*
Search recursively for {pattern}. See |:AckAdd|.
Also see http://beyondgrep.com for more information.
vim:tw=78:ts=8:ft=help:norl:
Полное официальное руководство доступно внутри Vim по команде :help help-writing.
Синтаксис и элементы разметки
Справочник разметки
| Разметка | Описание | Пример |
|---|---|---|
*tag* |
Тег целевой точки перехода | *myplugin-intro* |
|tag| |
Гиперссылка для перехода к тегу | |:command| |
'option' |
Опция конфигурации Vim | 'textwidth' |
{placeholder} |
Обязательный или необязательный аргумент | {Visual}gf |
<key> |
Специальная клавиша клавиатуры | <PageDown>, <CR> |
`command` |
Встроенная команда или строка кода | `set fo=want` |
CTRL-X |
Сочетание клавиш с Control | CTRL-] |
HEADING *tag* |
Заголовок раздела заглавными буквами с тегом | INSTALLATION *my-install* |
Heading~ |
Подзаголовок или заголовок столбца с тильдой | Options~ |
===== |
Основной разделитель разделов (78 символов) | ====================== |
----- |
Разделитель подразделов (78 символов) | ---------------------- |
Теги и навигация
- Выделяйте целевые якоря звездочками: plugin-tag
- Создавайте ссылки на теги символом вертикальной черты: |plugin-tag|
- Нажмите Ctrl-] на ссылке для мгновенного перехода к тегу; используйте Ctrl-T или Ctrl-O для возврата.
Блоки исходного кода
Обозначайте блоки кода знаком > в конце предшествующего абзаца и знаком < в начале строки окончания блока:
Example: >
let g:loaded_myplugin = 1
call myplugin#setup()
<
Заголовок документа
*myplugin.txt* Extended utility toolkit for Vim
В самой первой строке всегда указывайте основной тег с именем файла, за которым следует краткое описание.
Modeline для справки
Добавьте строку modeline в самую последнюю строчку файла:
vim:tw=78:ts=8:ft=help:norl:
Принятые соглашения
Оглавление (CONTENTS)
CONTENTS *myplugin-contents*
1. Introduction .............................. |myplugin-intro|
2. Commands .................................. |myplugin-commands|
3. Configuration Options ..................... |myplugin-options|
Блок сведений об авторе и лицензии
Author: Jack Hackness <[email protected]> *myplugin-author*
License: Same terms as Vim itself (see |license|)