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