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 @include emacsver.texi
   7 @c %**end of header
   8
   9 @copying
  10 This file documents the GNU Emacs Web Wowser (EWW) package.
  11
  12 Copyright @copyright{} 2014 Free Software Foundation, Inc.
  13
  14 @quotation
  15 Permission is granted to copy, distribute and/or modify this document
  16 under the terms of the GNU Free Documentation License, Version 1.3 or
  17 any later version published by the Free Software Foundation; with no
  18 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
  19 and with the Back-Cover Texts as in (a) below.  A copy of the license
  20 is included in the section entitled ``GNU Free Documentation License.''
  21
  22 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  23 modify this GNU manual.''
  24 @end quotation
  25 @end copying
  26
  27 @dircategory Emacs misc features
  28 @direntry
  29 * EWW: (eww).      Emacs Web Wowser
  30 @end direntry
  31
  32 @finalout
  33
  34 @titlepage
  35 @title Emacs Web Wowser (EWW)
  36 @subtitle A web browser for GNU Emacs.
  37
  38 @page
  39 @vskip 0pt plus 1filll
  40 @insertcopying
  41 @end titlepage
  42
  43 @contents
  44
  45 @ifnottex
  46 @node Top
  47 @top EWW
  48
  49 @insertcopying
  50 @end ifnottex
  51
  52 @menu
  53 * Overview::
  54 * Basics::
  55 * Advanced::
  56
  57 Appendices
  58 * History and Acknowledgments::
  59 * GNU Free Documentation License::  The license for this documentation.
  60
  61 Indices
  62 * Key Index::
  63 * Variable Index::
  64 * Lisp Function Index::
  65 * Concept Index::
  66 @end menu
  67
  68 @node Overview
  69 @chapter Overview
  70 @dfn{EWW}, the Emacs Web Wowser, is a web browser for GNU Emacs.  It
  71 can load, parse, and display various web pages using @dfn{shr.el}.
  72 However a GNU Emacs with @code{libxml2} support is required.
  73
  74 @node Basics
  75 @chapter Basic Usage
  76
  77 @findex eww
  78 @findex eww-open-file
  79 @vindex eww-search-prefix
  80 @cindex eww
  81 @cindex Web Browsing
  82   You can open a URL or search the web with the command @kbd{M-x eww}.
  83 If the input doesn't look like a URL or domain name the web will be
  84 searched via @code{eww-search-prefix}.  The default search engine is
  85 @url{https://duckduckgo.com, DuckDuckGo}.  If you want to open a file
  86 either prefix the file name with @code{file://} or use the command
  87 @kbd{M-x eww-open-file}.
  88
  89 @findex eww-quit
  90 @findex eww-reload
  91 @findex eww-copy-page-url
  92 @kindex q
  93 @kindex w
  94 @kindex g
  95   If loading the URL was successful the buffer @code{*eww*} is opened
  96 and the web page is rendered in it.  You can leave EWW by pressing
  97 @kbd{q} or exit the browser by calling @kbd{eww-quit}.  To reload the
  98 web page hit @kbd{g} (@code{eww-reload}).  Pressing @kbd{w}
  99 (@code{eww-copy-page-url}) will copy the current URL to the kill ring.
 100
 101 @findex eww-download
 102 @vindex eww-download-directory
 103 @kindex d
 104 @cindex Download
 105   A URL under the point can be downloaded with @kbd{d}
 106 (@code{eww-download}).  The file will be written to the directory
 107 specified in @code{eww-download-directory} (Default: @file{~/Downloads/}).
 108
 109 @findex eww-back-url
 110 @findex eww-forward-url
 111 @findex eww-list-histories
 112 @kindex r
 113 @kindex l
 114 @kindex H
 115 @cindex History
 116   EWW remembers the URLs you have visited to allow you to go back and
 117 forth between them.  By pressing @kbd{l} (@code{eww-back-url}) you go
 118 to the previous URL.  You can go forward again with @kbd{r}
 119 (@code{eww-forward-url}).  If you want an overview of your browsing
 120 history press @kbd{H} (@code{eww-list-histories}) to open the history
 121 buffer @code{*eww history*}.  The history is lost when EWW is quit.
 122 If you want to remember websites you can use bookmarks.
 123
 124 @findex eww-add-bookmark
 125 @findex eww-list-bookmarks
 126 @kindex b
 127 @kindex B
 128 @cindex Bookmarks
 129   EWW allows you to @dfn{bookmark} URLs.  Simply hit @kbd{b}
 130 (@code{eww-add-bookmark}) to store a bookmark for the current website.
 131 You can view stored bookmarks with @kbd{B}
 132 (@code{eww-list-bookmarks}).  This will open the bookmark buffer
 133 @code{*eww bookmarks*}.
 134
 135 @findex eww-browse-with-external-browser
 136 @vindex shr-external-browser
 137 @vindex eww-use-external-browser-for-content-type
 138 @kindex &
 139 @cindex External Browser
 140   Although EWW and shr.el do their best to render webpages in GNU
 141 Emacs some websites use features which can not be properly represented
 142 or are not implemented (E.g., JavaScript).  If you have trouble
 143 viewing a website with EWW then hit @kbd{&}
 144 (@code{eww-browse-with-external-browser}) inside the EWW buffer to
 145 open the website in the external browser specified by
 146 @code{shr-external-browser}.  Some content types, such as video or
 147 audio content, do not make sense to display in GNU Emacs at all.  You
 148 can tell EWW to open specific content automatically in an external
 149 browser by customizing
 150 @code{eww-use-external-browser-for-content-type}.
 151
 152 @node Advanced
 153 @chapter Advanced
 154
 155 @findex eww-view-source
 156 @kindex v
 157 @cindex Viewing Source
 158   You can view the source of a website with @kbd{v}
 159 (@code{eww-view-source}).  This will open a new buffer
 160 @code{*eww-source*} and insert the source.  The buffer will be set to
 161 @code{html-mode} if available.
 162
 163 @findex url-cookie-list
 164 @kindex C
 165 @cindex Cookies
 166   EWW handles cookies through the @ref{Top, url package, ,url}.
 167 You can list existing cookies with @kbd{C} (@code{url-cookie-list}).
 168 For details about the Cookie handling @xref{Cookies,,,url}.
 169
 170 @vindex eww-header-line-format
 171 @cindex Header
 172   The header line of the EWW buffer can be changed by customizing
 173 @code{eww-header-line-format}.  The format replaces @code{%t} with the
 174 title of the website and @code{%u} with the URL.
 175
 176 @c @vindex shr-bullet
 177 @c @vindex shr-hr-line
 178 @c @vindex eww-form-checkbox-selected-symbol
 179 @c @vindex eww-form-checkbox-symbol
 180 @c   EWW and the rendering engine shr.el use ASCII characters to
 181 @c represent some graphical elements, such as bullet points
 182 @c (@code{shr-bullet}), check boxes
 183 @c (@code{eww-form-checkbox-selected-symbol} and
 184 @c @code{eww-form-checkbox-symbol}), and horizontal rules
 185 @c @code{shr-hr-line}).  Depending on your fonts these characters can be
 186 @c replaced by Unicode glyphs to achieve better looking results.
 187
 188 @vindex shr-max-image-proportion
 189 @vindex shr-blocked-images
 190 @cindex Image Display
 191   Loading random images from the web can be problematic due to their
 192 size or content.  By customizing @code{shr-max-image-proportion} you
 193 can set the maximal image proportion in relation to the window they
 194 are displayed in.  E.g., 0.7 means an image is allowed to take up 70%
 195 of the width and height.  If Emacs supports image scaling (ImageMagick
 196 support required) then larger images are scaled down.  You can block
 197 specific images completely by customizing @code{shr-blocked-images}.
 198
 199 @node History and Acknowledgments
 200 @appendix History and Acknowledgments
 201
 202 EWW was originally written by Lars Ingebrigtsen, known for his work on
 203 Gnus.  He started writing an Emacs HTML rendering library,
 204 @code{shr.el}, to read blogs in Gnus.  He eventually added a web
 205 browser front end and HTML form support.  Which resulted in EWW, the
 206 Emacs Web Wowser.  EWW was announced on 16 June 2013:
 207 @url{http://lars.ingebrigtsen.no/2013/06/16/eww/}.
 208
 209 EWW was then moved from the Gnus repository to GNU Emacs and several
 210 developers started contributing to it as well.  A list of contributors
 211 at the time of writing this manual:
 212
 213 @itemize @bullet
 214 @item Daniel Hackney
 215 @item Eli Zaretskii
 216 @item Glenn Morris
 217 @item Ivan Kanis
 218 @item Juri Linkov
 219 @item Katsumi Yamaoka
 220 @item Kenjiro NAKAYAMA
 221 @item Lars Magne Ingebrigtsen
 222 @item Leo Liu
 223 @item Paul Eggert
 224 @item Rüdiger Sonderfeld
 225 @item Stefan Monnier
 226 @item Ted Zlatanov
 227 @end itemize
 228
 229 @node GNU Free Documentation License
 230 @chapter GNU Free Documentation License
 231 @include doclicense.texi
 232
 233 @node Key Index
 234 @unnumbered Key Index
 235
 236 @printindex ky
 237
 238 @node Variable Index
 239 @unnumbered Variable Index
 240
 241 @printindex vr
 242
 243 @node Lisp Function Index
 244 @unnumbered Function Index
 245
 246 @printindex fn
 247
 248 @node Concept Index
 249 @unnumbered Concept Index
 250
 251 @printindex cp
 252
 253
 254 @bye