doc/misc/eww.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename ../../info/eww.info
   4 @settitle Emacs Web Wowser
   5 @include docstyle.texi
   6 @c %**end of header
   7
   8 @copying
   9 This file documents the GNU Emacs Web Wowser (EWW) package.
  10
  11 Copyright @copyright{} 2014--2017 Free Software Foundation, Inc.
  12
  13 @quotation
  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.''
  20
  21 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  22 modify this GNU manual.''
  23 @end quotation
  24 @end copying
  25
  26 @dircategory Emacs misc features
  27 @direntry
  28 * EWW: (eww).      Emacs Web Wowser
  29 @end direntry
  30
  31 @finalout
  32
  33 @titlepage
  34 @title Emacs Web Wowser (EWW)
  35 @subtitle A web browser for GNU Emacs.
  36
  37 @page
  38 @vskip 0pt plus 1filll
  39 @insertcopying
  40 @end titlepage
  41
  42 @contents
  43
  44 @ifnottex
  45 @node Top
  46 @top EWW
  47
  48 @insertcopying
  49 @end ifnottex
  50
  51 @menu
  52 * Overview::
  53 * Basics::
  54 * Advanced::
  55
  56 Appendices
  57 * History and Acknowledgments::
  58 * GNU Free Documentation License::  The license for this documentation.
  59
  60 Indices
  61 * Key Index::
  62 * Variable Index::
  63 * Lisp Function Index::
  64 * Concept Index::
  65 @end menu
  66
  67 @node Overview
  68 @chapter Overview
  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.
  72
  73 @node Basics
  74 @chapter Basic Usage
  75
  76 @findex eww
  77 @findex eww-open-file
  78 @vindex eww-search-prefix
  79 @cindex eww
  80 @cindex Web Browsing
  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}.
  87
  88 @findex eww-quit
  89 @findex eww-reload
  90 @findex eww-copy-page-url
  91 @kindex q
  92 @kindex w
  93 @kindex g
  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.
  99
 100 @findex eww-open-in-new-buffer
 101 @kindex M-RET
 102   The @kbd{M-RET} command (@code{eww-open-in-new-buffer}) opens the
 103 URL at point in a new EWW buffer, akin to opening a link in a new
 104 ``tab'' in other browsers.
 105
 106 @findex eww-readable
 107 @kindex R
 108   The @kbd{R} command (@code{eww-readable}) will attempt to determine
 109 which part of the document contains the ``readable'' text, and will
 110 only display this part.  This usually gets rid of menus and the like.
 111
 112 @findex eww-toggle-fonts
 113 @findex shr-use-fonts
 114 @kindex F
 115   The @kbd{F} command (@code{eww-toggle-fonts}) toggles whether to use
 116 variable-pitch fonts or not.  This sets the @code{shr-use-fonts} variable.
 117
 118 @findex eww-toggle-colors
 119 @findex shr-use-colors
 120 @kindex F
 121   The @kbd{C} command (@code{eww-toggle-colors}) toggles whether to use
 122 HTML-specified colors or not.  This sets the @code{shr-use-colors} variable.
 123
 124 @findex eww-download
 125 @vindex eww-download-directory
 126 @kindex d
 127 @cindex Download
 128   A URL under the point can be downloaded with @kbd{d}
 129 (@code{eww-download}).  The file will be written to the directory
 130 specified in @code{eww-download-directory} (Default: @file{~/Downloads/}).
 131
 132 @findex eww-back-url
 133 @findex eww-forward-url
 134 @findex eww-list-histories
 135 @kindex r
 136 @kindex l
 137 @kindex H
 138 @cindex History
 139   EWW remembers the URLs you have visited to allow you to go back and
 140 forth between them.  By pressing @kbd{l} (@code{eww-back-url}) you go
 141 to the previous URL@.  You can go forward again with @kbd{r}
 142 (@code{eww-forward-url}).  If you want an overview of your browsing
 143 history press @kbd{H} (@code{eww-list-histories}) to open the history
 144 buffer @file{*eww history*}.  The history is lost when EWW is quit.
 145 If you want to remember websites you can use bookmarks.
 146
 147 @vindex eww-history-limit
 148   Along with the URLs visited, EWW also remembers both the rendered
 149 page (as it appears in the buffer) and its source.  This can take a
 150 considerable amount of memory, so EWW discards the history entries to
 151 keep their number within a set limit, as specified by
 152 @code{eww-history-limit}; the default being 50.  This variable could
 153 also be set to @code{nil} to allow for the history list to grow
 154 indefinitely.
 155
 156 @cindex PDF
 157   PDFs are viewed inline, by default, with @code{doc-view-mode}, but
 158 this can be customized by using the mailcap (@pxref{mailcap,,,
 159 emacs-mime, Emacs MIME Manual})
 160 mechanism, in particular @code{mailcap-mime-data}.
 161
 162 @findex eww-add-bookmark
 163 @findex eww-list-bookmarks
 164 @kindex b
 165 @kindex B
 166 @cindex Bookmarks
 167   EWW allows you to @dfn{bookmark} URLs.  Simply hit @kbd{b}
 168 (@code{eww-add-bookmark}) to store a bookmark for the current website.
 169 You can view stored bookmarks with @kbd{B}
 170 (@code{eww-list-bookmarks}).  This will open the bookmark buffer
 171 @file{*eww bookmarks*}.
 172
 173 @findex eww-switch-to-buffer
 174 @findex eww-list-buffers
 175 @kindex s
 176 @kindex S
 177 @cindex Multiple Buffers
 178   To get summary of currently opened EWW buffers, press @kbd{S}
 179 (@code{eww-list-buffers}).  The @file{*eww buffers*} buffer allows you
 180 to quickly kill, flip through and switch to specific EWW buffer.  To
 181 switch EWW buffers through a minibuffer prompt, press @kbd{s}
 182 (@code{eww-switch-to-buffer}).
 183
 184 @findex eww-browse-with-external-browser
 185 @vindex shr-external-browser
 186 @vindex eww-use-external-browser-for-content-type
 187 @kindex &
 188 @cindex External Browser
 189   Although EWW and shr.el do their best to render webpages in GNU
 190 Emacs some websites use features which can not be properly represented
 191 or are not implemented (E.g., JavaScript).  If you have trouble
 192 viewing a website with EWW then hit @kbd{&}
 193 (@code{eww-browse-with-external-browser}) inside the EWW buffer to
 194 open the website in the external browser specified by
 195 @code{shr-external-browser}.  Some content types, such as video or
 196 audio content, do not make sense to display in GNU Emacs at all.  You
 197 can tell EWW to open specific content automatically in an external
 198 browser by customizing
 199 @code{eww-use-external-browser-for-content-type}.
 200
 201 @node Advanced
 202 @chapter Advanced
 203
 204 @findex eww-view-source
 205 @kindex v
 206 @cindex Viewing Source
 207   You can view the source of a website with @kbd{v}
 208 (@code{eww-view-source}).  This will open a new buffer
 209 @file{*eww-source*} and insert the source.  The buffer will be set to
 210 @code{html-mode} if available.
 211
 212 @findex url-cookie-list
 213 @kindex C
 214 @cindex Cookies
 215   EWW handles cookies through the @ref{Top, url package, ,url}.
 216 You can list existing cookies with @kbd{C} (@code{url-cookie-list}).
 217 For details about the Cookie handling @xref{Cookies,,,url}.
 218
 219 @vindex eww-header-line-format
 220 @cindex Header
 221   The header line of the EWW buffer can be changed by customizing
 222 @code{eww-header-line-format}.  The format replaces @code{%t} with the
 223 title of the website and @code{%u} with the URL.
 224
 225 @findex eww-toggle-paragraph-direction
 226 @cindex paragraph direction
 227   The @kbd{D} command (@code{eww-toggle-paragraph-direction}) toggles
 228 the paragraphs direction between left-to-right and right-to-left
 229 text.  This can be useful on web pages that display right-to-left test
 230 (like Arabic and Hebrew), but where the web pages don't explicitly
 231 state the directionality.
 232
 233 @c @vindex shr-bullet
 234 @c @vindex shr-hr-line
 235 @c @vindex eww-form-checkbox-selected-symbol
 236 @c @vindex eww-form-checkbox-symbol
 237 @c   EWW and the rendering engine shr.el use ASCII characters to
 238 @c represent some graphical elements, such as bullet points
 239 @c (@code{shr-bullet}), check boxes
 240 @c (@code{eww-form-checkbox-selected-symbol} and
 241 @c @code{eww-form-checkbox-symbol}), and horizontal rules
 242 @c @code{shr-hr-line}).  Depending on your fonts these characters can be
 243 @c replaced by Unicode glyphs to achieve better looking results.
 244
 245 @vindex shr-max-image-proportion
 246 @vindex shr-blocked-images
 247 @cindex Image Display
 248   Loading random images from the web can be problematic due to their
 249 size or content.  By customizing @code{shr-max-image-proportion} you
 250 can set the maximal image proportion in relation to the window they
 251 are displayed in.  E.g., 0.7 means an image is allowed to take up 70%
 252 of the width and height.  If Emacs supports image scaling (ImageMagick
 253 support required) then larger images are scaled down.  You can block
 254 specific images completely by customizing @code{shr-blocked-images}.
 255
 256 @vindex shr-color-visible-distance-min
 257 @vindex shr-color-visible-luminance-min
 258 @cindex Contrast
 259   EWW (or rather its HTML renderer @code{shr}) uses the colors declared
 260 in the HTML page, but adjusts them if needed to keep a certain minimum
 261 contrast.  If that is still too low for you, you can customize the
 262 variables @code{shr-color-visible-distance-min} and
 263 @code{shr-color-visible-luminance-min} to get a better contrast.
 264
 265 @cindex Desktop Support
 266 @cindex Saving Sessions
 267   In addition to maintaining the history at run-time, EWW will also
 268 save the partial state of its buffers (the URIs and the titles of the
 269 pages visited) in the desktop file if one is used.  @xref{Saving Emacs
 270 Sessions,,, emacs, The GNU Emacs Manual}.
 271
 272 @vindex eww-desktop-remove-duplicates
 273   EWW history may sensibly contain multiple entries for the same page
 274 URI@.  At run-time, these entries may still have different associated
 275 point positions or the actual Web page contents.
 276 The latter, however, tend to be overly large to preserve in the
 277 desktop file, so they get omitted, thus rendering the respective
 278 entries entirely equivalent.  By default, such duplicate entries are
 279 not saved.  Setting @code{eww-desktop-remove-duplicates} to nil will
 280 force EWW to save them anyway.
 281
 282 @vindex eww-restore-desktop
 283   Restoring EWW buffers' contents may prove to take too long to
 284 finish.  When the @code{eww-restore-desktop} variable is set to
 285 @code{nil} (the default), EWW will not try to reload the last visited
 286 Web page when the buffer is restored from the desktop file, thus
 287 allowing for faster Emacs start-up times.  When set to @code{t},
 288 restoring the buffers will also initiate the reloading of such pages.
 289
 290 @vindex eww-restore-reload-prompt
 291   The EWW buffer restored from the desktop file but not yet reloaded
 292 will contain a prompt, as specified by the
 293 @code{eww-restore-reload-prompt} variable.  The value of this variable
 294 will be passed through @code{substitute-command-keys} upon each use,
 295 thus allowing for the use of the usual substitutions, such as
 296 @code{\[eww-reload]} for the current key binding of the
 297 @code{eww-reload} command.
 298
 299 @node History and Acknowledgments
 300 @appendix History and Acknowledgments
 301
 302 EWW was originally written by Lars Ingebrigtsen, known for his work on
 303 Gnus.  He started writing an Emacs HTML rendering library,
 304 @code{shr.el}, to read blogs in Gnus.  He eventually added a web
 305 browser front end and HTML form support.  Which resulted in EWW, the
 306 Emacs Web Wowser.  EWW was announced on 16 June 2013:
 307 @url{http://lars.ingebrigtsen.no/2013/06/16/eww/}.
 308
 309 EWW was then moved from the Gnus repository to GNU Emacs and several
 310 developers started contributing to it as well.
 311
 312 @node GNU Free Documentation License
 313 @chapter GNU Free Documentation License
 314 @include doclicense.texi
 315
 316 @node Key Index
 317 @unnumbered Key Index
 318
 319 @printindex ky
 320
 321 @node Variable Index
 322 @unnumbered Variable Index
 323
 324 @vindex eww-after-render-hook
 325 After eww has rendered the data in the buffer,
 326 @code{eww-after-render-hook} is called.  It can be used to alter the
 327 contents, for instance.
 328
 329 @printindex vr
 330
 331 @node Lisp Function Index
 332 @unnumbered Function Index
 333
 334 @printindex fn
 335
 336 @node Concept Index
 337 @unnumbered Concept Index
 338
 339 @printindex cp
 340
 341
 342 @bye