-
Notifications
You must be signed in to change notification settings - Fork 3
/
opener.texi
191 lines (144 loc) · 5.41 KB
/
opener.texi
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
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename opener.info
@settitle opener Manual 0.2
@c %**end of header
@copying
This manual is for opener version 0.2.
Copyright @copyright{} 2016 Tim Reddehase
@quotation
All rights reserved. This manual must accompany the source code of the
opener.el package.
@end quotation
@end copying
@dircategory Emacs lisp libraries
@direntry
* opener: (opener). Seamlessly open files via http(s) in buffer.
@end direntry
@titlepage
@title opener.el Manual
@author Tim Reddehase
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@node Top
@top Top
This manual is for opener.el, version 0.2.
@menu
* Overview::
* Installing::
* Using opener::
@end menu
@node Overview
@chapter Overview
Opener is a small package that makes it possible to open URLs directly
in a buffer, instead of going the way of downloading the corresponding
file with your browser and then opening that file manually. Users of
@emph{vim} might be familar that behaviour already, since it is built
into @emph{vim}.
However opener doesn't just open any URL in buffer, only those that it
determines correspond to a classic file. The simple reason for that
is, that normal webpages aren't really intended to be read via
source-code. Therefore those URLs are still opened in your favorite
browser. For information on how to customize the workflow and how to
force it to open in a buffer, see @ref{Using opener}.
@node Installing
@chapter Installing
It is recommended to install opener.el via the MELPA package
repository. However, it is still (as always) possible to do it by
hand:
To manually install opener.el, clone the git repository it into a
location of your choice (usually within your @code{~/.emacs.d}) and
add that location to your @code{load-path}.
@section Installing from MELPA
Follow these steps to install Octopress.el from the MELPA repository.
@lisp
(require 'package)
(add-to-list 'package-archives
'("melpa" . "http://melpa.org/packages/") t)
@end lisp
@noindent
Then refresh your packages list:
@example
M-x package-refresh-contents RET
@end example
@noindent
And finally, install opener.el:
@example
M-x package-install RET opener RET
@end example
@section Activating evil-mappings
You'll need to require the @emph{evil-opener} package instead.
@node Using opener
@chapter Using opener
@emph{Info:} The combination of opener with evil is optional, though
highly recommended.
@itemize @bullet
@item
@command{opener-open}, will query the user for a URL or FILE to open.
Provide a universal argument to force the function to open URL in a
buffer instead of applying file-like-url checking semantics.
@item
@command{opener-open-at-point}, opens a URL or file at point. Always applies
file-like-url checking semantics.
@end itemize
@section Customizing opener to my needs
Opener defines a small number of variables that can be used to
customize the behaviour and make it feel as smooth as you like it to
be.
@subsection After buffer-load hooks
In the web data is often minified, to save space and to reduce
transfer-costs (usually time). A typical use-case would be therefore
to unminify the resulting buffer if possible, in order to make it
actually human-readable. The @var{opener-major-mode-hooks} variable
allows you to hook functions into specific major-modes that are to be
executed when the URL is opened via opener. While it is always
possible to just attach these hooks functions to the major-mode
anyway, it would waste computing power to do this for normal files.
The variable contains a list of tuples (assoc-list) that maps a
major-mode to a list of hook-functions that are to be executed in
order and with the corresponding buffer set as the current-buffer. The
functions take no arguments.
@lisp
(defun nxml-pretty-format ()
(interactive)
(save-excursion
(shell-command-on-region (point-min) (point-max) "xmllint --format -" (buffer-name) t)
(nxml-mode)
(deactivate-mark t)))
(setq-default opener-major-mode-hooks
'((nxml-mode (nxml-pretty-format))))
@end lisp
The example will auto-format and indent the buffer contents of a XML
file using the @command{xmllint} binary.
@subsection Choose a custom browser
The @var{opener-url-browser-function} variable holds the reference to
a function that can open a URL with the semantics of a browser. It
defaults to @code{'browse-url}, which should work in most (if not all)
cases. However this variable can be customized to either force a
specific browser, provide an own implementation or to (for example)
start xwidgets instead. In any case the function is expected to take
one argument, the URL.
@lisp
(setq-default opener-url-browser-function
'xwidget-webkit-browse-url)
@end lisp
@section @anchor{What is a classic file-URL?}What is a classic file-URL?
Although not defined like that, there are historically two types of
used URLs. One is called the @emph{directory}-type and corresponds to
URLs which path looks like it would correspond to a directory on a
UNIX filesystem. For example
@example
@indicateurl{http://example.com/my-directory/is-this-one/} or
@indicateurl{http://example.com/my-directory}.
@end example
However there are also URLs which much
more clearly seem to resemble a file in the path-section of the URL, for example
@example
@indicateurl{http://example.com/sitemap.xml.gz} or
@indicateurl{http://example.com/index.html}.
@end example
We call these file-URLs in this manual, as it pertains to the kind of
URLs that will be handled by opener.