1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../../info/eww.info
4 @settitle Emacs Web Wowser
9 This file documents the GNU Emacs Web Wowser (EWW) package.
11 Copyright @copyright{} 2014--2016 Free Software Foundation, Inc.
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.3 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
18 and with the Back-Cover Texts as in (a) below. A copy of the license
19 is included in the section entitled ``GNU Free Documentation License.''
21 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
22 modify this GNU manual.''
26 @dircategory Emacs misc features
28 * EWW: (eww). Emacs Web Wowser
34 @title Emacs Web Wowser (EWW)
35 @subtitle A web browser for GNU Emacs.
38 @vskip 0pt plus 1filll
57 * History and Acknowledgments::
58 * GNU Free Documentation License:: The license for this documentation.
63 * Lisp Function Index::
69 @dfn{EWW}, the Emacs Web Wowser, is a web browser for GNU Emacs. It
70 can load, parse, and display various web pages using @dfn{shr.el}.
71 However a GNU Emacs with @code{libxml2} support is required.
78 @vindex eww-search-prefix
81 You can open a URL or search the web with the command @kbd{M-x eww}.
82 If the input doesn't look like a URL or domain name the web will be
83 searched via @code{eww-search-prefix}. The default search engine is
84 @url{https://duckduckgo.com, DuckDuckGo}. If you want to open a file
85 either prefix the file name with @code{file://} or use the command
86 @kbd{M-x eww-open-file}.
90 @findex eww-copy-page-url
94 If loading the URL was successful the buffer @file{*eww*} is opened
95 and the web page is rendered in it. You can leave EWW by pressing
96 @kbd{q} or exit the browser by calling @kbd{eww-quit}. To reload the
97 web page hit @kbd{g} (@code{eww-reload}). Pressing @kbd{w}
98 (@code{eww-copy-page-url}) will copy the current URL to the kill ring.
102 The @kbd{R} command (@code{eww-readable}) will attempt to determine
103 which part of the document contains the ``readable'' text, and will
104 only display this part. This usually gets rid of menus and the like.
106 @findex eww-toggle-fonts
107 @findex shr-use-fonts
109 The @kbd{F} command (@code{eww-toggle-fonts}) toggles whether to use
110 variable-pitch fonts or not. This sets the @code{shr-use-fonts} variable.
112 @findex eww-toggle-colors
113 @findex shr-use-colors
115 The @kbd{C} command (@code{eww-toggle-colors}) toggles whether to use
116 HTML-specified colors or not. This sets the @code{shr-use-colors} variable.
119 @vindex eww-download-directory
122 A URL under the point can be downloaded with @kbd{d}
123 (@code{eww-download}). The file will be written to the directory
124 specified in @code{eww-download-directory} (Default: @file{~/Downloads/}).
127 @findex eww-forward-url
128 @findex eww-list-histories
133 EWW remembers the URLs you have visited to allow you to go back and
134 forth between them. By pressing @kbd{l} (@code{eww-back-url}) you go
135 to the previous URL@. You can go forward again with @kbd{r}
136 (@code{eww-forward-url}). If you want an overview of your browsing
137 history press @kbd{H} (@code{eww-list-histories}) to open the history
138 buffer @file{*eww history*}. The history is lost when EWW is quit.
139 If you want to remember websites you can use bookmarks.
141 @vindex eww-history-limit
142 Along with the URLs visited, EWW also remembers both the rendered
143 page (as it appears in the buffer) and its source. This can take a
144 considerable amount of memory, so EWW discards the history entries to
145 keep their number within a set limit, as specified by
146 @code{eww-history-limit}; the default being 50. This variable could
147 also be set to @code{nil} to allow for the history list to grow
151 PDFs are viewed inline, by default, with @code{doc-view-mode}, but
152 this can be customized by using the mailcap (@pxref{mailcap,,,
153 emacs-mime, Emacs MIME Manual})
154 mechanism, in particular @code{mailcap-mime-data}.
156 @findex eww-add-bookmark
157 @findex eww-list-bookmarks
161 EWW allows you to @dfn{bookmark} URLs. Simply hit @kbd{b}
162 (@code{eww-add-bookmark}) to store a bookmark for the current website.
163 You can view stored bookmarks with @kbd{B}
164 (@code{eww-list-bookmarks}). This will open the bookmark buffer
165 @file{*eww bookmarks*}.
167 @findex eww-switch-to-buffer
168 @findex eww-list-buffers
171 @cindex Multiple Buffers
172 To get summary of currently opened EWW buffers, press @kbd{S}
173 (@code{eww-list-buffers}). The @file{*eww buffers*} buffer allows you
174 to quickly kill, flip through and switch to specific EWW buffer. To
175 switch EWW buffers through a minibuffer prompt, press @kbd{s}
176 (@code{eww-switch-to-buffer}).
178 @findex eww-browse-with-external-browser
179 @vindex shr-external-browser
180 @vindex eww-use-external-browser-for-content-type
182 @cindex External Browser
183 Although EWW and shr.el do their best to render webpages in GNU
184 Emacs some websites use features which can not be properly represented
185 or are not implemented (E.g., JavaScript). If you have trouble
186 viewing a website with EWW then hit @kbd{&}
187 (@code{eww-browse-with-external-browser}) inside the EWW buffer to
188 open the website in the external browser specified by
189 @code{shr-external-browser}. Some content types, such as video or
190 audio content, do not make sense to display in GNU Emacs at all. You
191 can tell EWW to open specific content automatically in an external
192 browser by customizing
193 @code{eww-use-external-browser-for-content-type}.
198 @findex eww-view-source
200 @cindex Viewing Source
201 You can view the source of a website with @kbd{v}
202 (@code{eww-view-source}). This will open a new buffer
203 @file{*eww-source*} and insert the source. The buffer will be set to
204 @code{html-mode} if available.
206 @findex url-cookie-list
209 EWW handles cookies through the @ref{Top, url package, ,url}.
210 You can list existing cookies with @kbd{C} (@code{url-cookie-list}).
211 For details about the Cookie handling @xref{Cookies,,,url}.
213 @vindex eww-header-line-format
215 The header line of the EWW buffer can be changed by customizing
216 @code{eww-header-line-format}. The format replaces @code{%t} with the
217 title of the website and @code{%u} with the URL.
219 @c @vindex shr-bullet
220 @c @vindex shr-hr-line
221 @c @vindex eww-form-checkbox-selected-symbol
222 @c @vindex eww-form-checkbox-symbol
223 @c EWW and the rendering engine shr.el use ASCII characters to
224 @c represent some graphical elements, such as bullet points
225 @c (@code{shr-bullet}), check boxes
226 @c (@code{eww-form-checkbox-selected-symbol} and
227 @c @code{eww-form-checkbox-symbol}), and horizontal rules
228 @c @code{shr-hr-line}). Depending on your fonts these characters can be
229 @c replaced by Unicode glyphs to achieve better looking results.
231 @vindex shr-max-image-proportion
232 @vindex shr-blocked-images
233 @cindex Image Display
234 Loading random images from the web can be problematic due to their
235 size or content. By customizing @code{shr-max-image-proportion} you
236 can set the maximal image proportion in relation to the window they
237 are displayed in. E.g., 0.7 means an image is allowed to take up 70%
238 of the width and height. If Emacs supports image scaling (ImageMagick
239 support required) then larger images are scaled down. You can block
240 specific images completely by customizing @code{shr-blocked-images}.
242 @vindex shr-color-visible-distance-min
243 @vindex shr-color-visible-luminance-min
245 EWW (or rather its HTML renderer @code{shr}) uses the colors declared
246 in the HTML page, but adjusts them if needed to keep a certain minimum
247 contrast. If that is still too low for you, you can customize the
248 variables @code{shr-color-visible-distance-min} and
249 @code{shr-color-visible-luminance-min} to get a better contrast.
251 @cindex Desktop Support
252 @cindex Saving Sessions
253 In addition to maintaining the history at run-time, EWW will also
254 save the partial state of its buffers (the URIs and the titles of the
255 pages visited) in the desktop file if one is used. @xref{Saving Emacs
256 Sessions, , emacs, The GNU Emacs Manual}.
258 @vindex eww-desktop-remove-duplicates
259 EWW history may sensibly contain multiple entries for the same page
260 URI@. At run-time, these entries may still have different associated
261 point positions or the actual Web page contents.
262 The latter, however, tend to be overly large to preserve in the
263 desktop file, so they get omitted, thus rendering the respective
264 entries entirely equivalent. By default, such duplicate entries are
265 not saved. Setting @code{eww-desktop-remove-duplicates} to nil will
266 force EWW to save them anyway.
268 @vindex eww-restore-desktop
269 Restoring EWW buffers' contents may prove to take too long to
270 finish. When the @code{eww-restore-desktop} variable is set to
271 @code{nil} (the default), EWW will not try to reload the last visited
272 Web page when the buffer is restored from the desktop file, thus
273 allowing for faster Emacs start-up times. When set to @code{t},
274 restoring the buffers will also initiate the reloading of such pages.
276 @vindex eww-restore-reload-prompt
277 The EWW buffer restored from the desktop file but not yet reloaded
278 will contain a prompt, as specified by the
279 @code{eww-restore-reload-prompt} variable. The value of this variable
280 will be passed through @code{substitute-command-keys} upon each use,
281 thus allowing for the use of the usual substitutions, such as
282 @code{\[eww-reload]} for the current key binding of the
283 @code{eww-reload} command.
285 @node History and Acknowledgments
286 @appendix History and Acknowledgments
288 EWW was originally written by Lars Ingebrigtsen, known for his work on
289 Gnus. He started writing an Emacs HTML rendering library,
290 @code{shr.el}, to read blogs in Gnus. He eventually added a web
291 browser front end and HTML form support. Which resulted in EWW, the
292 Emacs Web Wowser. EWW was announced on 16 June 2013:
293 @url{http://lars.ingebrigtsen.no/2013/06/16/eww/}.
295 EWW was then moved from the Gnus repository to GNU Emacs and several
296 developers started contributing to it as well.
298 @node GNU Free Documentation License
299 @chapter GNU Free Documentation License
300 @include doclicense.texi
303 @unnumbered Key Index
308 @unnumbered Variable Index
310 @vindex eww-after-render-hook
311 After eww has rendered the data in the buffer,
312 @code{eww-after-render-hook} is called. It can be used to alter the
313 contents, for instance.
317 @node Lisp Function Index
318 @unnumbered Function Index
323 @unnumbered Concept Index