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