-
Notifications
You must be signed in to change notification settings - Fork 3
/
rel.txt
219 lines (157 loc) · 7.63 KB
/
rel.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
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
*rel.txt* Define and follow links to resources with *Rel*
==============================================================================
_____ _____ ____ __ __ ___ __ __ ~
/ _ \/ __\/ _/ / | \/___\/ \/ \ ~
| _ <| __|| |--- \ | /| || \/ | ~
\__|\_/\_____/\_____/<_>\___/ \___/\__/\__/ ~
Resource Linking for Vim ~
=================================================================== v0.3.0 ===
DESCRIPTION *rel-description*
Press `<C-k>` in normal mode to follow the link under the cursor. If the link
begins with a `scheme:` it will be resolved to determine how to open the link.
If a link ends in a known suffix it will be opened by the associated program.
Links opened in vim may contain a fragment part to determine where to place
the cursor in the newly opened file.
*rel-links*
RELs ~
The links that `rel.vim` uses consist of only non-whitespace characters except
" < and >. Special characters can be included as escaped URL entities, ie. to
include a space character in a link you can use `%20`.
If the tilde `~` character appears at the beginning of a link it is expanded
to the value of `$HOME`.
*rel-fragments*
Fragments ~
Links to text files opened in vim may be suffixed with a fragment part that
determines where to place the cursor in the newly opened buffer.
A Line fragment (`#:<line>[:<column>]`) places the cursor on a specific
line and optionally in a specific column. A search fragment (`#/<text>`) finds
a text in the opened file to place the cursor over.
For example the link: >
~/.vimrc#:10
<
will place the cursor on line 10 of the `$HOME/.vimrc` file and >
~/.vimrc#:10:4
<
will place the cursor on line 10 column 4. The text fragment >
~/.vimrc#/set
<
will place the cursor at the first occurrence of the string "set" in the
`.vimrc` file.
Note that fragments function only for text files opened in vim and for the
built in `help:` and `man:` schemes.
*rel-suffix*
Suffixes ~
A map between a suffix and a program can be defined in |g:rel_extmap| to
determine which program to use to open links with a specific suffix.
*rel-schemes*
Schemes ~
This plugin defines 2 special schemes, `help:` to lookup vim help files and
`man:` to use the |man.vim| script to read man pages. For example >
help:rel.txt#/should%20refer
<
should refer to this sentence. Note that `%20` is translated to the space
character.
If `man.vim` is loaded then following the link: >
man:vim#/^ON-LINE
<
should open the vim man page using the |:Man| command.
Finally, if an `http://`, `https://` or `ftp://` URL is encountered the
command in |g:rel_http| will be run, passing the url to open it.
See |g:rel_schemes| on how to define more schemes.
CONFIGURATION *rel-config*
*rel-map*
Map ~
You can map a key combination of your liking to `<Plug>(Rel)` to follow a
link. If no map exists the default is: >
:nmap <C-k> <Plug>(Rel)
<
*g:rel_http*
Http browser ~
Change the program to run when opening an `http` or `https` URL: >
let g:rel_http = 'firefox %s'
<
The string `%s` will be replaced with the link.
*g:rel_open*
Opening a buffer ~
Change `g:rel_open` to determine how a buffer should be opened when following
a link: >
let g:rel_open = 'vsplit'
>
Set this to one of the vim commands used to open a file: |:tabnew|, |:vsplit|,
|:split|. Note that this does not affect how `man:` links are opened. See
|:Man| on how to change how the buffer for man pages is opened.
*g:rel_modifiers*
The value of `g:rel_modifiers` determines how to open a buffer when
`g:rel_open` is not |:tabnew|. For possible values, see |:vert|.
*g:rel_extmap*
External programs ~
You can define a dictionary of extensions mapping to programs to determine how
files with this suffix should be opened. The default value is: >
let g:rel_extmap = {
\ 'html': 'firefox %s'
\ }
<
In the rhs of these maps `%s` will be replaced with the link to the file.
*g:rel_schemes*
Custom schemes ~
The variable `g:rel_schemes` may contain a mapping between a scheme and a
string or a function to rewrite the link to determine how that link should be
opened. Once the link has been rewritten all of the known methods of opening
links are tried again. This allows rewriting links several times over.
String scheme value ~
If the value in the mapping dictionary is a string it may contain the special
strings `%p`, which will be replaced with the path part of the link and `%f`,
which will be replaced with the fragment part. This can be used to create
shortcuts to paths. For example: >
let g:rel_schemes = {
\ 'plugin': $HOME . '/.vim/plugin/%p.vim#%f'
\ }
<
would allow referring to a file in the local vim plugins using only the files
basename, for example: >
plugin:mark#:20
<
would refer to line 20 of the `$HOME/.vim/plugin/mark.vim` file, if it exists.
Function scheme value ~
If the value in the `g:rel_schemes` dictionary is a |Funcref| then it is
called with a List of `[full_link, path_part, fragment_part]` and what this
function returns will determines what will happen. Returning
- `"a string"` will cause this string to be passed to each of the known
methods for opening links, possibly opening the link.
- the value `1` indicates that the function has opened the link and no further
methods will be tried.
- the value `0` indicates that the function could not open the link and the
remaining methods should be tried.
TODO Add an example
*g:rel_highlight*
Syntax highlight links ~
Set this to a value above 0 to get syntax highlighting of text that looks like
links that would be followed. More is highlighted the higher the value.
Setting >
let g:rel_highlight = 1
<
will highlight links defined as part of a scheme in |g:rel_schemes|. >
let g:rel_highlight = 2
<
will also highlight links with the known suffixes in |g:rel_extmap|. >
let g:rel_highlight = 3
<
will highlight all text that includes a `#:` or `#/` fragment. >
let g:rel_highlight = 4
<
will also highlight http, https and ftp URLs. >
Finally go bananas and try to highlight everything that looks remotely like a
link by setting >
let g:rel_highlight = 5
<
The default is a value of 3.
*g:rel_link_chars*
Link Characters ~
TODO
ABOUT *rel-about*
The inspiration for this script came from `UTL.vim`, which has similar goals,
see http://www.vim.org/scripts/script.php?script_id=293
The latest version of `rel.vim` is available on GitHub:
http://github.com/aklt/vim-rel
Released under the same terms as vim, see |license|
vim:tw=78:et:ft=help:norl: