-
Notifications
You must be signed in to change notification settings - Fork 1
/
vim-hp.txt
146 lines (123 loc) · 5.38 KB
/
vim-hp.txt
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
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
*vim-hp* plugin to help you write documentation for your plugins.
Author: Vladimir Popov <vladimir@dokwork.ru>
License: MIT License
==============================================================================
CONTENTS
1. Usage.......................|hp-usage|
1.1. Sections...........|hp-sections|
1.2. Example.............|hp-example|
2. Commands.................|hp-commands|
==============================================================================
1. Usage *hp-usage*
The main feature of this plugin is generating a contents of your
documentation. The command |HpGenerateContents| generates a contents of the
current buffer and put it under cursor. By default, width of the contents will
be equal to the |textwidth|, but you can specified it explicitly: >
:HpGenerateContents 30
<
To update the contents after some file changes the |HpRefresh| exists. This
command updates sections and regenerates the contents. It can be invoked in
any place of the document.
Note: all commands are available only for 'help' files.
See more details in the section |hp-commands|.
1.1. Sections *hp-sections*
Every section in the documentation are considered as a part of the text from a
title of one section to a title of the next section. The title of a section
consists of the following parts: [{index}]{name}{tag}.
The {index} is an optional part of the title. It should contain numbers or
number signs (`#`) separated by the dot symbol. The last dot is optional. For
example: `1.` or `1.1` or `#.#` and so on. Also, you can mix numbers and
number signes: `1.#`.
The {tag} is a sequence of symbols between the `*` as it customary in Vim help.
The {name} is a trimmed sequence of symbols between index (or beginning of the
line) and tag.
1.2. Example *hp-example*
Let's see an example. We wrote our documentation with two sections:
Usage and License.
>
1 ▉
2 ==============================
3 1. Usage *usage*
4 Some text...
5
6 2. License *license*
7 Some text...
<
Now, we want to build the Contents of our documentation. To do so, we should
put the cursor to the place where the contents should be (position 1:1 in the
example above) and run command `:HpGenerateContents`. It inserts the contents
and move tags in the titles of sections to the right side:
>
1 CONTENTS
2 1. Usage.............|usage|
3 2. License.........|license|
4 ==============================
5 1. Usage *usage*
6 Some text...
7
8 2. License *license*
9 Some text...
<
Then we decided to add one more section in the middle, let's it be a section
Commands. We can set number 2 for the new section, or let the plugin choose a
number:
>
1 CONTENTS
2 1. Usage.............|usage|
3 2. License.........|license|
4 ==============================
5 1. Usage *usage*
6 Some text...
7
8 #. Commands *commands*
9 Some text...
10
11 2. License *license*
12 Some text...
<
The command `:HpRefresh` will update both the contents and titles:
>
1 CONTENTS
2 1. Usage.............|usage|
3 2. Commands.......|commands|
4 3. License.........|license|
5 ==============================
6 1. Usage *usage*
7 Some text...
8
9 2. Commands *commands*
10 Some text...
11
12 3. License *license*
13 Some text...
<
==============================================================================
2. Commands *hp-commands*
The following commands are provided by vim-hp for buffers with |filetype| `help`:
* |HpGenerateContents|
* |HpRefresh|
* |LeftRight|
*HpGenerateContents*
:HpGenerateContents [{width}] Generates a contents of the current buffer and
put it under cursor. If {width} is specified
then contents will take only {width} columns.
If {width} is absent then |textwidth| will be
used, or 80 when |textwidth| is 0.
*HpRefresh*
:HpRefresh Updates a sequential numbers of sections
according to their actual order. Then
regenerates a contents. If the contents is not
found, this command will throw an exception
with advice to generate a contents.
*LeftRight*
:LeftRight Moves a text before cursor to the left part of
the document and other text to the right part
according to the |textwidth|.
Example: >
some line of the text
^
cursor is here
:LeftRight
some line of the text
<
vim:tw=78:ts=8:noet:ft=help:norl: