doc/misc/eww.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename ../../info/eww
   4 @settitle Emacs Web Wowser
   5 @documentencoding UTF-8
   6 @c %**end of header
   7
   8 @copying
   9 This file documents the GNU Emacs Web Wowser (EWW) package.
  10
  11 Copyright @copyright{} 2014--2015 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-download
 101 @vindex eww-download-directory
 102 @kindex d
 103 @cindex Download
 104   A URL under the point can be downloaded with @kbd{d}
 105 (@code{eww-download}).  The file will be written to the directory
 106 specified in @code{eww-download-directory} (Default: @file{~/Downloads/}).
 107
 108 @findex eww-back-url
 109 @findex eww-forward-url
 110 @findex eww-list-histories
 111 @kindex r
 112 @kindex l
 113 @kindex H
 114 @cindex History
 115   EWW remembers the URLs you have visited to allow you to go back and
 116 forth between them.  By pressing @kbd{l} (@code{eww-back-url}) you go
 117 to the previous URL.  You can go forward again with @kbd{r}
 118 (@code{eww-forward-url}).  If you want an overview of your browsing
 119 history press @kbd{H} (@code{eww-list-histories}) to open the history
 120 buffer @file{*eww history*}.  The history is lost when EWW is quit.
 121 If you want to remember websites you can use bookmarks.
 122
 123 @findex eww-add-bookmark
 124 @findex eww-list-bookmarks
 125 @kindex b
 126 @kindex B
 127 @cindex Bookmarks
 128   EWW allows you to @dfn{bookmark} URLs.  Simply hit @kbd{b}
 129 (@code{eww-add-bookmark}) to store a bookmark for the current website.
 130 You can view stored bookmarks with @kbd{B}
 131 (@code{eww-list-bookmarks}).  This will open the bookmark buffer
 132 @file{*eww bookmarks*}.
 133
 134 @findex eww-browse-with-external-browser
 135 @vindex shr-external-browser
 136 @vindex eww-use-external-browser-for-content-type
 137 @kindex &
 138 @cindex External Browser
 139   Although EWW and shr.el do their best to render webpages in GNU
 140 Emacs some websites use features which can not be properly represented
 141 or are not implemented (E.g., JavaScript).  If you have trouble
 142 viewing a website with EWW then hit @kbd{&}
 143 (@code{eww-browse-with-external-browser}) inside the EWW buffer to
 144 open the website in the external browser specified by
 145 @code{shr-external-browser}.  Some content types, such as video or
 146 audio content, do not make sense to display in GNU Emacs at all.  You
 147 can tell EWW to open specific content automatically in an external
 148 browser by customizing
 149 @code{eww-use-external-browser-for-content-type}.
 150
 151 @node Advanced
 152 @chapter Advanced
 153
 154 @findex eww-view-source
 155 @kindex v
 156 @cindex Viewing Source
 157   You can view the source of a website with @kbd{v}
 158 (@code{eww-view-source}).  This will open a new buffer
 159 @file{*eww-source*} and insert the source.  The buffer will be set to
 160 @code{html-mode} if available.
 161
 162 @findex url-cookie-list
 163 @kindex C
 164 @cindex Cookies
 165   EWW handles cookies through the @ref{Top, url package, ,url}.
 166 You can list existing cookies with @kbd{C} (@code{url-cookie-list}).
 167 For details about the Cookie handling @xref{Cookies,,,url}.
 168
 169 @vindex eww-header-line-format
 170 @cindex Header
 171   The header line of the EWW buffer can be changed by customizing
 172 @code{eww-header-line-format}.  The format replaces @code{%t} with the
 173 title of the website and @code{%u} with the URL.
 174
 175 @c @vindex shr-bullet
 176 @c @vindex shr-hr-line
 177 @c @vindex eww-form-checkbox-selected-symbol
 178 @c @vindex eww-form-checkbox-symbol
 179 @c   EWW and the rendering engine shr.el use ASCII characters to
 180 @c represent some graphical elements, such as bullet points
 181 @c (@code{shr-bullet}), check boxes
 182 @c (@code{eww-form-checkbox-selected-symbol} and
 183 @c @code{eww-form-checkbox-symbol}), and horizontal rules
 184 @c @code{shr-hr-line}).  Depending on your fonts these characters can be
 185 @c replaced by Unicode glyphs to achieve better looking results.
 186
 187 @vindex shr-max-image-proportion
 188 @vindex shr-blocked-images
 189 @cindex Image Display
 190   Loading random images from the web can be problematic due to their
 191 size or content.  By customizing @code{shr-max-image-proportion} you
 192 can set the maximal image proportion in relation to the window they
 193 are displayed in.  E.g., 0.7 means an image is allowed to take up 70%
 194 of the width and height.  If Emacs supports image scaling (ImageMagick
 195 support required) then larger images are scaled down.  You can block
 196 specific images completely by customizing @code{shr-blocked-images}.
 197
 198 @vindex shr-color-visible-distance-min
 199 @vindex shr-color-visible-luminance-min
 200 @cindex Contrast
 201   EWW (or rather its HTML renderer @code{shr}) uses the colors declared
 202 in the HTML page, but adjusts them if needed to keep a certain minimum
 203 contrast.  If that is still too low for you, you can customize the
 204 variables @code{shr-color-visible-distance-min} and
 205 @code{shr-color-visible-luminance-min} to get a better contrast.
 206
 207 @node History and Acknowledgments
 208 @appendix History and Acknowledgments
 209
 210 EWW was originally written by Lars Ingebrigtsen, known for his work on
 211 Gnus.  He started writing an Emacs HTML rendering library,
 212 @code{shr.el}, to read blogs in Gnus.  He eventually added a web
 213 browser front end and HTML form support.  Which resulted in EWW, the
 214 Emacs Web Wowser.  EWW was announced on 16 June 2013:
 215 @url{http://lars.ingebrigtsen.no/2013/06/16/eww/}.
 216
 217 EWW was then moved from the Gnus repository to GNU Emacs and several
 218 developers started contributing to it as well.
 219
 220 @node GNU Free Documentation License
 221 @chapter GNU Free Documentation License
 222 @include doclicense.texi
 223
 224 @node Key Index
 225 @unnumbered Key Index
 226
 227 @printindex ky
 228
 229 @node Variable Index
 230 @unnumbered Variable Index
 231
 232 @printindex vr
 233
 234 @node Lisp Function Index
 235 @unnumbered Function Index
 236
 237 @printindex fn
 238
 239 @node Concept Index
 240 @unnumbered Concept Index
 241
 242 @printindex cp
 243
 244
 245 @bye