-
Notifications
You must be signed in to change notification settings - Fork 20
/
investigate.txt
266 lines (201 loc) · 12.7 KB
/
investigate.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
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
*investigate.txt* Last change: 2013 Dec
____ __ _ __
/ _/___ _ _____ _____/ /_(_)___ _____ _/ /____
/ // __ \ | / / _ \/ ___/ __/ / __ `/ __ `/ __/ _ \
_/ // / / / |/ / __(__ ) /_/ / /_/ / /_/ / /_/ __/
/___/_/ /_/|___/\___/____/\__/_/\__, /\__,_/\__/\___/
/____/
==============================================================================
CONTENTS *investigate*
1. Intro...................................|investigate-intro|
2. Functionality...........................|investigate-functionality|
3. Configuration Options...................|investigate-configuration|
3.1 Variables..........................|investigate-variables|
3.2 Conf File..........................|investigate-conf-file|
3.3 Writing Commands...................|investigate-writing-commands|
4. About...................................|investigate-about|
5. License.................................|investigate-license|
6. Thanks..................................|investigate-thanks|
==============================================================================
1. Intro *investigate-intro*
Investigate is a plugin for viewing language documentation for the word under
the cursor.
By default investigate is mapped to 'gK'. If you want to set up your
own mapping you should use something like this:
nnoremap <leader>K :call investigate#Investigate('n')<CR>
vnoremap <leader>K :call investigate#Investigate('v')<CR>
==============================================================================
2. Functionality *investigate-functionality*
Documentation can be viewed a few different ways. Using a custom command for a
file type that allows arbitrary commands to be run such as :h for vim. Using
Dash.app on Mac OS X. Or on the web. You can override any of the default
settings to make documentation open however you'd like using these methods.
==============================================================================
3. Configuration *investigate-configuration*
Investigate provides tons of configurations to allow all language defaults to
be overridden on a global and per project basis. This can be done by setting
global vim variables or using a '.investigaterc' file in the root of the
directory vim is running from.
------------------------------------------------------------------------------
3.1 Variables *investigate-variables*
There are quite a few different options that can be specified to change the
default settings, or add support for other languages. If you do want to add
other language support to investigate or change the default settings please
submit a pull request to the Github repository. If at anytime there are no
commands for the given filetype an error will be provided shown in the
command line. Please submit pull requests for any languages you would like
to see added to investigate.
*investigate_use_dash*
Default: 0
Set this variable to automatically open documentation in Dash.app when
you're on Mac OS X. If you're not on Mac OS X and this variable is set it
is ignored.
let g:investigate_use_dash=1
Download Dash for OS X from http://kapeli.com/dash
*investigate_dash_format*
This variable is set automatically by investigate depending on whether the
current version of Dash supports the dash-plugin URL scheme. In theory you
could set this if you noticed a slow down on the first dash query each time
you opened Vim. In practice this shouldn't have much of an effect.
*investigate_use_command_for_<filetype>*
Tell investigate to use the custom command for a specific filetype. Since,
behind the scenes the custom command is the highest priority of command to
be run, you typically shouldn't need this. If you set this it will
automatically use a custom command for the filetype. It will first attempt
to run the command defined by |investigate_command_for_<filetype>| if there
is one, otherwise it will attempt to run the predefined custom command.
Setting this any of these to 0 will be useless. But you know, if you want..
let g:investigate_use_command_for_ruby=1
*investigate_use_dash_for_<filetype>*
Tell investigate to prioritize opening documentation in Dash.app over using
a custom command. You would want to use this if, for example, you wanted to
open Vim's documentation in Dash over opening it with :h. This will default
to using the Dash keyword defined by |investigate_dash_for_<filetype>| if
there is one, otherwise it will use the predefined Dash keyword.
let g:investigate_use_dash_for_vim=1
*investigate_use_url_for_<filetype>*
Tell investigate to prioritize the URL documentation viewer for the filetype.
You would use this if you wanted to make investigate show the documentation
on the web over showing a custom command or the dash page. For example if
you wanted to open most languages in Dash but wanted to open Rails
documentation in their awesome online API viewer you could set that up.
let g:investigate_use_url_for_rails=1
*investigate_syntax_for_<filetype>*
This variable by filetype allows you to alias one filetype to another. This
is evaluated before any other mappings. This means if you override the URL
settings for filetypeA and then alias filetypeB to filetypeA, filetypeB will
use the overridden URL. An real example being help which is mapped to vim by
default. Example:
let g:investigate_syntax_for_rspec="ruby"
*investigate_command_for_<filetype>*
This variable allows you to set specific commands for a specific filetype.
See |investigate-writing-commands| for the setup on how to write the commands
with the correct replacements. This overrides the current set custom command
or it sets another command. I could imagine you attempting to set ri as the
default command for Ruby syntaxes. I haven't thought of a way to do that but
if you do I'd love to know about it! Here's what it would look like if the
default for vim hadn't already been set up.
let g:investigate_command_for_vim="^i:h ^s"
*investigate_dash_for_<filetype>*
This variable allows you to set specific Dash keywords for filetypes. You
would probably want to use this if you set up search profiles or changed then
names of any the default docsets in Dash to something more useful. You don't
need to add the : at the end of the keyword. If you are using a version of
Dash greater than 1.9.3 then investigate will use the dash-plugin URL scheme
which means you shouldn't have to change this option if you've just changed
the default name for a docset. This remaps all ruby files to open the rails
documentation:
let g:investigate_dash_for_ruby="rails"
*investigate_url_for_<filetype>*
This variable allows you to set the URL for a filetype to search through. See
|investigate-writing-commands| to see the exact syntax mapping a URL. You'd
want to do this if you don't agree with the site I picked to search for the
specific filetype. If you have a better one I'd love to hear about it via a
pull request. This is the default ruby URL but if you were redefining it:
let g:investigate_url_for_ruby="http://ruby-doc.com/search.html?q=^s"
------------------------------------------------------------------------------
3.2 Configuration File *investigate-conf-file*
In the root of any directory a file can be created. This will
redefine the behavior of investigate when it's being run from that directory.
A simple example of this is a Rails project where you want to open the
documentation for Ruby files in the Rails API reference rather than Ruby's.
Lines starting with # are considered comments. In brackets you can put any
keyword that is an investigate variable. The current keywords are syntax,
command, dash, and url.
*investigate_local_filename*
Default: ".invrc"
You can change the default name of the configuration file with this variable.
If you don't want the file to be hidden you can leave off the preceding dot.
let g:investigate_local_filename=".investigaterc"
The contents of this file are expanded to look like:
let g:investigate_<identifier>_for_<left>=<right>
Where <identifier> is the last word wrapped by brackets, <left> and <right>
are what's on the left and right side of the equals sign respectively.
Example:
# Open ruby files as rails
[syntax]
ruby=rails
# Custom command for vim
# This is the default command for vim
# This syntax is explained in |investigate-writing-commands|
[command]
vim=^i:h ^s
# Reassigns the dash identifier for a filetype
[dash]
html=web
css=web
# Default to Python 3 documentation
[url]
python="http://docs.python.org/3/search.html?q=^s"
------------------------------------------------------------------------------
3.3 Writing Commands *investigate-writing-commands*
Custom commands have 3 special identifiers for you to use.
^s - This is replaced with the search string from under the cursor
^x - This is replaced with the URL escaped word from under the cursor
^e - This is replaced with the executable for the current system
^i - This tells investigate not to prepend the executable
If your command needs to use the same executable investigate uses to open
URLs or Dash on OS X, you can leave the command without ^e and it will be
prepended automatically. If your command ends up starting with the executable
it will be run in vim with the 'system()' command. Otherwise it will be run as
is. So for example, if you wanted to run Ruby documentation through the ri
command line tool, you could do something like "^i!ri ^s" which, if activated
over the word "strip", would give call "!ri strip" to be executed by vim. If you
didn't use ^i at the beginning it would give you "open !ri strip" (on OS X)
which probably wouldn't make sense. All occurrences of each of these
identifiers are replaced globally. I chose "^" since it is not a valid
character in a URL where something else like %s could occur naturally and mess
up investigate.
==============================================================================
4. About *investigate-about*
Investigate was created and is maintained by Keith Smiley
<[email protected]> at https://github.com/Keithbsmiley/investigate.vim
Any feature requests or bug reports should be submitted on the Github
repository.
==============================================================================
5. License *investigate-license*
Investigate is licensed under MIT. The full text (as found in LICENSE):
Copyright (c) 2013 Keith Smiley (http://keith.so)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the 'Software'), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
==============================================================================
6. Thanks *investigate-thanks*
Some awesome people and projects that helped develop this plugin:
Steve Losh - http://learnvimscriptthehardway.stevelosh.com/
Syntastic - https://github.com/scrooloose/syntastic
Tim Pope - http://tpo.pe/
==============================================================================
vim:tw=78:et:ft=help:norl:isk+=-:ts=4:sw=4:sts=4