EWW
***

This file documents the GNU Emacs Web Wowser (EWW) package.

Copyright © 2014--2015 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License.''

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.''

Overview
********

EWW, the Emacs Web Wowser, is a web browser for GNU Emacs.  It can load, parse, and display various web pages using shr.el. However a GNU Emacs with libxml2 support is required.

Basic Usage
***********

You can open a URL or search the web with the command M-x eww. If the input doesn't look like a URL or domain name the web will be searched via eww-search-prefix.  The default search engine is DuckDuckGo (https://duckduckgo.com).  If you want to open a file either prefix the file name with file:// or use the command M-x eww-open-file.

If loading the URL was successful the buffer *eww* is opened and the web page is rendered in it.  You can leave EWW by pressing q or exit the browser by calling eww-quit.  To reload the web page hit g (eww-reload).  Pressing w (eww-copy-page-url) will copy the current URL to the kill ring.

A URL under the point can be downloaded with d (eww-download).  The file will be written to the directory specified in eww-download-directory (Default: ~/Downloads/).

EWW remembers the URLs you have visited to allow you to go back and forth between them.  By pressing l (eww-back-url) you go to the previous URL.  You can go forward again with r (eww-forward-url).  If you want an overview of your browsing history press H (eww-list-histories) to open the history buffer *eww history*.  The history is lost when EWW is quit. If you want to remember websites you can use bookmarks.

EWW allows you to bookmark URLs.  Simply hit b (eww-add-bookmark) to store a bookmark for the current website. You can view stored bookmarks with B (eww-list-bookmarks).  This will open the bookmark buffer *eww bookmarks*.

Although EWW and shr.el do their best to render webpages in GNU Emacs some websites use features which can not be properly represented or are not implemented (E.g., JavaScript).  If you have trouble viewing a website with EWW then hit & (eww-browse-with-external-browser) inside the EWW buffer to open the website in the external browser specified by shr-external-browser.  Some content types, such as video or audio content, do not make sense to display in GNU Emacs at all.  You can tell EWW to open specific content automatically in an external browser by customizing eww-use-external-browser-for-content-type.

Advanced
********

You can view the source of a website with v (eww-view-source).  This will open a new buffer *eww-source* and insert the source.  The buffer will be set to html-mode if available.

EWW handles cookies through the url package (url). You can list existing cookies with C (url-cookie-list). For details about the Cookie handling see Cookies (url).

The header line of the EWW buffer can be changed by customizing eww-header-line-format.  The format replaces %t with the title of the website and %u with the URL.

Loading random images from the web can be problematic due to their size or content.  By customizing shr-max-image-proportion you can set the maximal image proportion in relation to the window they are displayed in.  E.g., 0.7 means an image is allowed to take up 70% of the width and height.  If Emacs supports image scaling (ImageMagick support required) then larger images are scaled down.  You can block specific images completely by customizing shr-blocked-images.

EWW (or rather its HTML renderer shr) uses the colors declared in the HTML page, but adjusts them if needed to keep a certain minimum contrast.  If that is still too low for you, you can customize the variables shr-color-visible-distance-min and shr-color-visible-luminance-min to get a better contrast.

History and Acknowledgments
***************************

EWW was originally written by Lars Ingebrigtsen, known for his work on Gnus.  He started writing an Emacs HTML rendering library, shr.el, to read blogs in Gnus.  He eventually added a web browser front end and HTML form support.  Which resulted in EWW, the Emacs Web Wowser.  EWW was announced on 16 June 2013: http://lars.ingebrigtsen.no/2013/06/16/eww/.

EWW was then moved from the Gnus repository to GNU Emacs and several developers started contributing to it as well.

GNU Free Documentation License
******************************

     [file doclicense.texi not included]