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 @findex eww-toggle-paragraph-direction
220 @cindex paragraph direction
221 The @kbd{D} command (@code{eww-toggle-paragraph-direction}) toggles
222 the paragraphs direction between left-to-right and right-to-left
223 text. This can be useful on web pages that display right-to-left test
224 (like Arabic and Hebrew), but where the web pages don't explicitly
225 state the directionality.
227 @c @vindex shr-bullet
228 @c @vindex shr-hr-line
229 @c @vindex eww-form-checkbox-selected-symbol
230 @c @vindex eww-form-checkbox-symbol
231 @c EWW and the rendering engine shr.el use ASCII characters to
232 @c represent some graphical elements, such as bullet points
233 @c (@code{shr-bullet}), check boxes
234 @c (@code{eww-form-checkbox-selected-symbol} and
235 @c @code{eww-form-checkbox-symbol}), and horizontal rules
236 @c @code{shr-hr-line}). Depending on your fonts these characters can be
237 @c replaced by Unicode glyphs to achieve better looking results.
239 @vindex shr-max-image-proportion
240 @vindex shr-blocked-images
241 @cindex Image Display
242 Loading random images from the web can be problematic due to their
243 size or content. By customizing @code{shr-max-image-proportion} you
244 can set the maximal image proportion in relation to the window they
245 are displayed in. E.g., 0.7 means an image is allowed to take up 70%
246 of the width and height. If Emacs supports image scaling (ImageMagick
247 support required) then larger images are scaled down. You can block
248 specific images completely by customizing @code{shr-blocked-images}.
250 @vindex shr-color-visible-distance-min
251 @vindex shr-color-visible-luminance-min
253 EWW (or rather its HTML renderer @code{shr}) uses the colors declared
254 in the HTML page, but adjusts them if needed to keep a certain minimum
255 contrast. If that is still too low for you, you can customize the
256 variables @code{shr-color-visible-distance-min} and
257 @code{shr-color-visible-luminance-min} to get a better contrast.
259 @cindex Desktop Support
260 @cindex Saving Sessions
261 In addition to maintaining the history at run-time, EWW will also
262 save the partial state of its buffers (the URIs and the titles of the
263 pages visited) in the desktop file if one is used. @xref{Saving Emacs
264 Sessions,,, emacs, The GNU Emacs Manual}.
266 @vindex eww-desktop-remove-duplicates
267 EWW history may sensibly contain multiple entries for the same page
268 URI@. At run-time, these entries may still have different associated
269 point positions or the actual Web page contents.
270 The latter, however, tend to be overly large to preserve in the
271 desktop file, so they get omitted, thus rendering the respective
272 entries entirely equivalent. By default, such duplicate entries are
273 not saved. Setting @code{eww-desktop-remove-duplicates} to nil will
274 force EWW to save them anyway.
276 @vindex eww-restore-desktop
277 Restoring EWW buffers' contents may prove to take too long to
278 finish. When the @code{eww-restore-desktop} variable is set to
279 @code{nil} (the default), EWW will not try to reload the last visited
280 Web page when the buffer is restored from the desktop file, thus
281 allowing for faster Emacs start-up times. When set to @code{t},
282 restoring the buffers will also initiate the reloading of such pages.
284 @vindex eww-restore-reload-prompt
285 The EWW buffer restored from the desktop file but not yet reloaded
286 will contain a prompt, as specified by the
287 @code{eww-restore-reload-prompt} variable. The value of this variable
288 will be passed through @code{substitute-command-keys} upon each use,
289 thus allowing for the use of the usual substitutions, such as
290 @code{\[eww-reload]} for the current key binding of the
291 @code{eww-reload} command.
293 @node History and Acknowledgments
294 @appendix History and Acknowledgments
296 EWW was originally written by Lars Ingebrigtsen, known for his work on
297 Gnus. He started writing an Emacs HTML rendering library,
298 @code{shr.el}, to read blogs in Gnus. He eventually added a web
299 browser front end and HTML form support. Which resulted in EWW, the
300 Emacs Web Wowser. EWW was announced on 16 June 2013:
301 @url{http://lars.ingebrigtsen.no/2013/06/16/eww/}.
303 EWW was then moved from the Gnus repository to GNU Emacs and several
304 developers started contributing to it as well.
306 @node GNU Free Documentation License
307 @chapter GNU Free Documentation License
308 @include doclicense.texi
311 @unnumbered Key Index
316 @unnumbered Variable Index
318 @vindex eww-after-render-hook
319 After eww has rendered the data in the buffer,
320 @code{eww-after-render-hook} is called. It can be used to alter the
321 contents, for instance.
325 @node Lisp Function Index
326 @unnumbered Function Index
331 @unnumbered Concept Index