1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Dillo User Manual</title>
<style>
body {
background: white;
color: black;
line-height: 1.5;
margin: 3em;
font-family: sans-serif;
font-size: 16px;
}
.main {
margin: 0 auto; /* won't work on Dillo, yet */
max-width: 40em;
min-width: 20em;
}
ul.toc {
font-size: 14px;
padding: 1em;
}
ul.toc li {
padding: 0px;
}
h1 {
margin-top: 0.25em;
margin-bottom: 0.25em
}
h2 {
padding: 0.5em;
margin-top: 1em;
text-align: center;
}
h3 {
border-top: 1px solid #eee;
padding-top: 1em;
}
pre {
border-left: 4px solid #ccc;
padding: 0.5em;
background-color: #f8f8f8;
font-size: 14px;
}
ul {
margin-left: 0px;
padding-left: 1.5em;
}
li {
padding: 0.2em;
}
table {
width: 100%;
border-collapse: collapse;
}
th,td {
padding: 0.25em;
border-spacing: 0px;
border-top: solid 1px #ccc;
border-bottom: solid 1px #ccc;
}
th {
background-color: #eee;
}
footer {
color: #777;
margin: 2em;
font-size: 14px;
text-align: center;
}
</style>
</head>
<body>
<div class="main">
<h1>Dillo User Manual</h1>
<p>Welcome to the user manual of the Dillo browser. The manual is divided into
<em>sections</em> but is written in a <em>single page</em> to allow search by
keywords. Generated for version __VERSION__.</p>
<details><!-- Not supported in Dillo, but decays ok -->
<summary class="toc">Table of contents:</summary>
<ul class="toc">
<li><a href="#introduction">Introduction</a></li>
<li><a href="#reading">Reading</a>
<ul>
<li><a href="#basics">Basics</a></li>
<li><a href="#scrolling">Scrolling</a></li>
<li><a href="#find-text">Find text</a></li>
<li><a href="#copy-and-paste">Copy and paste</a></li>
<li><a href="#zoom">Zoom</a></li>
</ul>
</li>
<li><a href="#navigation">Navigation</a>
<ul>
<li><a href="#hyperlinks">Hyperlinks</a></li>
<li><a href="#history">History</a></li>
<li><a href="#location-bar">Location bar</a></li>
<li><a href="#web-search">Web search</a></li>
<li><a href="#tabs">Tabs</a></li>
<li><a href="#bookmarks">Bookmarks</a></li>
</ul>
</li>
<li><a href="#privacy-and-network">Privacy and Network</a>
<ul>
<li><a href="#https">HTTPS</a></li>
<li><a href="#cookies">Cookies</a></li>
<li><a href="#proxy">Proxy</a></li>
<li><a href="#ad-blocking">Ad-blocking</a></li>
<li><a href="#downloads">Downloads</a></li>
<li><a href="#images-off-mode">Images-off mode</a></li>
</ul>
<li><a href="#configuration">Configuration</a>
<ul>
<li><a href="#dillorc">Dillorc</a></li>
<li><a href="#cookiesrc">Cookiesrc</a></li>
<li><a href="#domainrc">Domainrc</a></li>
<li><a href="#style-css">Style.css</a></li>
<li><a href="#dpidrc">Dpidrc</a></li>
<li><a href="#bm-txt">bm.txt</a></li>
<li><a href="#keysrc">Keysrc</a></li>
</ul>
</li>
<li><a href="#advanced-usage">Advanced usage</a>
<ul>
<li><a href="#plugins">Plugins</a></li>
<li><a href="#bug-meter">Bug meter</a></li>
<li><a href="#keyboard-shortcuts">Keyboard shortcuts</a></li>
</ul>
</li>
</ul>
</details>
<h2 id="introduction">Introduction</h2>
<p>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
<a href="#plugins">plugins</a>.</p>
<p>Dillo supports a subset of HTML 4.01 and CSS 2.1 but it <b>doesn't support
JavaScript</b> and only implements some elements of HTML 5 and CSS 3. It also
renders plain text documents and images in PNG, JPG, GIF, SVG and WebP
formats.</p>
<h2 id="reading">Reading</h2>
<p>In this section we cover the basics to read a web page, scrolling and finding
or copying text.</p>
<h3 id="basics">Basics</h3>
<p>
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.
<p>
Dillo has <em>context sensitive menus</em>, 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".
<p>
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".
<p>
You can open this manual from Dillo by clicking on the top right "?" button. It
doesn't require a network connection.
<h3 id="scrolling">Scrolling</h3>
<p>There are several methods to move or scroll the view of the current page.</p>
<ul>
<li>Using the <em>keyboard</em>:
<ul>
<li>Use the <code>Home</code> or <code>End</code> keys to jump to the top
or to the end of a page.</li>
<li>Use <code>PgUp</code> or <code>PgDn</code> to advance a whole
<em>page</em> (window size) minus one <em>step</em>.</li>
<li>Use the arrow keys to move the view a <em>step</em> in that
direction.</li>
<li>You can also use the <code>Space</code> key as <code>PgDn</code> and
<code>b</code> as PgUp.</li>
</ul>
</li>
<li>Using the <em>mouse</em> or <em>pointing device</em>:
<ul>
<li>Rotate the mouse wheel to move one <em>step</em> in that direction.
Hold Shift to move one <em>page</em> instead.
<li>Keep the middle button (or mouse wheel button) pressed while
dragging to scroll the page precisely.
</ul>
</li>
<li>Using the <em>scrollbar</em>:
<ul>
<li>Drag the thumb in the scrollbar on the side up or down to scroll the
page.
<li>Left-click or right-click on the scrollbar above or below the thumb to
move one <em>page</em> in that direction.
<li>Middle-click on the scrollbar above or below the thumb to jump to that
specific position of the page.
<li>Click the scrollbar arrows to move the view one <em>step</em> in
that direction.
<li>Rotate the mouse wheel over the vertical scrollbar to move one
<em>page</em> in that direction.
</ul>
</li>
</ul>
<p>You can control the <b>size of a <em>step</em></b> by setting the
<code>scroll_step</code> option in the <a href="#dillorc">dillorc</a>
configuration file. By default it will scroll 100 pixels per step. The vertical
scrollbar can be positioned on the left side setting the
<code>scrollbar_on_left</code> option to <code>YES</code>, by default it is on
the right side.</p>
The vertical scrollbar has another mode of operation to navigate full
<em>pages</em> that can be enabled by setting the
<code>scrollbar_page_mode</code> option to <code>YES</code> or temporarily by
holding the Shift key. When this mode is active, left-clicking anywhere on the
scrollbar will scroll down one page and right-clicking will scroll up one page.
Middle clicking on the scrollbar will move the thumb to that position, which can
also be dragged. The Shift key can also be used to temporarily disable this
mode if it was enabled in the configuration.
<h3 id="find-text">Find text</h3>
<p>
To find text in a document right-click to open the <em>Page menu</em> and select
<em>Find text</em> or press <code>Ctrl+F</code> on the keyboard. Then type the
substring that you want to find and click Next (or the <code>Enter</code> key).
</p>
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.
<p>
To close the find bar you can click on the red X on the bottom right or press
ESC.
<h3 id="copy-and-paste">Copy and paste</h3>
<p>
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.
<p>
If you want to select more than one screen, hold the mouse left button down and
scroll with PgUp, PgDn or the arrow keys.
<P>
If you want to paste an URL into Dillo, do it on the "clear-URL"
button (the "X" next to the <a href="#location-bar">location bar</a>).
<p>
<h3 id="zoom">Zoom</h3>
<p>
You can increase or decrease the size of the elements of a page by changing the
zoom factor. Use <code>Ctrl +</code> to increase the size, <code>Ctrl -</code>
to decrease it and <code>Ctrl 0</code> to reset the value to 100%.
<p>
The initial zoom factor is specified by the <code>zoom_factor</code> option in
the <a href="#dillorc">dillorc</a> configuration file. When a new tab or window
is opened, the current zoom factor value is inherited.
<h2 id="navigation">Navigation</h2>
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.
<h3 id="hyperlinks">Hyperlinks</h3>
<p>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:
<p style="text-align: center">
<img
style="border: solid 1px #ddd;"
alt="hand shaped cursor"
src="data:image/gif;base64,R0lGODlhGAAYAPYAAAAAAAEBAQICAgQEBAcHBx4eHiwsLC8vLzo6Oj09PVZWVldXV1xcXF1dXWlpaWxsbG5uboODg52dnZ6enqCgoKKioqWlpaampqioqKqqqq+vr7S0tLW1tbe3t7u7u7y8vL6+vr+/v8HBwcTExMfHx8jIyMzMzNLS0tPT09jY2Nra2tvb29zc3N3d3d7e3t/f3+Dg4OLi4uPj4+Tk5OXl5efn5+jo6Onp6erq6uvr6+zs7O7u7u/v7/Hx8fLy8vT09Pb29vf39/j4+Pn5+fr6+vv7+/z8/P39/f7+/v///wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH5BAAAAAAALAAAAAAYABgAAAfMgEmCg4SFhoeFQUGIjINEIDQ0IESNiDoxCQg0OZWHMUkAAEkunYakoUkqpYWnoidBRIqrrUmRHJEePYuNtJlJmTqRk4y0qKiZm4ZEy6qhLsaiqKSOJioqHCNEodsNzqiqgz0iDgYSOdrb6duphDkgD6EGEer07IM6GTkL9Pyi4IJEYlCg0a1fOnuOXJjbZxAAASLTCEFc2NCAiogSFdJ4QIBfAREDEUGkMMyQwBK7DhGhMUKDhZcwM3A40aNTEB05curMoYPSqp9ADQUCADs=">
<p>
Links to other pages usually appear in
<span style="color:blue; text-decoration: underline">blue and underlined</span>
by default and once they are visited they change to
<span style="color:purple; text-decoration: underline">purple</span>.
However, this is not always the case, so using the mouse cursor shape is the
best indicator of a
<em><a style="color:black; text-decoration: none" href="#">link</a></em>.
<p>
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.
<p>
<h3 id="history">History</h3>
<p>
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.
<p>
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.
<p>
The <code>,</code> (comma) and <code>.</code> (dot) keys can be used to jump
backwards or forward (mnemonic: those keys are usually labeled "<" and
">").
<h3 id="location-bar">Location bar</h3>
<p>
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.
<p>
The red <b style="color: darkred">x</b>
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
<b style="color: darkred">x</b>
button to go to the URL in the clipboard.
<p>
You can also select the location bar content from the keyboard by pressing
<code>Ctrl+L</code>.
<h3 id="web-search">Web search</h3>
<p>
Several search engines are available by pressing the magnifying glass icon next
to the location bar or by pressing <code>Ctrl+S</code>. The search engines are
configured in <a href="#dillorc">Dillorc</a> with the option
<code>search_url</code>. Use it multiple times to define multiple search
engines.
<p>
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:<br>
<pre>
search_url="dd DuckDuckGo http://duckduckgo.com/lite/?kp=-1&kd=-1&q=%s"
</pre>
<p>
Defines the "DuckDuckGo" search engine with the prefix "<code>dd</code>", so you
can type in the location bar "<code>dd dillo browser</code>" to search with
DuckDuckGo for the keywords "dillo browser".
<h3 id="tabs">Tabs</h3>
<p>
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. A new tab can also be opened from the <code>File</code> menu or
using the shortcut <code>Ctrl+T</code>.
<p>
Press <code>Shift</code> while middle-clicking a link to automatically focus the
new tab. If you want this behaviour to be the default, set the following option
in the <a href="#dillorc">dillorc</a> configuration file:
<pre>
focus_new_tab=YES
</pre>
If this option is set, pressing <code>Shift</code> middle-clicking will instead
avoid focusing the new tab.
<p>
It is also possible to have the middle-click open a window instead of a tab. For
this set the option:
<pre>
middle_click_opens_new_tab=NO
</pre>
<p>
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:
<pre>
right_click_closes_tab=NO
</pre>
<p>
Use the <code>new_tab_page</code> option to control which page is loaded in a
newly opened tab, by default is an empty page. To open the
bookmarks page set the following line in <a href="#dillorc">dillorc</a>:
<pre>
new_tab_page="dpi:/bm/"
</pre>
<h3 id="bookmarks">Bookmarks</h3>
<p>
Dillo can save URLs of web pages as bookmarks so you can open them later. To
bookmark the current page, open the <em>Page menu</em> by right-clicking on the
page and select "Bookmark this page" (it also works over a link).
<p>
To see or edit the bookmarks, click on the Bookmarks button on the panel or
press <code>Ctrl+B</code>.
<p>
Bookmarks are handled by a built-in Dillo plugin named <code>bm</code> (read more
about plugins in the <a href="#plugins">Plugins section</a>) and are
synchronized across all instances of the browser. The list of bookmarks can also
be shown by opening the URL <a href="dpi:/bm/"><code>dpi:/bm/</code></a>.
<p>
The bookmarks are stored in a simple plain text file named <code>bm.txt</code>
(see the details of this file in the <a href="#bm-txt">bm.txt section</a>). You
can edit the file directly to change the bookmarks.
<h2 id="privacy-and-network">Privacy and network</h2>
<p>The default privacy policy in Dillo attempts to keep the user safe from
tracking, <em>even if this policy breaks a lot of website functionality</em>. In
this section you can add exceptions or relax the configuration at your own risk.
<h3 id="https">HTTPS</h3>
<p>Dillo has support for
<a href="https://en.wikipedia.org/wiki/HTTPS">HTTPS</a>,
allowing secure connections to remote websites. Use the protocol
"<code>https:</code>" 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.
<p>
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:
<pre>
$ dillo
dillo_dns_init: Here we go! (threaded)
TLS library: <u>OpenSSL 3.2.1 30 Jan 2024</u>
...
</pre>
<h3 id="cookies">Cookies</h3>
<p>
Due to privacy concerns, <b>cookies are disabled by default</b> unless
explicitly enabled in the configuration.
<p>
Support for cookies is implemented using a built-in plugin that shares them
between several instances of Dillo and follows the
<a href="http://tools.ietf.org/html/rfc6265">RFC 6265</a>
specification. Current cookie limits are 20 per domain and
1200 in total.
<p>Cookies are configured by the <code>cookiesrc</code> configuration file. See
the <a href="#cookiesrc">Cookiesrc section</a> to see how to enable cookies for
some domains or accept them by default.</p>
<h3 id="proxy">Proxy</h3>
<p>Dillo can use a HTTP proxy by setting the environment variable
<code>http_proxy</code> or the
<a href="#dillorc">configuration option</a> with the same name. All HTTP and
HTTPS traffic will be sent through the proxy.
<p><b>Note</b>: Plugins may not implement proxy support.
</p>
<h3 id="ad-blocking">Ad blocking</h3>
<p>Dillo has the ability to block content when loading a page based on the domain
the embedded 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.</p>
<p>See the <a href="#domainrc">domainrc</a> configuration file to find out how to
specify which domains are blocked or allowed.</p>
<h3 id="downloads">Downloads</h3>
<p>Downloads are made using
<a href="http://www.gnu.org/software/wget/">wget</a>
with a <a href="http://www.fltk.org">FLTK</a>-based GUI wrapper, through
the <a href="#plugins">Dillo plugin (dpi) framework</a>.
If you close the browser window, downloads will continue.</p>
<h3 id="images-off-mode">Images-off mode</h3>
<p>
You can browse without images now:
<ul>
<li>There is an option in the Tools menu to disable automatic image loading.
An image's alt text (or <code>[IMG]</code> placeholder) will appear in the
page.
<li>If you want to load an individual image, left click on its text.
<li>You can set "no images" as the default mode in dillorc.
</ul>
<h2 id="configuration">Configuration</h2>
<p>Dillo has <b>several configuration files</b> that control the behavior of the
browser. Each configuration file is searched <em>first</em> in the
<a href="file:~/.dillo"><code>~/.dillo</code></a> directory and,
<em>if not found</em>, in the default system configuration directory (typically
<code>/etc/dillo</code>).</p>
<p>Most configuration files can include comments by <em>starting</em> a line
with the "<code>#</code>" symbol. Their specific syntax is described in the
following sections.</p>
<h3 id="dillorc">Dillorc</h3>
<p>The main configuration of Dillo is controlled by the
<a href="file:~/.dillo/dillorc"><code>dillorc</code></a> file.
The list of all available options can be found in the system
configuration file, typically
<a href="file:/etc/dillo/dillorc"><code>/etc/dillo/dillorc</code></a>. You may
want to copy it into
<a href="file:~/.dillo/dillorc"><code>~/.dillo/dillorc</code></a>
and edit it to suit your needs.</p>
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:
<ul>
<li>"<code>#option=...</code>" shows the built-in default.</li>
<li>"<code># option=...</code>" is an additional example.</li>
<li>"<code>option=...</code>" overrides the built-in value.</li>
</ul>
<p>The <code>search_url</code> option can be specified multiple times:
<pre>
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"
</pre>
<h3 id="cookiesrc">Cookiesrc</h3>
<p>Cookies are configured in the
<a href="file:~/.dillo/cookiesrc"><code>~/.dillo/cookiesrc</code></a>
file by using rules, with one rule per line. The rule syntax is very simple,
first specify the <em>host</em> and then the <em>action</em>, separated by
white spaces. Comment lines start with <code>#</code> as the first character and
the whole line is ignored.
<p>
The host can be in the form <code>example.com</code> to match only that
domain or <code>.example.com</code> to match all subdomains of example.com. The
special word <code>DEFAULT</code> specifies the default policy, when no other
match occurs.
<p>
The action can be: <code>DENY</code> to ignore cookies,
<code>ACCEPT_SESSION</code> to only accept session cookies but don't save them
to disk and <code>ACCEPT</code> to accept and store cookies in disk (this will
allow sites to track you over time).
<p>
When the cookies plugin exits, only the accepted cookies by <code>ACCEPT</code>
are saved to
<a href="file:~/.dillo/cookies.txt"><code>~/.dillo/cookies.txt</code></a>,
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 <code>dpidc stop</code>.
<p>
Here is an example <code>cookiesrc</code> file:
<pre>
# host action
DEFAULT DENY
fltk.org ACCEPT
.example.com ACCEPT_SESSION
</pre>
<p> Which is parsed as follows:</p>
<ul>
<li>Line 1: Comment line begins with <code>#</code>.</li>
<li>Line 2: Deny all cookies from all domains not otherwise specified (this is
the default).
<li>Line 3: Accept all cookies from fltk.org, and save them to disk when the
cookie plugin exits.</li>
<li>Line 4: Accept all cookies from all subdomains of example.com, but do not
save them when the cookie plugin exits.</li>
</ul>
<p>
Dillo is especially concerned about privacy and security issues. Our advice is
to <em>avoid cookies whenever possible</em> and at most set ACCEPT_SESSION to
<em>specific trusted sites</em>.
<h3 id="domainrc">Domainrc</h3>
<p>With the
<code>~/.dillo/domainrc</code>
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.
<p>
The file contains one rule per line. Comments are specified by starting the line
with the <code>#</code> symbol. The default rule is either
<code>default accept</code> or <code>default deny</code> and will cause Dillo
to, respectively, accept all requests by default or deny all requests by
default.
<p>
Depending on the default rule, the next rules behave as exceptions by denying
specific connections or allowing specific connections, respectively.
<p>
Exceptions to the default rule are written in the format
<code>source destination</code>, and match request from the source domain to the
destination domain. The source and destination domains can be specified in three
ways:
<ul>
<li>"<code>*</code>" to match any domain</li>
<li>"<code>example.com</code>" to match the specific host example.com</li>
<li>"<code>.example.com</code>" to match example.com and any of its
subdomains</li>
</ul>
<p>
Here is an example:
<pre>
# Accept all requests by default
default accept
# But block some ad-sites and trackers from any domain
* .doubleclick.net
* .googleadservices.com
* .quantserve.com
</pre>
<h3 id="style-css">Style.css</h3>
<p>Custom
<a href="https://en.wikipedia.org/wiki/CSS">CSS styles</a> can be placed in the
<a href="file:~/.dillo/style.css"><code>~/.dillo/style.css</code></a>
file to set default web page styles. To override page styles add the
"<code>!important</code>" flag.
<h3 id="dpidrc">Dpidrc</h3>
<p>The configuration for <a href="#plugins">plugins</a> is placed in the
<a href="file:~/.dillo/dpidrc"><code>~/.dillo/dpidrc</code></a> file.</p>
<p>Plugins are searched in the <code>~/.dillo/dpi/</code> directory first, and
then in the system directory if not found. The <code>dpi_dir</code> option
sets the system <code>dpi</code> directory and must be specified once. Here is
an example:</p>
<pre>
dpi_dir=/usr/lib/dillo/dpi
</pre>
<p>By default, plugins will receive requests at the URL
<code>dpi:/<em>name</em>/</code>, for example bookmarks are available at
<a href="dpi:/bm/"><code>dpi:/bm/</code></a>.
<p>Plugins can also be associated with a protocol (like "<code>file:</code>").
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
<code>proto.<em>name</em>=<em>path-to-plugin.dpi</em></code>. The path of the
plugin is relative to the <code>dpi</code> directory. Here are protocols
used by the built-in plugins:</p>
<pre>
proto.file=file/file.dpi
proto.ftp=ftp/ftp.filter.dpi
proto.data=datauri/datauri.filter.dpi
</pre>
<p>Here (
<img alt="red dot"
src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==">
) is an example image using the <code>data:</code> protocol used to define a PNG
image inline in a HTML document.
</p>
<h3 id="bm-txt">bm.txt</h3>
<p>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
<a href="file:~/.dillo/bm.txt"><code>~/.dillo/bm.txt</code></a>. The file can be
modified by using the
<a href="dpi:/bm/">Book button</a>
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).</p>
<p>The syntax of the <code>bm.txt</code> file is described as follows:</p>
<p>First, the sections are defined at the beginning, prefixed with a
<code>:s<em>N</em>:</code> identifier, along with the description of the
section:</p>
<pre>
:s0: News
:s1: Blog
</pre>
<p>Then every bookmark is added in a single line, by writing the section
identifier, the URL and a description:</p>
<pre>
s0 https://slashdot.org Slashdot
s0 https://news.ycombinator.com/ Hacker News
s1 https://100r.co/site/log.html 100 Rabbits Log
</pre>
<p>The <code>bm.txt</code> file is designed to be <em>easily</em> read by humans
and is suitable to be kept updated among machines by using a version control
tool.
<h3 id="keysrc">Keysrc</h3>
<p>The mapping of keys in Dillo is controlled by the
<a href="file:~/.dillo/keysrc"><code>~/.dillo/keysrc</code></a> file.
The format is "<code>key = action</code>" or
"<code><modifier>key = action</code>". Lines that begin with a "#" are comments.
The commented-out bindings below show the defaults built into Dillo.
<ul>
<li>Modifiers recognized: Shift, Ctrl, Alt, Meta (on Mac OS X use "Meta" for
Command).
<li>Key names recognized: Backspace, Delete, Down, End, Esc, F1 through
F12, Home, Insert, Left, Menu, PageDown, PageUp, Print, Return, Right, Space,
Tab, Up.
<li>Multimedia keys: Back, Favorites, Forward, HomePage, Mail, MediaNext,
MediaPlay, MediaPrev, MediaStop, Refresh, Search, Sleep, Stop, VolumeDown,
VolumeMute, VolumeUp.
</ul>
<p>If Dillo is running under X11, keys whose names are not recognized can be
specified using their keysym value in hexadecimal. Use <code>xev</code> to get
the keysym, for example:
<pre>
0x1008ff27 = forward
</pre>
<p>The action "nop" (no operation) can be used to remove a binding.
<p>Example file:</p>
<pre>
# "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
</pre>
<h2 id="advanced-usage">Advanced usage</h2>
These sections focus on advanced topics and are recommended for experienced
users of Dillo.
<h3 id="plugins">Plugins</h3>
<p>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.</p>
<p>Plugins can be written in <em>any programming language</em> and they
interact with the browser using the
<a href="https://dillo-browser.github.io/old/dpi1.html">DPI protocol</a>. A
<a href="https://dillo-browser.github.io/#plugins">list of plugins</a>
is available on the Dillo website. Some plugins are just a
<a href="https://raw.githubusercontent.com/dillo-browser/dillo-plugin-man/master/man.filter.dpi">few
lines of shell script</a>, 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 <code>.dpi</code> extension (or <code>.dpi.exe</code> in Windows) in
<code>~/.dillo/dpi</code> and <code>dpi_dir</code> (see the
<a href="#dpidrc">Dpidrc</a> configuration section).</p>
<p>There are two types of plugins: <em>filters</em> and <em>servers</em>.
Filters are executed for each request like a
<a href="https://en.wikipedia.org/wiki/Pipeline_(Unix)">UNIX pipe</a>,
they read from the
standard input and write to the standard output. The name of filter plugin
programs must end in <code>.filter.dpi</code>. 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.</p>
<p>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 <code>~/.dillo/dpi/<em>name</em>/</code> and
then associate the <em>name</em> protocol to the program that must run in
the
<a href="file:~/.dillo/dpidrc"><code>~/.dillo/dpidrc</code></a> file.
Plugins may have other software dependencies required for it to work.</p>
<p>Here is an example of how to manually install the
<a href="https://github.com/dillo-browser/dillo-plugin-gemini">Gemini protocol plugin</a>
(it comes with a Makefile that automates the process, so this is not necessary),
which is a filter plugin written in shell script:</p>
<pre>
$ 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
</pre>
<p>Now, when a request is made to an URL that begins with the
<code>gemini:</code> protocol, it will be processed by the
<code>gemini/gemini.filter.dpi</code> program, and the output will be displayed
by Dillo.</p>
<h3 id="bug-meter">Bug Meter</h3>
<p>
Dillo includes a
<a href='https://dillo-browser.github.io/old/help/bug_meter.html'>bug meter</a>
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.
<p>
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.
<p>
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.
<h3 id="keyboard-shortcuts">Keyboard shortcuts</h3>
<p>
Most actions can be issued by using a keyboard shortcut. The key bindings can be
changed in the
<code><a href="file:~/.dillo/keysrc">~/.dillo/keysrc</a></code> file (see the
<a href="#keysrc">keysrc</a> section).
The list of default bindings is given in the following table.
<p>
<table>
<tr><th>Shortcut <th>Mnemonic <th>Function
<tr><td>Ctrl-L <td>Location <td>Enter a new URL
<tr><td>Ctrl-F <td>Find <td>Find text
<tr><td>Ctrl-S <td>Search <td>Search the web
<tr><td>Ctrl-R <td>Reload <td>Reload current page
<tr><td>Ctrl-N <td>New <td>New browser window
<tr><td>Ctrl-T <td>Tab <td>New tab
<tr><td>Ctrl-W <td>Window <td>Quit tab/window
<tr><td>Ctrl-O <td>Open <td>Open file
<tr><td>Ctrl-U <td> <td>View source
<tr><td>Ctrl-B <td>Bookmarks <td>View bookmarks
<tr><td>Ctrl-Q <td>Quit <td>Quit dillo
<tr><td>Ctrl-+ or Ctrl-= <td>Bigger <td>Zoom in
<tr><td>Ctrl-- <td>Smaller <td>Zoom out
<tr><td>Ctrl-0 <td>100% <td>Reset zoom to 100%
<tr><td>Back or "<b>,</b>" <td>< <td>Previous page
<tr><td>Shift-Back or "<b>.</b>" <td>> <td>Next page
<tr><td>Alt-F <td>File <td>File menu
<tr><td>Ctrl-Tab or<br>
Ctrl-PageDown <td>Tab <td>Next tab
<tr><td>Ctrl-Shift-Tab or<br>
Ctrl-PageUp <td>Tab <td>Previous tab
<tr><td>Esc <td>escape <td>Close dialog,
Close findbar,<br>
Hide/show control panels
</table>
<footer>
<p>This manual has been written in HTML <em>by hand</em> using Vim.<br>
If you find any issue, please report it via
<a href="https://github.com/dillo-browser/dillo/issues/new">GitHub</a> or
<a href="mailto:dillo-dev@mailman3.com">email</a>.
</footer>
</div>
</body>
</html>
|
