From 021adb56db9d66cee2b58a635764798245b494d0 Mon Sep 17 00:00:00 2001 From: Rodrigo Arias Mallo Date: Sat, 27 Apr 2024 22:30:04 +0200 Subject: Add version to user manual Fixes: https://github.com/dillo-browser/dillo/issues/136 --- doc/Makefile.am | 10 +- doc/user_help.html | 793 -------------------------------------------------- doc/user_help.in.html | 793 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 800 insertions(+), 796 deletions(-) delete mode 100644 doc/user_help.html create mode 100644 doc/user_help.in.html (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index a672597b..943e70d7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,12 +1,16 @@ -dist_doc_DATA = user_help.html +doc_DATA = user_help.html man_MANS = dillo.1 EXTRA_DIST = \ README \ Cookies.txt \ dillo.1.in \ - user_help.html + user_help.in.html dillo.1: $(srcdir)/dillo.1.in Makefile sed 's%/usr/local%${prefix}%g' < $(srcdir)/dillo.1.in > dillo.1 -DISTCLEANFILES = dillo.1 +# Use .in.html instead of .html.in so it is recognized as HTML. +user_help.html: $(srcdir)/user_help.in.html Makefile + sed 's/__VERSION__/${VERSION}/g' $< > $@ + +DISTCLEANFILES = dillo.1 user_help.html diff --git a/doc/user_help.html b/doc/user_help.html deleted file mode 100644 index 7ba78277..00000000 --- a/doc/user_help.html +++ /dev/null @@ -1,793 +0,0 @@ - - - - - Dillo User Manual - - - - -
-

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.

- -
-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.

- - - -

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). -

- -

-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 (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: -

-hand shaped cursor -

-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. - -

-

-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: -

- -

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: - - -

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:

- -

-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: -

-

-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 ( -red dot -) 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. - -

- -

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 -
-

-

This manual has been written in HTML by hand using Vim.
-If you find any issue, please report it via -GitHub or -email. -

-
- - - diff --git a/doc/user_help.in.html b/doc/user_help.in.html new file mode 100644 index 00000000..c3166710 --- /dev/null +++ b/doc/user_help.in.html @@ -0,0 +1,793 @@ + + + + + Dillo __VERSION__ User Manual + + + + +
+

Dillo __VERSION__ 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.

+ +
+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.

+ + + +

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). +

+ +

+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 (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: +

+hand shaped cursor +

+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. + +

+

+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: +

+ +

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: + + +

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:

+ +

+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: +

+

+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 ( +red dot +) 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. + +

+ +

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 +
+

+
+ + + -- cgit v1.2.3