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--2015 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-list-buffers
169 @cindex Multiple Buffers
170 To get summary of currently opened EWW buffers, press @kbd{S}
171 (@code{eww-list-buffers}). The @file{*eww buffers*} buffer allows to
172 quickly kill, flip through and switch to specific EWW buffer.
174 @findex eww-browse-with-external-browser
175 @vindex shr-external-browser
176 @vindex eww-use-external-browser-for-content-type
178 @cindex External Browser
179 Although EWW and shr.el do their best to render webpages in GNU
180 Emacs some websites use features which can not be properly represented
181 or are not implemented (E.g., JavaScript). If you have trouble
182 viewing a website with EWW then hit @kbd{&}
183 (@code{eww-browse-with-external-browser}) inside the EWW buffer to
184 open the website in the external browser specified by
185 @code{shr-external-browser}. Some content types, such as video or
186 audio content, do not make sense to display in GNU Emacs at all. You
187 can tell EWW to open specific content automatically in an external
188 browser by customizing
189 @code{eww-use-external-browser-for-content-type}.
194 @findex eww-view-source
196 @cindex Viewing Source
197 You can view the source of a website with @kbd{v}
198 (@code{eww-view-source}). This will open a new buffer
199 @file{*eww-source*} and insert the source. The buffer will be set to
200 @code{html-mode} if available.
202 @findex url-cookie-list
205 EWW handles cookies through the @ref{Top, url package, ,url}.
206 You can list existing cookies with @kbd{C} (@code{url-cookie-list}).
207 For details about the Cookie handling @xref{Cookies,,,url}.
209 @vindex eww-header-line-format
211 The header line of the EWW buffer can be changed by customizing
212 @code{eww-header-line-format}. The format replaces @code{%t} with the
213 title of the website and @code{%u} with the URL.
215 @c @vindex shr-bullet
216 @c @vindex shr-hr-line
217 @c @vindex eww-form-checkbox-selected-symbol
218 @c @vindex eww-form-checkbox-symbol
219 @c EWW and the rendering engine shr.el use ASCII characters to
220 @c represent some graphical elements, such as bullet points
221 @c (@code{shr-bullet}), check boxes
222 @c (@code{eww-form-checkbox-selected-symbol} and
223 @c @code{eww-form-checkbox-symbol}), and horizontal rules
224 @c @code{shr-hr-line}). Depending on your fonts these characters can be
225 @c replaced by Unicode glyphs to achieve better looking results.
227 @vindex shr-max-image-proportion
228 @vindex shr-blocked-images
229 @cindex Image Display
230 Loading random images from the web can be problematic due to their
231 size or content. By customizing @code{shr-max-image-proportion} you
232 can set the maximal image proportion in relation to the window they
233 are displayed in. E.g., 0.7 means an image is allowed to take up 70%
234 of the width and height. If Emacs supports image scaling (ImageMagick
235 support required) then larger images are scaled down. You can block
236 specific images completely by customizing @code{shr-blocked-images}.
238 @vindex shr-color-visible-distance-min
239 @vindex shr-color-visible-luminance-min
241 EWW (or rather its HTML renderer @code{shr}) uses the colors declared
242 in the HTML page, but adjusts them if needed to keep a certain minimum
243 contrast. If that is still too low for you, you can customize the
244 variables @code{shr-color-visible-distance-min} and
245 @code{shr-color-visible-luminance-min} to get a better contrast.
247 @cindex Desktop Support
248 @cindex Saving Sessions
249 In addition to maintaining the history at run-time, EWW will also
250 save the partial state of its buffers (the URIs and the titles of the
251 pages visited) in the desktop file if one is used. @xref{Saving Emacs
252 Sessions, , emacs, The GNU Emacs Manual}.
254 @vindex eww-desktop-remove-duplicates
255 EWW history may sensibly contain multiple entries for the same page
256 URI@. At run-time, these entries may still have different associated
257 point positions or the actual Web page contents.
258 The latter, however, tend to be overly large to preserve in the
259 desktop file, so they get omitted, thus rendering the respective
260 entries entirely equivalent. By default, such duplicate entries are
261 not saved. Setting @code{eww-desktop-remove-duplicates} to nil will
262 force EWW to save them anyway.
264 @vindex eww-restore-desktop
265 Restoring EWW buffers' contents may prove to take too long to
266 finish. When the @code{eww-restore-desktop} variable is set to
267 @code{nil} (the default), EWW will not try to reload the last visited
268 Web page when the buffer is restored from the desktop file, thus
269 allowing for faster Emacs start-up times. When set to @code{t},
270 restoring the buffers will also initiate the reloading of such pages.
272 @vindex eww-restore-reload-prompt
273 The EWW buffer restored from the desktop file but not yet reloaded
274 will contain a prompt, as specified by the
275 @code{eww-restore-reload-prompt} variable. The value of this variable
276 will be passed through @code{substitute-command-keys} upon each use,
277 thus allowing for the use of the usual substitutions, such as
278 @code{\[eww-reload]} for the current key binding of the
279 @code{eww-reload} command.
281 @node History and Acknowledgments
282 @appendix History and Acknowledgments
284 EWW was originally written by Lars Ingebrigtsen, known for his work on
285 Gnus. He started writing an Emacs HTML rendering library,
286 @code{shr.el}, to read blogs in Gnus. He eventually added a web
287 browser front end and HTML form support. Which resulted in EWW, the
288 Emacs Web Wowser. EWW was announced on 16 June 2013:
289 @url{http://lars.ingebrigtsen.no/2013/06/16/eww/}.
291 EWW was then moved from the Gnus repository to GNU Emacs and several
292 developers started contributing to it as well.
294 @node GNU Free Documentation License
295 @chapter GNU Free Documentation License
296 @include doclicense.texi
299 @unnumbered Key Index
304 @unnumbered Variable Index
306 @vindex eww-after-render-hook
307 After eww has rendered the data in the buffer,
308 @code{eww-after-render-hook} is called. It can be used to alter the
309 contents, for instance.
313 @node Lisp Function Index
314 @unnumbered Function Index
319 @unnumbered Concept Index