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 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
138 @findex eww-add-bookmark
139 @findex eww-list-bookmarks
143 EWW allows you to @dfn{bookmark} URLs. Simply hit @kbd{b}
144 (@code{eww-add-bookmark}) to store a bookmark for the current website.
145 You can view stored bookmarks with @kbd{B}
146 (@code{eww-list-bookmarks}). This will open the bookmark buffer
147 @file{*eww bookmarks*}.
149 @findex eww-browse-with-external-browser
150 @vindex shr-external-browser
151 @vindex eww-use-external-browser-for-content-type
153 @cindex External Browser
154 Although EWW and shr.el do their best to render webpages in GNU
155 Emacs some websites use features which can not be properly represented
156 or are not implemented (E.g., JavaScript). If you have trouble
157 viewing a website with EWW then hit @kbd{&}
158 (@code{eww-browse-with-external-browser}) inside the EWW buffer to
159 open the website in the external browser specified by
160 @code{shr-external-browser}. Some content types, such as video or
161 audio content, do not make sense to display in GNU Emacs at all. You
162 can tell EWW to open specific content automatically in an external
163 browser by customizing
164 @code{eww-use-external-browser-for-content-type}.
169 @findex eww-view-source
171 @cindex Viewing Source
172 You can view the source of a website with @kbd{v}
173 (@code{eww-view-source}). This will open a new buffer
174 @file{*eww-source*} and insert the source. The buffer will be set to
175 @code{html-mode} if available.
177 @findex url-cookie-list
180 EWW handles cookies through the @ref{Top, url package, ,url}.
181 You can list existing cookies with @kbd{C} (@code{url-cookie-list}).
182 For details about the Cookie handling @xref{Cookies,,,url}.
184 @vindex eww-header-line-format
186 The header line of the EWW buffer can be changed by customizing
187 @code{eww-header-line-format}. The format replaces @code{%t} with the
188 title of the website and @code{%u} with the URL.
190 @c @vindex shr-bullet
191 @c @vindex shr-hr-line
192 @c @vindex eww-form-checkbox-selected-symbol
193 @c @vindex eww-form-checkbox-symbol
194 @c EWW and the rendering engine shr.el use ASCII characters to
195 @c represent some graphical elements, such as bullet points
196 @c (@code{shr-bullet}), check boxes
197 @c (@code{eww-form-checkbox-selected-symbol} and
198 @c @code{eww-form-checkbox-symbol}), and horizontal rules
199 @c @code{shr-hr-line}). Depending on your fonts these characters can be
200 @c replaced by Unicode glyphs to achieve better looking results.
202 @vindex shr-max-image-proportion
203 @vindex shr-blocked-images
204 @cindex Image Display
205 Loading random images from the web can be problematic due to their
206 size or content. By customizing @code{shr-max-image-proportion} you
207 can set the maximal image proportion in relation to the window they
208 are displayed in. E.g., 0.7 means an image is allowed to take up 70%
209 of the width and height. If Emacs supports image scaling (ImageMagick
210 support required) then larger images are scaled down. You can block
211 specific images completely by customizing @code{shr-blocked-images}.
213 @vindex shr-color-visible-distance-min
214 @vindex shr-color-visible-luminance-min
216 EWW (or rather its HTML renderer @code{shr}) uses the colors declared
217 in the HTML page, but adjusts them if needed to keep a certain minimum
218 contrast. If that is still too low for you, you can customize the
219 variables @code{shr-color-visible-distance-min} and
220 @code{shr-color-visible-luminance-min} to get a better contrast.
222 @node History and Acknowledgments
223 @appendix History and Acknowledgments
225 EWW was originally written by Lars Ingebrigtsen, known for his work on
226 Gnus. He started writing an Emacs HTML rendering library,
227 @code{shr.el}, to read blogs in Gnus. He eventually added a web
228 browser front end and HTML form support. Which resulted in EWW, the
229 Emacs Web Wowser. EWW was announced on 16 June 2013:
230 @url{http://lars.ingebrigtsen.no/2013/06/16/eww/}.
232 EWW was then moved from the Gnus repository to GNU Emacs and several
233 developers started contributing to it as well.
235 @node GNU Free Documentation License
236 @chapter GNU Free Documentation License
237 @include doclicense.texi
240 @unnumbered Key Index
245 @unnumbered Variable Index
247 @vindex eww-after-render-hook
248 After eww has rendered the data in the buffer,
249 @code{eww-after-render-hook} is called. It can be used to alter the
250 contents, for instance.
254 @node Lisp Function Index
255 @unnumbered Function Index
260 @unnumbered Concept Index