Writing Documentation | documentation writing-docs |
For every new feature, writing documentation is mandatory for the patch to be accepted. The docs are written in asciidoc version 8.x or newer. The are placed in the src/locale/en-US/ directory and compiled with make doc. Please refer to the asciidoc documentation above for details. Usually you can just write text as is, and mostly it will be interpreted correctly. The only difficult part is to write special sections like for :help.
|<F1>| |:help| |:h| |help|
||:h[elp] {subject}|| +
||<F1>||
____________________________________________________________________________
Open help window.
The default section is shown unless {subject} is specified.
If you need help for a specific topic, try [c]:help overview[c].
____________________________________________________________________________
is displayed as:
<F1> :help :h help
Open help window. The default section is shown unless {subject} is specified. If you need help for a specific topic, try :help overview.
Some notes about the code above:
|<F1>| defines a tag. A tag is written at the right in magenta and let's you jump to a topic with :help <F1>. Note that you must write it from right to left, so in the above example |help| will be the most left tag, and |<F1>| the most right one.
||:h[elp] {subject}|| + and ||<F1>|| define command or mapping names and are printed on the left side. Note the + at the end of one command, that indicates a new line. There is no general rule when a new line is needed and when not, just try it out and see what looks better.
The actual help code for this command is embedded in at least 4 underscores (_). This generates a quoteblock and indents the text so it is more clear that it belongs to the command.
Wrap things in [c] and they are drawn like a :command. Also [o] and [m] are available to show options and mappings.
Any string within {…} and [arg], [url], [count] and [!] are automatically drawn in a blue color.
There are also some additional asciidoc commands specifically for writing vimperator documentation:
section:Writing{nbsp}Documentation[writing-docs,documentation] Creates a new section like Writing Documentation in this help file with 2 tags.
help:developer{nbsp}information[developer.html#documentation] creates a link with text developer information to the tag documentation in the file developer.html.
If you don't know in which file/section you should put some documentation, ask on the mailing list or on #vimperator. Usually help should be grouped together in logically connected subject areas like opening web pages.