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