1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
heading:Developer{nbsp}information[developer-information]
section:Writing{nbsp}documentation[writing-docs,documentation]
For every new feature, writing documentation is _mandatory_ for the patch to
be accepted. The docs are written in
http://www.methods.co.nz/asciidoc/index.html[asciidoc] version 8.2.x.
They are placed in the _src/locale/en-US/_ directory and compiled with
_make doc_. Please refer to the
http://www.methods.co.nz/asciidoc/userguide.html[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::help[various.html,online-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:
++++++++++++++++++++++++++++++++++++++++
<p><span class="hiddentag"><F1></span> <span
class="hiddentag">:help</span> <span class="hiddentag">:h</span> <span
class="hiddentag">help</span>
<div class="key">:h[elp] <span class="argument">{subject}</span></div><br />
<div class="key"><F1></div></p>
<div class="quoteblock">
<div class="quoteblock-content">
<p>Open help window.
The default section is shown unless <span class="argument">{subject}</span> is specified.
If you need help for a specific topic, try <span class="command">:help overview</span>.</p>
</div></div>
+++++++++++++++++++++++++++++++++++++++
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 [c]:help <F1>[c]. 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]$$*,
*$$[m]$$* and *$$[a]$$* are available to markup options, mappings, and
arguments.
- As a convenience, any string within \{...\} and $$[count]$$ and $$[!]$$ are
automatically marked up as an argument.
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
help:opening{nbsp}web{nbsp}pages[browsing.html,opening].
section:Generating{nbsp}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.
// vim: set filetype=asciidoc:
|
