Привет, коллеги. Сегодня мы обсудим формат help-файла. Он очень прост.
Это может пригодиться, если вы делаете свои Вим-плагины (например, решили оформить какие-то удачные привязки, функции, скрипты и т.п. в виде цельного пакета), если вы решили перевести текст справки на другой язык или расширить его, а также для создания своей документации для своих целей. Для создания доки отлично подойдет перловский POD, который к тому же и в другие форматы конвертируется, зато Вим позволяет справку читать и умеет переходить по ссылкам. Про POD в другой раз расскажу, а сегодня давайте про Вим.
Файл должен быть иметь расширение txt (есть еще варианты для переводных, но в это пока не вдаемся). Первая строка должна быть вида
*helpfile_name.txt* For Vim version 7.3 Last change: 2010 June 4
Здесь важна первая компонента: это метка файла. По ней этот файл будет индексирован. Поля должны быть разделены табуляцией.
Последней строкой традиционно идет modeline, в которой задают опции textwidth, tabstop, filetype (это значение должно быть HELP).
В остальном пишите что хотите, но к вашим услугам есть некоторые средства разметки. Прежде всего, это метки, которые помещаются между звездочками. Как имя файла в первой строке. Или *MyDict_About*
Можно будет перейти на эту метку, так что ее традиционно размещают справа на отдельной строке. Это как заглавие параграфа. Важно, чтобы метка не совпадала с уже существующими.
Для ссылок на уже существующие метки (ваши или системные) поместите имя метки между вертикальными черточками |. Например, |MyDict_About|
При упоминании опции Вим, поместите ее между апострофами '. Например, 'textwidth'. Можно будет перейти на соответствующую страницу.
Эти три сущности будут выделены цветом при просмотре. А звездочки и черточки будут скрыты.
Цветом выделяется еще кое-что. Например, заголовки (которые ссылками не будут) пометьте тильдой ~ в конце строки. Заголовок (он один на строке) будет выделен. Например,
Это заголовок~
Отдельные мысли можно отделять друг от друга линией из знаков равенства от начала строки:
==================================
Эта линейка будет выделена цветом.
Чтобы пример кода был выделен отдельно цветом, поместите знак > в конце строки (отделив пробелом) перед блоком, и знак < в начале строки после блока, а сам блок пишите не от начала строки. Вместо завершающего <, можно начать новую строку после блока от начала строки. Например,
Пример кода: >
function f()
return
endfunc
<
Будут выделены строки от function... до endfunc.
Автоматически выделяются цветом клавиши, вроде <ESC> или CTRL-F, а также слово в фигурных скобках, например {rhs}.
Ну и есть ряд слов, выделяемых ярким цветом: Note, Notes. Также Todo и Error, но перед таким словом должна идти табуляция, потом пробел или звездочка, а после табуляция и латинские буквы. Потом что угодно.
Написав текст, поместите файл (или файлы) в ~/.vim/doc и проиндексируйте командой
:helptags ~/.vim/doc
Всё. Вы можете пользоваться своей справкой так же, как и встроенной.
Давайте рассмотрим пример.
Написав такой простенький учебный файл, разместив его в указанной папке и проведя индексацию, я могу теперь в любой момент запросить справку:
:help SHW_ch1
или по любой другой метке (их три всего).
Так можно сделать себе свой справочник и узнавать полезное не отрываясь от работы.
Может быть удобно.
Напоследок замечу, что можно не проводить индексацию, встраивая свои файлы в help-систему Вим. Достаточно просто выставить тип файла, если он не распознан автоматически, и читать справку с комфортом. Если она одним файлом, то переходы не слишком нужны, хватит поиска. А вот если вы забабахали доку во многих файлах, то Вим в качестве справочника может быть неплохой идеей.
Удачи, коллеги.