# Dillo User Manual

Welcome to the user manual of the Dillo browser. The manual is divided into sections but is written in a single page to allow search by keywords. Generated for version __VERSION__.

Table of contents:

## Introduction

Dillo is a web browser designed to be fast, use few resources and support slow and unreliable networks on resource-constrained machines. It can load local and remote files via HTTP, HTTPS and FTP. Other protocols like Gemini, Gopher, IPFS and others are available as plugins.

Dillo supports a subset of HTML 4.01 and CSS 2.1 but it doesn't support JavaScript and only implements some elements of HTML 5 and CSS 3. It also renders plain text documents and images in PNG, JPG and GIF formats.

## Reading

In this section we cover the basics to read a web page, scrolling and finding or copying text.

### Basics

The graphical interface is designed to be used with a mouse or pointing device. At the top of the browser window you have the location bar and the main buttons to control the browser. You can leave the mouse for a brief moment over any part of the menu to show a tooltip with more information.

Dillo has context sensitive menus, which are opened with the right mouse button, available on pages, links, images, forms, the Back and Forward buttons, and the bug meter. They show different actions to be performed specific to the element. For example, to save a page you can right-click on the page and select "Save page as...". Or to copy a link URL you can right-click on a link and select "Copy link location".

Dillo can hide all panels and use the whole window area to display the page. To switch between modes use the ESC key. You can also choose the control panel size by going to the Tools button and selecting a different one under "Panel size".

You can open this manual from Dillo by clicking on the top right "?" button. It doesn't require a network connection.

### Scrolling

There are several methods to move or scroll the view of the current page.

- Using the keyboard:
  - Use the `Home` or `End` keys to jump to the top or to the end of a page.
  - Use `PgUp` or `PgDn` to advance a whole page (window size) minus one step.
  - Use the arrow keys to move the view a step in that direction.
  - You can also use the `Space` key as `PgDn` and `b` as PgUp.
- Using the mouse or pointing device:
  - Rotate the mouse wheel to move one step in that direction.
  - Keep the middle button (or mouse wheel button) pressed while dragging to scroll the page precisely.
- Using the scrollbar:
  - Drag the thumb in the scrollbar on the side up or down to scroll the page.
  - Left-click or right-click on the scrollbar above or below the thumb to move one page in that direction.
  - Middle-click on the scrollbar above or below the thumb to jump to that specific position of the page.
  - Click the scrollbar arrows to move the view one step in that direction.

You can control the size of a step by setting the `scroll_step` option in the dillorc configuration file. By default it will scroll 100 pixels per step.

### Find text

To find text in a document right-click to open the Page menu and select Find text or press `Ctrl+F` on the keyboard. Then type the substring that you want to find and click Next (or the `Enter` key).

Dillo will scroll the page and highlight found text starting from the top. To find a word (not a substring) use spaces around it to limit the search to matching words only.

To close the find bar you can click on the red X on the bottom right or press ESC.

### Copy and paste

To copy some text just hold down the left mouse button and move to select the area to copy. To paste, go to the target application and press the middle mouse button.

If you want to select more than one screen, hold the mouse left button down and scroll with PgUp, PgDn or the arrow keys.

If you want to paste an URL into Dillo, do it on the "clear-URL" button (the "X" next to the location bar).

## Navigation

This section focuses on how to navigate to other pages by following hyperlinks, using bookmarks, typing or pasting a new URL or using the history.

### Hyperlinks

Hyperlinks (or just links) allow you to navigate to other pages by clicking them. They change the cursor to a hand to indicate that an element can be clicked with the left button:

Links to other pages usually appear in blue and underlined by default and once they are visited they change to purple. However, this is not always the case, so using the mouse cursor shape is the best indicator of a link.

When you follow a link by clicking on it, the previous pages will be remembered in case you want to go back to them. Use the Back and Forward buttons on the top bar to navigate among history pages.

### History

When you follow several links across different web pages, they are remembered in case you can to go back. Use the "Back" and "Forward" buttons of the panel to go to the previous or next page.

You can also right-click on the Back or Forward buttons to open a menu with the list of previous or next pages available, so you can jump directly to them. Use the left button to open them in the current tab or the middle button to open them in a new tab.

The `,` (comma) and `.` (dot) keys can be used to jump backwards or forward (mnemonic: those keys are usually labeled "<" and ">").

### Location bar

The location bar on the top displays the URL of the current page loaded and can be used to access other pages by typing the new URL or by pasting it and pressing Enter.

The red x on the left clears the location bar content when left clicked. Then you can type or paste a new address from the clipboard by middle clicking on the location bar. As these two actions are usually performed together, you can simply middle-click on the x button to go to the URL in the clipboard.

You can also select the location bar content from the keyboard by pressing `Ctrl+L`.

### Web search

Several search engines are available by pressing the magnifying glass icon next to the location bar or by pressing `Ctrl+S`. The search engines are configured in Dillorc with the option `search_url`. Use it multiple times to define multiple search engines.

The location bar can also be used to search the web by using a special prefix for each search engine. For example, the following line:

    search_url="dd DuckDuckGo http://duckduckgo.com/lite/?kp=-1&kd=-1&q=%s"

Defines the "DuckDuckGo" search engine with the prefix "`dd`", so you can type in the location bar "`dd dillo browser`" to search with DuckDuckGo for the keywords "dillo browser".

### Tabs

Dillo can open different web pages into tabs. To open a link in a new tab click the middle button instead of the left button. The same applies to buttons to submit a form.

By default the new tab will be automatically focused. If you want to change this behaviour, adjust the following options in the dillorc configuration file:

    middle_click_opens_new_tab
    focus_new_tab

Press `Shift` to temporarily reverse the focusing behaviour while middle-clicking on a link.

To close a tab press the X button on the top right (only visible with multiple tabs). You can also close the tab by clicking with the right button on the tab label. The middle button can be used instead by setting the option:

    right_click_closes_tab=NO

### Bookmarks

Dillo can save URLs of web pages as bookmarks so you can open them later. To bookmark the current page, open the Page menu by right-clicking on the page and select "Bookmark this page" (it also works over a link).

To see or edit the bookmarks, click on the Bookmarks button on the panel or press `Ctrl+B`.

Bookmarks are handled by a built-in Dillo plugin named `bm` (read more about plugins in the Plugins section) and are synchronized across all instances of the browser. The list of bookmarks can also be shown by opening the URL `dpi:/bm/`.

The bookmarks are stored in a simple plain text file named `bm.txt` (see the details of this file in the bm.txt section). You can edit the file directly to change the bookmarks.

## Privacy and network

The default privacy policy in Dillo attempts to keep the user safe from tracking, even if this policy breaks a lot of website functionality. In this section you can add exceptions or relax the configuration at your own risk.

### HTTPS

Dillo has support for HTTPS, allowing secure connections to remote websites. Use the protocol "`https:`" to specify the use of HTTPS. When a problem is encountered with the remote certificate, a warning dialog explains the details and allows you to choose what to do: continue loading the website or cancel.

By default Dillo looks for a TLS library at build time, which can be OpenSSL or mbedTLS. You can see which library is being used by looking at the console when it starts:

    $ dillo
    dillo_dns_init: Here we go! (threaded)
    TLS library: OpenSSL 3.2.1 30 Jan 2024
    ...

### Cookies

Due to privacy concerns, cookies are disabled by default unless explicitly enabled in the configuration.

Support for cookies is implemented using a built-in plugin that shares them between several instances of Dillo and follows the RFC 6265 specification. Current cookie limits are 20 per domain and 1200 in total.

Cookies are configured by the `cookiesrc` configuration file. See the Cookiesrc section to see how to enable cookies for some domains or accept them by default.

### Proxy

Dillo can use a HTTP proxy by setting the environment variable `http_proxy` or the configuration option with the same name. All HTTP and HTTPS traffic will be sent through the proxy.

Note: Plugins may not implement proxy support.

### Ad blocking

Dillo has the ability to block content when loading a page based on the domain the embeded content is being loaded from. You can control how Dillo handles automatic requests for resources (like images and style sheets) that aren't at the same domain as the original page.

See the domainrc configuration file to find out how to specify which domains are blocked or allowed.

### Downloads

Downloads are made using wget with a FLTK-based GUI wrapper, through the Dillo plugin (dpi) framework. If you close the browser window, downloads will continue.

### Images-off mode

You can browse without images now:

- There is an option in the Tools menu to disable automatic image loading. An image's alt text (or `[IMG]` placeholder) will appear in the page.
- If you want to load an individual image, left click on its text.
- You can set "no images" as the default mode in dillorc.

## Configuration

Dillo has several configuration files that control the behavior of the browser. Each configuration file is searched first in the `~/.dillo` directory and, if not found, in the default system configuration directory (typically `/etc/dillo`).

Most configuration files can include comments by starting a line with the "`#`" symbol. Their specific syntax is described in the following sections.

### Dillorc

The main configuration of Dillo is controled by the `dillorc` file. The list of all available options can be found in the system configuration file, typically `/etc/dillo/dillorc`. You may want to copy it into `~/.dillo/dillorc` and edit it to suit your needs.

The file is commented to describe what each option does. The default value for each option as well as other interesting values are also available as comments:

- "`#option=...`" shows the built-in default.
- "`# option=...`" is an additional example.
- "`option=...`" overrides the built-in value.

The `search_url` option can be specified multiple times:

    search_url="dd DuckDuckGo (https) https://duckduckgo.com/lite/?kp=-1&q=%s"
    search_url="Wikipedia http://www.wikipedia.org/w/index.php?search=%s&go=Go"

### Cookiesrc

Cookies are configured in the `~/.dillo/cookiesrc` file by using rules, with one rule per line. The rule syntax is very simple, first specify the host and then the action, separated by white spaces. Comment lines start with `#` as the first character and the whole line is ignored.

The host can be in the form `example.com` to match only that domain or `.example.com` to match all subdomains of example.com. The special word `DEFAULT` specifies the default policy, when no other match occurs.

The action can be: `DENY` to ignore cookies, `ACCEPT_SESSION` to only accept session cookies but don't save them to disk and `ACCEPT` to accept and store cookies in disk (this will allow sites to track you over time).

When the cookies plugin exits, only the accepted cookies by `ACCEPT` are saved to `~/.dillo/cookies.txt`, and ACCEPT_SESSION cookies are forgotten. The cookies plugin normally exits after a period of inactivity, but you can force it to exit with the command `dpidc stop`.

Here is an example `cookiesrc` file:

    # host        action
    DEFAULT       DENY
    fltk.org      ACCEPT
    .example.com  ACCEPT_SESSION

Which is parsed as follows:

- Line 1: Comment line begins with `#`.
- Line 2: Deny all cookies from all domains not otherwise specified (this is the default).
- Line 3: Accept all cookies from fltk.org, and save them to disk when the cookie plugin exits.
- Line 4: Accept all cookies from all subdomains of example.com, but do not save them when the cookie plugin exits.

Dillo is especially concerned about privacy and security issues. Our advice is to avoid cookies whenever possible and at most set ACCEPT_SESSION to specific trusted sites.

### Domainrc

With the `~/.dillo/domainrc` file, you can control how Dillo handles automatic requests for resources (like images and style sheets) that aren't at the same domain as the original page.

The file contains one rule per line. Comments are specified by starting the line with the `#` symbol. The default rule is either `default accept` or `default deny` and will cause Dillo to, respectively, accept all requests by default or deny all requests by default.

Depending on the default rule, the next rules behave as exceptions by denying specific connections or allowing specific connections, respectively.

Exceptions to the default rule are written in the format `source destination`, and match request from the source domain to the destination domain. The source and destination domains can be specified in three ways:

- "`*`" to match any domain
- "`example.com`" to match the specific host example.com
- "`.example.com`" to match example.com and any of its subdomains

Here is an example:

    # Accept all requests by default
    default accept
    # But block some ad-sites and trackers from any domain
    * .doubleclick.net
    * .googleadservices.com
    * .quantserve.com

### Style.css

Custom CSS styles can be placed in the `~/.dillo/style.css` file to set default web page styles. To override page styles add the "`!important`" flag.

### Dpidrc

The configuration for plugins is placed in the `~/.dillo/dpidrc` file.

Plugins are searched in the `~/.dillo/dpi/` directory first, and then in the system directory if not found. The `dpi_dir` option sets the system `dpi` directory and must be specified once. Here is an example:

    dpi_dir=/usr/lib/dillo/dpi

By default, plugins will receive requests at the URL `dpi:/name/`, for example bookmarks are available at `dpi:/bm/`.

Plugins can also be associated with a protocol (like "`file:`"). When a request is made using the given protocol the associated plugin is used to process the request. The rest of the file assigns a plugin to a protocol, one per line. The syntax is `proto.name=path-to-plugin.dpi`. The path of the plugin is relative to the `dpi` directory. Here are protocols used by the built-in plugins:

    proto.file=file/file.dpi
    proto.ftp=ftp/ftp.filter.dpi
    proto.data=datauri/datauri.filter.dpi

Here ( ) is an example image using the `data:` protocol used to define a PNG image inline in a HTML document.

### bm.txt

Web page URLs can be saved as bookmarks so they can be accessed in the future. Bookmarks are stored in a plain text file located at `~/.dillo/bm.txt`. The file can be modified by using the Book button in the toolbar and the context menu on a page or link, but they can also be edited manually. Bookmarks are organized into sections and are given a description (usually the page title).

The syntax of the `bm.txt` file is described as follows:

First, the sections are defined at the beginning, prefixed with a `:sN:` identifier, along with the description of the section:

    :s0: News
    :s1: Blog

Then every bookmark is added in a single line, by writing the section identifier, the URL and a description:

    s0 https://slashdot.org Slashdot
    s0 https://news.ycombinator.com/ Hacker News
    s1 https://100r.co/site/log.html 100 Rabbits Log

The `bm.txt` file is designed to be easily read by humans and is suitable to be kept updated among machines by using a version control tool.

### Keysrc

The mapping of keys in Dillo is contolled by the `~/.dillo/keysrc` file. The format is "`key = action`" or "`<modifier>key = action`". Lines that begin with a "#" are comments. The commented-out bindings below show the defaults built into Dillo.

- Modifiers recognized: Shift, Ctrl, Alt, Meta (on Mac OS X use "Meta" for Command).
- Key names recognized: Backspace, Delete, Down, End, Esc, F1 through F12, Home, Insert, Left, Menu, PageDown, PageUp, Print, Return, Right, Space, Tab, Up.
- Multimedia keys: Back, Favorites, Forward, HomePage, Mail, MediaNext, MediaPlay, MediaPrev, MediaStop, Refresh, Search, Sleep, Stop, VolumeDown, VolumeMute, VolumeUp.

If Dillo is running under X11, keys whose names are not recognized can be specified using their keysym value in hexadecimal. Use `xev` to get the keysym, for example:

    0x1008ff27 = forward

The action "nop" (no operation) can be used to remove a binding.

Example file:

    # "close-all" closes all tabs/windows and exits.
    <ctrl>q = close-all

    # "left-tab" and "right-tab" switch to the left/right of the current tab.
    <ctrl><shift>tab = left-tab

    # Use HJKL to move around
    k = line-up
    j = line-down
    h = left
    l = right

## Advanced usage

These sections focus on advanced topics and are recommended for experienced users of Dillo.

### Plugins

The functionality of Dillo can be extended by using plugins, which can translate other formats to HTML, implement new protocols or provide a custom service.

Plugins can be written in any programming language and they interact with the browser using the DPI protocol. A list of plugins is available on the Dillo website. Some plugins are just a few lines of shell script, so you are encouraged to read them to learn how to write your own plugins. Plugins are searched by looking for files that end with the `.dpi` extension (or `.dpi.exe` in Windows) in `~/.dillo/dpi` and `dpi_dir` (see the Dpidrc configuration section).

There are two types of plugins: filters and servers. Filters are executed for each request like a UNIX pipe, they read from the standard input and write to the standard output. The name of filter plugin programs must end in `.filter.dpi`. On the other hand, servers listen on a socket for new requests. They can process several requests at the same time, preventing the overhead of spawning multiple processes and they can easily share information among requests.

You can install plugins from any third party, but you should always review the source before running code written by others. To install a new plugin, copy the files to `~/.dillo/dpi/name/` and then associate the name protocol to the program that must run in the `~/.dillo/dpidrc` file. Plugins may have other software dependencies required for it to work.

Here is an example of how to manually install the Gemini protocol plugin (it comes with a Makefile that automates the process, so this is not necessary), which is a filter plugin written in shell script:

    $ mkdir -p ~/.dillo/dpi/gemini
    $ cp gemini.filter.dpi ~/.dillo/dpi/gemini/
    $ chmod +x ~/.dillo/dpi/gemini/gemini.filter.dpi
    $ echo "proto.gemini=gemini/gemini.filter.dpi" >> ~/.dillo/dpidrc
    $ dpidc stop

Now, when a request is made to an URL that begins with the `gemini:` protocol, it will be processed by the `gemini/gemini.filter.dpi` program, and the output will be displayed by Dillo.

### Bug Meter

Dillo includes a bug meter which shows the number of detected bugs inside the page. The bugs are caught at parsing time, so the error messages also show the line where they occur and provide a hint of what was expected instead.

The primary purpose of the bug meter is to help webmasters and page authors to polish the contents of their sites with a view to making them compliant with HTML standards.

The bug meter is located at the lower right corner of Dillo. Use the left-click to see the messages, right-click for a menu to open other HTML validators.

### Keyboard shortcuts

Most actions can be issued by using a keyboard shortcut. The key bindings can be changed in the `~/.dillo/keysrc` file (see the keysrc section). The list of default bindings is given in the following table.

Shortcut | Mnemonic | Function
--- | --- | ---
Ctrl-L | Location | Enter a new URL
Ctrl-F | Find | Find text
Ctrl-S | Search | Search the web
Ctrl-R | Reload | Reload current page
Ctrl-N | New | New browser window
Ctrl-T | Tab | New tab
Ctrl-W | Window | Quit tab/window
Ctrl-O | Open | Open file
Ctrl-U |  | View source
Ctrl-B | Bookmarks | View bookmarks
Ctrl-Q | Quit | Quit dillo
Back or "," | < | Previous page
Shift-Back or "." | > | Next page
Alt-F | File | File menu
Ctrl-Tab or Ctrl-PageDown | Tab | Next tab
Ctrl-Shift-Tab or Ctrl-PageUp | Tab | Previous tab
Esc | escape | Close dialog, Close findbar, Hide/show control panels