Vimperator

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

: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 :help overview.

Some notes about the code above:

There are also some additional asciidoc commands specifically for writing Vimperator documentation:

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.

Generating documentation

generating-docs

You can also autogenerate most of the asciidoc help after you have written a new command, mapping or option. For this, use:

:echo util.generateHelp(commands.get("addons"), "Extra text")

Now you can copy the asciidoc text but always make sure it looks OK after you compile the help file with "make doc", as the auto-generation might not work correctly for all special cases.