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.
113 @vindex eww-download-directory
116 A URL under the point can be downloaded with @kbd{d}
117 (@code{eww-download}). The file will be written to the directory
118 specified in @code{eww-download-directory} (Default: @file{~/Downloads/}).
121 @findex eww-forward-url
122 @findex eww-list-histories
127 EWW remembers the URLs you have visited to allow you to go back and
128 forth between them. By pressing @kbd{l} (@code{eww-back-url}) you go
129 to the previous URL@. You can go forward again with @kbd{r}
130 (@code{eww-forward-url}). If you want an overview of your browsing
131 history press @kbd{H} (@code{eww-list-histories}) to open the history
132 buffer @file{*eww history*}. The history is lost when EWW is quit.
133 If you want to remember websites you can use bookmarks.
135 @vindex eww-history-limit
136 Along with the URLs visited, EWW also remembers both the rendered
137 page (as it appears in the buffer) and its source. This can take a
138 considerable amount of memory, so EWW discards the history entries to
139 keep their number within a set limit, as specified by
140 @code{eww-history-limit}; the default being 50. This variable could
141 also be set to @code{nil} to allow for the history list to grow
145 PDFs are viewed inline, by default, with @code{doc-view-mode}, but
146 this can be customized by using the mailcap (@pxref{mailcap,,,
147 emacs-mime, Emacs MIME Manual})
148 mechanism, in particular @code{mailcap-mime-data}.
150 @findex eww-add-bookmark
151 @findex eww-list-bookmarks
155 EWW allows you to @dfn{bookmark} URLs. Simply hit @kbd{b}
156 (@code{eww-add-bookmark}) to store a bookmark for the current website.
157 You can view stored bookmarks with @kbd{B}
158 (@code{eww-list-bookmarks}). This will open the bookmark buffer
159 @file{*eww bookmarks*}.
161 @findex eww-list-buffers
163 @cindex Multiple Buffers
164 To get summary of currently opened EWW buffers, press @kbd{S}
165 (@code{eww-list-buffers}). The @file{*eww buffers*} buffer allows to
166 quickly kill, flip through and switch to specific EWW buffer.
168 @findex eww-browse-with-external-browser
169 @vindex shr-external-browser
170 @vindex eww-use-external-browser-for-content-type
172 @cindex External Browser
173 Although EWW and shr.el do their best to render webpages in GNU
174 Emacs some websites use features which can not be properly represented
175 or are not implemented (E.g., JavaScript). If you have trouble
176 viewing a website with EWW then hit @kbd{&}
177 (@code{eww-browse-with-external-browser}) inside the EWW buffer to
178 open the website in the external browser specified by
179 @code{shr-external-browser}. Some content types, such as video or
180 audio content, do not make sense to display in GNU Emacs at all. You
181 can tell EWW to open specific content automatically in an external
182 browser by customizing
183 @code{eww-use-external-browser-for-content-type}.
188 @findex eww-view-source
190 @cindex Viewing Source
191 You can view the source of a website with @kbd{v}
192 (@code{eww-view-source}). This will open a new buffer
193 @file{*eww-source*} and insert the source. The buffer will be set to
194 @code{html-mode} if available.
196 @findex url-cookie-list
199 EWW handles cookies through the @ref{Top, url package, ,url}.
200 You can list existing cookies with @kbd{C} (@code{url-cookie-list}).
201 For details about the Cookie handling @xref{Cookies,,,url}.
203 @vindex eww-header-line-format
205 The header line of the EWW buffer can be changed by customizing
206 @code{eww-header-line-format}. The format replaces @code{%t} with the
207 title of the website and @code{%u} with the URL.
209 @c @vindex shr-bullet
210 @c @vindex shr-hr-line
211 @c @vindex eww-form-checkbox-selected-symbol
212 @c @vindex eww-form-checkbox-symbol
213 @c EWW and the rendering engine shr.el use ASCII characters to
214 @c represent some graphical elements, such as bullet points
215 @c (@code{shr-bullet}), check boxes
216 @c (@code{eww-form-checkbox-selected-symbol} and
217 @c @code{eww-form-checkbox-symbol}), and horizontal rules
218 @c @code{shr-hr-line}). Depending on your fonts these characters can be
219 @c replaced by Unicode glyphs to achieve better looking results.
221 @vindex shr-max-image-proportion
222 @vindex shr-blocked-images
223 @cindex Image Display
224 Loading random images from the web can be problematic due to their
225 size or content. By customizing @code{shr-max-image-proportion} you
226 can set the maximal image proportion in relation to the window they
227 are displayed in. E.g., 0.7 means an image is allowed to take up 70%
228 of the width and height. If Emacs supports image scaling (ImageMagick
229 support required) then larger images are scaled down. You can block
230 specific images completely by customizing @code{shr-blocked-images}.
232 @vindex shr-color-visible-distance-min
233 @vindex shr-color-visible-luminance-min
235 EWW (or rather its HTML renderer @code{shr}) uses the colors declared
236 in the HTML page, but adjusts them if needed to keep a certain minimum
237 contrast. If that is still too low for you, you can customize the
238 variables @code{shr-color-visible-distance-min} and
239 @code{shr-color-visible-luminance-min} to get a better contrast.
241 @cindex Desktop Support
242 @cindex Saving Sessions
243 In addition to maintaining the history at run-time, EWW will also
244 save the partial state of its buffers (the URIs and the titles of the
245 pages visited) in the desktop file if one is used. @xref{Saving Emacs
246 Sessions, , emacs, The GNU Emacs Manual}.
248 @vindex eww-desktop-remove-duplicates
249 EWW history may sensibly contain multiple entries for the same page
250 URI@. At run-time, these entries may still have different associated
251 point positions or the actual Web page contents.
252 The latter, however, tend to be overly large to preserve in the
253 desktop file, so they get omitted, thus rendering the respective
254 entries entirely equivalent. By default, such duplicate entries are
255 not saved. Setting @code{eww-desktop-remove-duplicates} to nil will
256 force EWW to save them anyway.
258 @vindex eww-restore-desktop
259 Restoring EWW buffers' contents may prove to take too long to
260 finish. When the @code{eww-restore-desktop} variable is set to
261 @code{nil} (the default), EWW will not try to reload the last visited
262 Web page when the buffer is restored from the desktop file, thus
263 allowing for faster Emacs start-up times. When set to @code{t},
264 restoring the buffers will also initiate the reloading of such pages.
266 @vindex eww-restore-reload-prompt
267 The EWW buffer restored from the desktop file but not yet reloaded
268 will contain a prompt, as specified by the
269 @code{eww-restore-reload-prompt} variable. The value of this variable
270 will be passed through @code{substitute-command-keys} upon each use,
271 thus allowing for the use of the usual substitutions, such as
272 @code{\[eww-reload]} for the current key binding of the
273 @code{eww-reload} command.
275 @node History and Acknowledgments
276 @appendix History and Acknowledgments
278 EWW was originally written by Lars Ingebrigtsen, known for his work on
279 Gnus. He started writing an Emacs HTML rendering library,
280 @code{shr.el}, to read blogs in Gnus. He eventually added a web
281 browser front end and HTML form support. Which resulted in EWW, the
282 Emacs Web Wowser. EWW was announced on 16 June 2013:
283 @url{http://lars.ingebrigtsen.no/2013/06/16/eww/}.
285 EWW was then moved from the Gnus repository to GNU Emacs and several
286 developers started contributing to it as well.
288 @node GNU Free Documentation License
289 @chapter GNU Free Documentation License
290 @include doclicense.texi
293 @unnumbered Key Index
298 @unnumbered Variable Index
300 @vindex eww-after-render-hook
301 After eww has rendered the data in the buffer,
302 @code{eww-after-render-hook} is called. It can be used to alter the
303 contents, for instance.
307 @node Lisp Function Index
308 @unnumbered Function Index
313 @unnumbered Concept Index