Add a setting to read additional config files from any other config
[xxxterm.git] / xxxterm.1
bloba9bc91a887b76120c9d8743ee5ec124d4cfc7461
1 .\"     $xxxterm$
2 .\"
3 .\" Copyright (c) 2010, 2011 Marco Peereboom <marco@peereboom.us>
4 .\" Copyright (c) 2011 Jason McIntyre <jmc@openbsd.org>
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .Dd $Mdocdate: October 14 2011 $
19 .Dt XXXTERM 1
20 .Os
21 .Sh NAME
22 .Nm xxxterm
23 .Nd lightweight web browser
24 .Sh SYNOPSIS
25 .Nm xxxterm
26 .Bk -words
27 .Op Fl nSTtV
28 .Op Fl f Ar file
29 .Op Fl s Ar session_name
30 .Op Ar url ...
31 .Ek
32 .Sh DESCRIPTION
33 .Nm
34 is a minimalistic web browser that tries to stay out of the way so that
35 valuable screen real estate can be used for much more important stuff.
36 It has sane defaults and does not require one to learn a language to do any
37 configuration.
38 It was written by hackers for hackers
39 and it strives to be small, compact, and fast.
40 .Pp
41 .Nm
42 is very simple in its use.
43 Most actions are initiated via key or mouse bindings.
44 Key bindings are based on those of the
45 .Xr vi 1
46 text editor,
47 giving web browsing a similar feel to navigating a text document.
48 The
49 .Sx KEY BINDINGS
50 section below documents the various defaults and possible customizations.
51 .Pp
52 The options are as follows:
53 .Bl -tag -width Ds
54 .It Fl f Ar file
55 Specify an alternative configuration file.
56 .It Fl n
57 Open a new tab in a running
58 .Nm
59 for each specified URL.
60 This option requires
61 .Cm enable_socket
62 to be enabled.
63 .It Fl e Ar command
64 Execute arbitrary command (see the
65 .Sx COMMAND MODE
66 section below) in a running
67 .Nm
68 instance. This option requires
69 .Cm enable_socket
70 to be enabled. Example run: xxxterm -e "tabnew openbsd.org"; xxxterm -e
71 tabclose; xxxterm -e wq.
72 .It Fl S
73 Disable the toolbar.
74 .It Fl s Ar session_name
75 Open session that was saved with ":session save" command.
76 .It Fl T
77 Disable visualization of tabs.
78 .It Fl t
79 Disable tabs.
80 .It Fl V
81 Display version and exit.
82 .El
83 .Sh FAST STARTUP
84 The following notation is used throughout this page:
85 .Pp
86 .Bl -tag -width Ds -offset indent -compact
87 .It Cm C-
88 Control
89 .It Cm S-
90 Shift
91 .It Cm M1-
92 Meta 1 (sometimes marked Alt)
93 .It Cm M2-
94 Meta 2
95 .It Cm M3-
96 Meta 3
97 .It Cm M4-
98 Meta 4 (sometimes marked Windows)
99 .It Cm M5-
100 Meta 2
101 .It Cm MB1
102 Mouse button 1
105 To browse to a specific address,
106 either use the mouse to click on the address bar
107 or press
108 .Cm F6
109 to shift the keyboard focus to the address bar.
110 The address is then entered manually.
112 The mouse can be used to navigate the page in the traditional manner,
113 or the keyboard can be used instead.
114 For example,
115 .Cm PageUp
117 .Cm PageDown
118 will scroll up and down the page.
120 To follow a link,
121 either click on it or use the
122 .Cm f
123 key and have
125 assign numbers to each link on the page;
126 entering that number on the keyboard will prompt
128 to follow the link.
129 .Sh KEY BINDINGS
131 provides many actions accessed via key or mouse bindings.
132 Most can be reprogrammed using a
133 .Cm keybinding
134 entry in the configuration file.
135 Each keyboard shortcut requires exactly one entry in the configuration file.
136 A shortcut can have multiple entries in the configuration file.
137 The format of the keybinding entry is as follows:
139 .D1 keybinding = action,(!)keystroke(s)
141 For example, "keybinding = tabnew,C-t" where
142 .Cm tabnew
143 is the action and
144 .Cm C-t
146 the keystrokes.
147 GTK has some default keybindings for manipulating text inside input
148 fields, such as the URI or search entry widget, for example
149 .Cm C-w
150 deletes a word. To override these defaults prefix your key with an
151 exclamation mark, like this: "keybinding = tabclose,!C-w".
153 .Cm clearall
154 key word is special and is meant to reset the key binding list to the GTK+
155 and WebKit defaults.
156 This keyword should be the first
157 .Cm keybinding
158 entry in the configuration file.
160 Shift should be used sparingly since it gets in the way of non-USA keyboards.
161 See the accompanying configuration file for examples.
163 The various bindings are documented below.
164 The relevant keybinding action is given afterwards, in parentheses.
165 .Ss Command mode
166 These commands are used to focus or unfocus input on the default input of a web
167 page.
169 .Bl -tag -width Ds -offset indent -compact
170 .It Cm ESC
171 Go to command mode; unfocus current entry on web page.
172 .Pq Cm command_mode
173 .It Cm i
174 Go to insert mode; focus on default entry on web page.
175 .Pq Cm insert_mode
177 .Ss Search Commands
178 These commands are used to search for text strings within a web page.
180 .Bl -tag -width Ds -offset indent -compact
181 .It Cm /
182 Start a search
183 .Pq Cm search
184 .It Cm \&?
185 Start a backwards search
186 .Pq Cm searchb
187 .It Cm n
188 Next item matching search
189 .Pq Cm searchnext
190 .It Cm N
191 Previous item matching search
192 .Pq Cm searchprev
194 .Ss Focus Commands
195 These commands are used to shift the focus of
197 from one area to another.
199 .Bl -tag -width Ds -offset indent -compact
200 .It Cm F6
201 Focus on address bar
202 .Pq Cm focusaddress
203 .It Cm F7
204 Focus on search entry
205 .Pq Cm focussearch
207 .Ss Command Aliases
208 These commands allow the user to map specific actions to specific keys.
209 It can be useful when the
210 .Fl S
211 option is used.
213 .Bl -tag -width Ds -offset indent -compact
214 .It Cm F1
215 Alias for ":help"
216 .It Cm F2
217 Alias for ":proxy toggle"
218 .It Cm F4
219 Alias for ":toplevel toggle"
220 .It Cm F9
221 Alias for ":open"
222 .Pq Cm promptopen
223 .It Cm F10
224 Alias for ":open current-uri"
225 .Pq Cm promptopencurrent
226 .It Cm F11
227 Alias for ":tabnew"
228 .Pq Cm prompttabnew
229 .It Cm F12
230 Alias for ":tabnew current-uri"
231 .Pq Cm prompttabnewcurrent
233 .Ss Navigation Commands
234 These commands allow the user to navigate web pages and,
235 to some extent,
236 control the browser.
238 .Bl -tag -width "Space, C-f, PageDownXXX" -offset indent -compact
239 .It Cm F5, C-r, C-l
240 Reload page
241 .Pq Cm reload
242 .It Cm Backspace, M-Left
243 Previous page
244 .Pq Cm goback
245 .It Cm S-BackSpace, M-Right
246 Forward page
247 .Pq Cm goforward
248 .It Cm j, Down
249 Next line on page
250 .Pq Cm scrolldown
251 .It Cm k, Up
252 Previous line on page
253 .Pq Cm scrollup
254 .It Cm G, End
255 Bottom of page
256 .Pq Cm scrollbottom
257 .It Cm gg, Home
258 Top of page
259 .Pq Cm scrolltop
260 .It Cm Space, C-f, PageDown
261 Page down
262 .Pq Cm scrollpagedown
263 .It Cm C-b, PageUp
264 Page up
265 .Pq Cm scrollpageup
266 .It Cm l, Right
267 Page right
268 .Pq Cm scrollright
269 .It Cm h, Left
270 Page left
271 .Pq Cm scrollleft
272 .It Cm $
273 Page far right
274 .Pq Cm scrollfarright
275 .It Cm 0
276 Page far left
277 .Pq Cm scrollfarleft
278 .It Cm M-f
279 Favorites
280 .Pq Cm fav
281 .It Cm M-j
282 Cookie jar
283 .Pq Cm cookiejar
284 .It Cm M-d
285 Download manager
286 .Pq Cm dl
287 .It Cm C-p
288 Print page
289 .Pq Cm print
290 .It Cm M-h
291 Global history
292 .Pq Cm history
293 .It Cm C-j
294 Toggle Java Script enabled for FQDN
295 .Pq Cm js
296 .It Cm C-s
297 Toggle source view
298 .Pq Cm togglesrc
299 .It Cm M-c
300 Toggle cookie enabled for FQDN
301 .Pq Cm cookie
302 .It Cm M-p
303 Toggle plugins enabled for FQDN
304 .Pq Cm plugin
306 .Ss Tab Manipulation
308 supports tabbed browsing.
309 That is, web pages may be opened in separate tabs,
310 allowing the user to quickly move from one page to another,
311 and back.
312 These commands then are used to create, destroy, and move between tabs.
314 .Bl -tag -width "C-plus, C-equalXXX" -offset indent -compact
315 .It Cm C-MB1
316 Open new tab with the clicked link
317 .It Cm C-t
318 Create new tab with focus in URL entry
319 .Pq Cm tabnew
320 .It Cm C-T
321 Create new tab with focus in URL entry as the last tab in the browser
322 .Pq Cm 999tabnew
323 .It Cm C-w
324 Destroy current tab
325 .Pq Cm tabclose
326 .It Cm U
327 Undo close tab
328 .Pq Cm tabundoclose
329 .It Cm C-Left, C-PageUp
330 Go to the previous tab
331 .Pq Cm tabprevious
332 .It Cm C-Right, C-PageDown
333 Go to the next tab
334 .Pq Cm tabnext
335 .It Cm C-[1..9]
336 Jump to page
337 .Ar N
338 .Pq Cm tabnext [1..9]
339 .It Cm C-<
340 Jump to first page
341 .Pq Cm tabfirst
342 .It Cm C->
343 Jump to last page
344 .Pq Cm tablast
345 .It Cm C-minus
346 Zoom out by 4%
347 .Pq Cm focusout
348 .It Cm C-plus, C-equal
349 Zoom in by 4%
350 .Pq Cm focusin
351 .It Cm C-0
352 Set zoom level to 100%
353 .Pq Cm focusreset
355 .Ss Yanking and pasting
356 These commands copy and paste text to and from the clipboard.
358 .Bl -tag -width Ds -offset indent -compact
359 .It Cm p
360 Paste the contents of the clipboard into the address bar
361 .Pq Cm pasteuricur
362 .It Cm P
363 Paste the contents of the clipboard into a new tab
364 .Pq Cm pasteurinew
365 .It Cm y
366 Yank the current URL into the clipboard
367 .Pq Cm yankuri
369 .Ss Hyperlink Following
370 This allows the user to follow hyperlinks
371 without using a mouse.
372 Enter the corresponding number to follow the link.
373 Alternatively one can type the name of the link and when there are no more
374 possibilities
376 will follow the link.
378 .Bl -tag -width Ds -offset indent -compact
379 .It Cm f, '.'
380 Highlight all links and prefix them with a number.
381 .Pq Cm hinting
382 .It Cm F, ','
383 Highlight all links and prefix them with a number but open in a new tab.
384 .Pq Cm hinting_newtab
386 .Ss Exiting
387 Commands to exit the browser.
389 .Bl -tag -width Ds -offset indent -compact
390 .It Cm C-q
391 Quit
392 .Pq Cm quitall
394 .Ss Low-Contrast Color Scheme
395 These commands toggle the page style between the default CSS and a
396 low-contrast color scheme with light grey text on a dark grey background.
398 .Bl -tag -width Ds -offset indent -compact
399 .It Cm s
400 Toggle the current tab's style.
401 .Pq Cm userstyle
402 .It Cm S
403 Toggle the global page style mode.
404 Will also affect new tabs.
405 .Pq Cm userstyle_global
407 .Ss Insert-mode commands
408 The following commands are only available when editing an input-field
410 .Bl -tag -width Ds -offset indent -compact
411 .It Cm C-i
412 Edit the contents of the currently active input-element in an external editor.
413 .Pq Cm editelement
415 .Sh COMMAND MODE
416 Command mode works in a similar fashion to the
417 .Xr vi 1
418 editor;
419 it is entered by typing a colon and exited by typing Esc.
420 The commands and their descriptions are listed below.
421 .Bl -tag -width Ds -offset indent
422 .It Cm about , version
423 Show the "About" page.
424 .It Cm buffers , ls , tabs
425 Displays the currently open tabs and lets the user switch tab by typing
426 the tab number or using the mouse.
427 .It Cm ca
428 Display CA certificates.
429 .It Cm cert , cert show
430 Download and display certificates of domain on tab.
431 .It Cm cert save
432 Save certificate into a local store.
433 The next time the site is visited it is compared against the store.
434 If the certificate matches,
435 the address bar will be blue;
436 if it doesn't the bar will be red.
437 .It Cm cookie
439 .Cm cookie
440 command is used to manipulate the cookie whitelist.
441 Used by itself it expands to
442 .Cm cookie show all .
443 .It Cm cookiejar
444 Show cookie jar contents.
445 .It Cm cookie purge
446 Remove all cookies from the cookie jar.
447 .It Cm cookie save, cookie save fqdn
448 Save the current fully qualified domain name (FQDN)
449 to the persistent whitelist.
450 For example,
451 the www.peereboom.us domain would result in saving .www.peereboom.us.
452 .It Cm cookie save domain
453 Save the top level domain name to the persistent whitelist.
454 For example,
455 the www.peereboom.us domain would result in saving .peereboom.us.
457 This action enables cookies if it is currently disabled for this entry.
458 .It Cm cookie show all
459 Show all persistent and session entries in the cookie whitelist.
460 .It Cm cookie show persistent
461 Show all persistent entries in the cookie whitelist.
462 .It Cm cookie show session
463 Show all session entries in the cookie whitelist.
464 .It Cm cookie toggle domain
465 Toggle cookie support for the current top level domain.
466 .It Cm cookie toggle, cookie toggle fqdn
467 Toggle cookie support for the current FQDN.
468 .It Cm dl
469 Show download manager.
470 .It Cm encoding <encoding>
472 .Cm <encoding>
473 is set the tab's encoding will be set to
474 .Cm <encoding>
477 reloads the tab.
479 .Cm <encoding>
480 is not set
482 will display the current tab encoding.
483 .It Cm editsrc
484 Opens the source for the current tab in the editor specified by the
485 setting
486 .Cm external_editor
487 and then checks for changes to the file opened. If it is changed, the
488 page will be updated.
489 .It Cm editelement
490 If a text-element is currently active (<input> or <textarea>), it's
491 contents will be opened in the same fashion as for the command
492 .Cm editsrc
493 above
494 .It Cm fav
495 Show favorites.
496 .It Cm favadd
497 Add the current page to favorites.
498 .It Cm fullscreen , f
499 Toggle hiding tabs and url entry toolbar.
500 .It Cm h , hist , history
501 Show global history.
502 .It Cm help
503 Show help page.
504 .It Cm home
505 Go to home URL.
506 .It Cm js
508 .Cm js
509 command is used to manipulate the Java Script whitelist.
510 Used by itself it expands to
511 .Cm js show all .
512 .It Cm js save, save fqdn
513 Saves the FQDN to the persistent whitelist.
514 For example,
515 the www.peereboom.us domain would result in saving .www.peereboom.us.
516 .It Cm js save domain
517 Saves the top level domain name to the persistent whitelist.
518 For example,
519 the www.peereboom.us domain would result in saving .peereboom.us.
521 This action enables Java Script if it is currently disabled for this entry.
522 .It Cm js show all
523 Shows all persistent and session entries in the JS whitelist.
524 .It Cm js show persistent
525 Shows all persistent entries in the JS whitelist.
526 .It Cm js show session
527 Shows all session entries in the JS whitelist.
528 .It Cm js toggle, js toggle fqdn
529 Toggle Java Script execution for the current FQDN.
530 .It Cm js toggle domain
531 Toggle Java Script execution for the current top level domain.
532 .It Cm loadimages
533 If auto_load_images is disabled, load all images for current site.
534 .It Cm open , op , o URL
535 Open URL.
536 .It Cm plugin
538 .Cm plugin
539 command is used to manipulate the plugin whitelist.
540 Used by itself it expands to
541 .Cm plugin show all .
542 .It Cm plugin save, save fqdn
543 Saves the FQDN to the persistent whitelist.
544 For example,
545 the www.peereboom.us domain would result in saving .www.peereboom.us.
546 .It Cm plugin save domain
547 Saves the top level domain name to the persistent whitelist.
548 For example,
549 the www.peereboom.us domain would result in saving .peereboom.us.
551 This action enables plugins if they are currently disabled for this entry.
552 .It Cm plugin show all
553 Shows all persistent and session entries in the plugin whitelist.
554 .It Cm plugin show persistent
555 Shows all persistent entries in the plugin whitelist.
556 .It Cm plugin show session
557 Shows all session entries in the plugin whitelist.
558 .It Cm plugin toggle, plugin toggle fqdn
559 Toggle plugin execution for the current FQDN.
560 .It Cm plugin toggle domain
561 Toggle plugin execution for the current top level domain.
562 .It Cm print
563 Print page.
564 .It Cm proxy
566 .Cm proxy
567 command is used to manipulate the currently set proxy.
568 Used by itself it expands to
569 .Cm proxy show .
570 .It Cm proxy show
571 Displays the current
572 .Cm http_proxy
573 setting.
574 .It Cm proxy toggle
575 Enables or disables the proxy for
576 .Nm .
577 Note that
578 .Cm http_proxy
579 must be set before it can be toggled.
580 .It Cm qa , qall , quitall
581 Quit
582 .Nm .
583 .It Cm quit , q
584 Close current tab and quit
586 if it is the last tab.
587 .It Cm restart
588 Restart
590 and reload all current tabs.
591 .It Cm run_script [path_to_script]
592 Runs the script path_to_script with the current uri as the argument.
593 If path_to_script is not provided, the value of default_script is used
594 instead.
595 .It Cm script [filename]
596 Run an external JavaScript script file in the current tab context.
597 .It Cm session , Cm session show
598 Display the current session name.
599 By default the session name is main_session.
600 To create a new session use the
601 .Cm session save
602 command.
603 A session is defined as the lifetime of the browser application.
604 .It Cm session delete <session_name>
605 Delete session session_name from persistent storage.
606 If session_name is the current session then the session will revert to
607 main_session.
608 .It Cm session open <session_name>
609 Open session_name and close all currently open tabs.
610 Going forward this session is named session_name.
611 .It Cm session save <session_name>
612 Save current tabs to session_name session.
613 This will close the current session and going forward this session is named
614 session_name.
615 .It Cm set
616 The set command is used to inspect, clear or change runtime options.
617 There are 3 methods to use
618 .Cm :set .
619 When used by itself as
620 .Cm :set
621 the command displays all options as currently set.
623 To set a value use
624 .Cm :set option=value .
625 For example,
626 .Cm :set http_proxy=http://127.0.0.1:8080 .
628 To clear a value use
629 .Cm :set option= .
630 For example,
631 .Cm :set http_proxy= .
633 Note, not all options can be set at runtime.
634 .It Cm stats
635 Show blocked cookie statistics.
636 These statistics vary based on settings and are not persistent.
637 .It Cm statustoggle , statust
638 Toggle status bar.
639 .It Cm stop
640 Stop loading the current web page.
641 .It Cm tabclose
642 Close current tab.
643 .It Cm tabhide
644 Hide tabs.
645 .It Cm tabnew , tabedit [URL]
646 Create new tab and optionally open provided URL.
647 .It Cm tabnext
648 Go to the next tab.
649 .It Cm tabprevious
650 Go to the previous tab.
651 .It Cm tabshow
652 Show tabs in GUI.
653 .It Cm toplevel , toplevel toggle
654 Toggle the top level domain name cookie and JS session whitelist.
655 This is to enable/disable short lived full site functionality without
656 permanently adding the top level domain to the persistent whitelist.
657 .It Cm urlhide , urlh
658 Hide url entry and tool bar.
659 .It Cm urlshow , urls
660 Show url entry and tool bar.
661 .It Cm userstyle
662 Toggle between normal and low contrast mode.
663 .It Cm w
664 Save open tabs to current session.
665 The tabs will be restored next time the session is opened.
666 See the session command for additional details.
667 .It Cm wq
668 Save open tabs and quit.
669 The tabs will be restored next time
671 the session is opened.
672 See the session command for additional details.
674 .Sh BUFFER COMMANDS
675 In addition to shortcuts and commands
677 provides buffer commands. Buffer commands are short, multi character
678 vi-like commands, often requiring an argument. Partial buffer commands
680 displayed in the buffer command statusbar element (see
681 .Cm statusbar_elems ) .
682 Pressing Esc or switching to another tab cancels a partially entered
683 buffer command. In the following list
684 .Cm arg
685 denotes the argument a buffer command accepts. Buffer commands are
686 defined as extended regular experssions.
687 Note that if a character is used as a shortcut it will not be interpreted
688 as the beginning of a buffer command. This is the case with
689 .Cm 0 .
691 .Bl -tag -width "['][a-zA-Z0-9]XXX" -offset indent -compact
692 .It Cm gg
693 go to the top of the page
694 .It Cm gG
695 go to the bottom of the page
696 .It Cm [0-9]+%
697 go to the
698 .Cm arg
699 percent of the page
700 .It Cm zz
701 go to 50% of the page
702 .It Cm [0-9]*gu
704 .Cm arg
705 levels up. If
706 .Cm arg
707 is missing, 1 is assumed. Going a
708 level up means going to a URI obtained from the current one by removing
709 the last slash ('/') character and everything that follows it
710 .It Cm gU
711 go to the root level, i.e. going up as many levels as possible.
712 .It Cm gh
713 open the home page in the current tab
714 .It Cm m[a-zA-Z0-9]
715 set a mark denoted by
716 .Cm arg
717 at the current page position. These marks behave like those in vi or
718 less.
719 .It Cm ['][a-zA-Z0-9']
720 go to the position where mark
721 .Cm arg
722 was set. The special mark "'" points to the previous page position, after a
723 "gg", "gG", "zz", "%" or "'" buffer command.
724 .It Cm M[a-zA-Z0-9]
725 set the current uri as quickmark
726 .Cm arg
727 .It Cm go[a-zA-Z0-9]
728 open the uri marked as quickmark
729 .Cm arg
730 in the current tab
731 .It Cm gn[a-zA-Z0-9]
732 open the uri marked as quickmark
733 .Cm arg
734 in a new tab
735 .It Cm [0-9]+t
736 activate tab number
737 .It Cm g0
738 go to first tab
739 .It Cm g$
740 go to last tab
741 .It Cm [0-9]*gt
742 go to the
743 .Cm arg
744 next tab
745 .It Cm [0-9]*gT
746 go to the
747 .Cm arg
748 previous tab
749 .Cm arg
750 .It Cm ZZ
751 quit
753 .It Cm ZR
754 restart
756 .It Cm zi
757 zoom in by 4%
758 .It Cm zo
759 zoom out by 4%
760 .It Cm z0
761 set zoom level to 100%
762 .It Cm [0-9]+Z
763 set zoom level to
764 .Cm arg
767 .Sh QUICKMARKS
768 Quickmarks are like bookmarks, except they are refered to by a single
769 character (a letter or a digit), instead of a longer name. See the
770 .Cm M[a-zA-Z0-9] ,
771 .Cm go[a-zA-Z0-9]
773 .Cm gn[a-zA-Z0-9]
774 buffer commands for usage. Quickmarks are stored in
775 .Pa ~/.xxxterm/quickmarks
776 and are saved automatically after each
777 .Cm M[a-zA-Z0-9]
778 buffer command.
779 .Sh ABOUT SCREENS
780 The about screens are internally generated web pages by
782 for user interaction.
783 These are entered in the address bar and the format is
784 .Cm about:screen
785 where screen is the desired screen to display.
786 For example about:favorites.
787 Any about screen can be used as the home page as specified by
788 .Cm home
789 in the configuration file.
791 .Bl -tag -width "downloadsXXX" -offset indent -compact
792 .It Cm about
793 show the about screen
794 .It Cm blank
795 show a blank screen
796 .It Cm cookiewl
797 show the cookie whitelist screen
798 .It Cm cookiejar
799 show the cookiejar screen
800 .It Cm downloads
801 show the downloads screen
802 .It Cm favorites
803 show the favorites screen
804 .It Cm help
805 show the help web page
806 .It Cm history
807 show the history screen
808 .It Cm jswl
809 show the Java Script whitelist screen
810 .It Cm set
811 show the settings screen
812 .It Cm stats
813 show the statistics screen
815 .Sh WHITELISTS
816 This section describes advanced usage settings.
817 Most users should use
818 .Cm browser_mode
819 instead to setup
821 and skip over this section.
824 has a number of whitelists to control blocking cookies and Java Script
825 execution for FQDNs or domains.
826 When properly enabled these whitelists require either the FQDN or top level
827 domain to exist in the whitelists in order to allow cookies to be stored or
828 Java Script to execute.
829 Both Java Script and cookies have two whitelists associated with them.
830 The whitelists are called session and persistent.
831 Items in the session whitelists are only allowed for the lifetime of the
833 instance.
834 Items in the persistent whitelists are stored on disk and are restored
835 upon restarting.
837 Setting up the whitelists is a little tricky due to intricacies of WebKit.
838 In fact the semantics are different for cookies and Java Script.
840 Cookie whitelist requires the following configuration to be set:
842 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
843 .It Cm cookies_enabled
844 This is a WebKit setting and must be set to
845 .Pa 1
846 (ENABLED)
847 in order to be able to use a
848 cookie whitelist.
849 .It Cm enable_cookie_whitelist
850 This needs to be set to
851 .Pa 1
852 to enable the cookie whitelist functionality.
853 .It Cm cookie_wl
854 These entries in the configuration file are the actual domains names in the
855 cookie whitelist.
858 Java Script whitelist requires the following configuration to be set:
860 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
861 .It Cm enable_scripts
862 This is a WebKit setting and must be set to
863 .Pa 0
864 (DISABLED)
865 in order to be able to use a
866 Java Script whitelist.
867 .It Cm enable_js_whitelist
868 This needs to be set to
869 .Pa 1
870 to enable the Java Script whitelist functionality.
871 .It Cm js_wl
872 These entries in the configuration file are the actual domains names in the
873 Java Script whitelist.
876 Plugin whitelist requires the following configuration to be set:
878 .Bl -tag -width "enable_plugin_whitelistXXX" -offset indent -compact
879 .It Cm enable_plugins
880 This is a WebKit setting and must be set to
881 .Pa 1
882 (ENABLED)
883 in order to be able to use a
884 plugin whitelist.
885 .It Cm enable_plugin_whitelist
886 This needs to be set to
887 .Pa 1
888 to enable the plugin whitelist functionality.
889 .It Cm pl_wl
890 These entries in the configuration file are the actual domains names in the
891 plugin whitelist.
894 See the
895 .Pa FILES
896 section for additional configuration file entries and details
897 that alter runtime behavior.
898 .Sh FILES
899 .Bl -tag -width "/etc/xxxterm.confXXX" -compact
900 .It Pa ~/.xxxterm.conf
902 user specific settings.
903 .It Pa ~/.xxxterm
905 scratch directory.
909 tries to open the user specific file,
910 .Pa ~/.xxxterm.conf .
911 If that file is unavailable,
912 it then uses built-in defaults.
914 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
915 For example:
917 .Dl http_proxy = http://127.0.0.1:8080
919 Enabling or disabling an option is done by using 1 or 0 respectively.
921 The file supports the following keywords:
923 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
924 .It Cm alias
925 Defines an alias for a given URL, so that the URL is loaded when the alias is
926 entered in the address bar.
927 If the aliased URL includes a %s format specifier, then any argument given after
928 the alias on the address bar is substituted.
929 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
930 then the URL http://www.google.com/search?q=foo is loaded when navigating to
931 "g foo".
932 .It Cm allow_volatile_cookies
933 If set cookies are stored in the session cache but will be discarded once
935 exits.
936 Unfortunately enabling this does allow for some limited tracking on the web.
937 .It Cm append_next
938 When set a new tab is appended after the current tab instead of being appended
939 as the last tab.
940 .It Cm auto_load_images
941 If disabled, images will not be loaded automatically.
942 .It Cm autofocus_onload
943 When set a tab that is loaded will attempt to autofocus the default input
944 entry.
945 This is only done for tabs that are currently visible.
946 .It Cm browser_mode
949 browser has 3 default operating modes:
950 .Pa normal
951 (the default),
952 .Pa whitelist
954 .Pa kiosk .
955 In the
956 .Pa normal
957 mode the browser allows all cookies, plugins and Java Script as any other
958 browser would.
959 This means that all cookies are saved to persistent storage and that all
960 Java Script and plugins run.
962 On the other hand, using the
963 .Pa whitelist
964 mode enables whitelists.
965 This requires the user to add all the required
966 .Pa cookie_wl ,
967 .Pa js_wl
969 .Pa pl_wl
970 items.
971 If a domain does not appear in the whitelists
973 disallows cookies, Java Script and plugin execution.
976 .Pa kiosk
977 mode the browse works just like
978 .Pa normal
979 mode however the toolbar only has the backward, forward and home button.
981 This setting must be the first entry in
982 .Pa ~/.xxxterm.conf
983 because it sets advanced settings that can be overridden later in the file.
984 See the default config file for more details.
985 .It Cm cmd_font
986 Set the command prompt font.
987 E.g.
988 .Pa cmd_font = monospace normal 9 .
989 .It Cm color_visited_uris
990 When enabled (the default)
992 will color visited links. This is done while the web page loads using
993 JavaScript, rather than WebKit's (broken, see bug #51747) built-in
994 facility for coloring visited links. The JavaScript approach is
995 (probably) slower and is not consistent across tabs (unless the tabs are
996 reloaded), but has the advantage of not leaking history data to web
997 pages (see http://wtikay.com/docs/details.html).
998 .It Cm cookie_policy
999 This field delineates the cookie policy.
1000 Possible values are: no3rdparty, reject 3rd party cookies.
1001 accept, accept all cookies.
1002 reject, reject all cookies.
1003 .It Cm include_config
1004 This must be a path to another configuration file.
1005 Configuration files are usually read from top to bottom, however, if
1006 this option is set,
1008 will begin reading the included file at this location and continue
1009 reading the rest of the configuation after the included file has
1010 finished being read.
1012 Any simple settings set before the include may
1013 be overridden by settings in the included file, and any simple
1014 settings set in the included file may be overridden later by settings
1015 after the include or at runtime using the
1016 .Cm :set
1017 command.
1018 However, database settings (for example,
1019 .Cm cookie_wl , js_wl , pl_wl ,
1021 .Cm keybinding )
1022 are only ever added to the database, and so the order of an included
1023 configuration file is not pertinent to these database settings.
1025 This feature is likely best used as the last item in
1026 .Pa ~/.xxxterm.conf .
1027 .It Cm cookie_wl
1028 This is a cookie whitelist item.
1029 Use multiple times to add multiple entries.
1030 Valid entries are for example *.moo.com and the equivalent .moo.com.
1031 A fully qualified host is also valid and is for example www.moo.com.
1032 .It Cm cookies_enabled
1033 Enable cookies.
1034 .It Cm ctrl_click_focus
1035 Give focus in newly created tab instead of opening it in the background.
1036 .It Cm default_script
1037 Path to the script used as the default value for the run_script
1038 command.
1039 .It Cm default_zoom_level
1040 Set the default browsing zoom level.
1041 .It Cm download_dir
1042 Locations where files are downloaded to.
1043 This directory must exist and
1045 validates that during startup.
1046 .It Cm download_mode
1047 Controls how downloads are handled.
1048 Possible values are:
1049 .Bd -literal -offset indent
1050 start - automatically start download.
1051 ask   - ask user for confirmation.
1052 add   - add to downloadmanager, but
1053         do not start.
1055 The default is "start".
1056 .It Cm download_notifications
1057 When enabled a message is shown when downloads are started and
1058 finished.  Default is 0.
1059 .It Cm enable_autoscroll
1060 When enabled clicking MB3 will spawn the autoscroll ball, scrolling can
1061 then proceed by dragging the mouse away from the ball.
1062 .It Cm enable_cookie_whitelist
1063 When enabled all cookies must be in the whitelist or they are rejected.
1064 Additionally whitelisted cookies also enable HTML5 local storage for the
1065 domain.
1066 .It Cm enable_favicon_entry
1067 When enabled (the default)
1069 displays the favicon of the web page at the URI entry. This setting
1070 affects both
1071 .Cm normal
1073 .Cm compact
1074 tabs.
1075 .It Cm enable_favicon_tabs
1076 When enabled (disabled by default)
1078 displays favicons at each tab. This setting only affects
1079 .Cm compact
1080 tabs.
1081 .It Cm enable_js_autorun
1082 Enables support for autorunning JavaScript after page loads.  When
1083 enabled,
1084 .Pa ~/.xxxterm/js/
1085 will be searched for
1086 .Pa default.js
1088 .Pa host.domain.js .
1090 .Pa host.domain.js
1091 does not exist,
1092 .Pa domain.js
1093 will be tried instead.  The content of the both default and
1094 host/domain files are read and executed on each page load.
1095 Default is 1.
1097 As an example, if you add the line
1098 .Pa alert("Hello, world");
1099 to your
1100 .Pa default.js ,
1101 a pop-up displaying "Hello, world" will be shown on every page reload.
1102 While not useful, any javascript can be run through this mechanism,
1103 making it useful for global or site-specific modifications.
1104 .It Cm enable_js_whitelist
1105 When enabled all domains must be in the js whitelist in order to run Java
1106 Script.
1107 NOTE: Make sure
1108 .Cm enable_scripts
1109 is set to 0.
1110 .It Cm enable_plugin_whitelist
1111 When enabled all domains must be in the plugin whitelist in order to run
1112 plugins.
1113 NOTE: Make sure
1114 .Cm enable_plugins
1115 is set to 0.
1116 .It Cm enable_plugins
1117 Enable external plugins such as Flash and Java.
1118 .It Cm enable_strict_transport
1119 Enable support for the Strict-Transport-Security HTTP-header.
1120 When enabled, sites that set this flag will only be visited via HTTPS.
1121 Default value is 1
1122 .It Cm enable_scripts
1123 Enable Java Script.
1124 .It Cm enable_socket
1125 When enabled the first instance of
1127 will create a socket in the
1128 .Pa ~/.xxxterm
1129 directory.
1130 Using the -n url option on subsequent
1132 invocations will cause the specified URL to be loaded in a new tab.
1133 Only a user with identical UID and GID can use this option.
1134 .It Cm enable_localstorage
1135 Enable html5 Local Storage.
1136 .It Cm enable_spell_checking
1137 Enables spell checking. Preferred languages can be set using
1138 .Cm spell_check_languages
1139 option.
1140 .It Cm encoding
1141 Set the default encoding.
1142 E.g.
1143 .Pa encoding = ISO-8859-1 .
1144 .It Cm external_editor
1145 Set which editor to use for external editing.
1146 the string <file> will be replaced by the current filename.
1147 E.g.
1148 .Pa external_editor = gvim -f <file>
1149 Note!
1150 .Cm xxxterm
1151 relies on the editor
1152 .Pa not forking
1153 into the background.
1154 .It Cm fancy_bar
1155 Enables a backward, forward, and stop button to the toolbar.
1156 Additionally if
1157 .Cm search_string
1158 is set it'll enable an entry box for searches.
1159 .It Cm guess_search
1160 When enabled
1162 will try to guess if the string you entered, in the URI entry widget or
1163 the command widget, is term you want to search for using search_string
1164 (see above).
1165 If the string does not contain a dot nor a slash, is not a
1166 path to a local file and does not resolves to an IP then it is assumed
1167 to be a search term.
1168 .It Cm gui_mode
1169 To simplify configuring
1171 allows you pick between two GUI modes:
1172 .Pa classic
1173 (the default) and
1174 .Pa minimal .
1175 In the
1176 .Pa classic
1177 mode the GUI looks similar to that of most mainstream browsers. While in
1178 .Pa minimal
1179 mode the GUI looks more vi-like. One can get a GUI between the two by
1180 tweaking the low-level GUI settings found under the advanced GUI setting
1181 section in the configuration file.
1182 .It Cm history_autosave
1183 When enabled
1185 will save all command and search history.
1186 Upon restarting
1188 the saved command and search history will be restored.
1189 .It Cm home
1190 Homepage in URL format.
1191 .It Cm http_proxy
1192 Proxy server in URL format.
1194 overrides
1195 .Cm http_proxy
1196 if it is specified as an environment variable.
1197 It must be noted that on older webkit versions one MUST use an IP address and
1198 not a FQDN.
1199 This works as expected with webkit 1.4.2.
1201 If one desires to use a socks proxy then an intermediary tool must be used.
1202 It has been reported that tsocks works with
1203 .Nm .
1204 .It Cm icon_size
1205 Permits icon sizes to be changed if
1206 .Cm fancy_bar
1207 is enabled.
1208 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
1209 .It Cm js_wl
1210 This is a Java Script whitelist item.
1212 .Cm cookie_wl
1213 for semantics and more details.
1214 .It Cm max_connections
1215 The maximum number of connections that
1217 can open at once.
1218 .It Cm max_host_connections
1219 The maximum number of connections that
1221 can open at once to a given host.
1222 .It Cm mime_type
1223 Sets an action for a specific or default MIME type.
1224 For example, to download and view a pdf using kpdf set
1225 .Pa mime_type = application/pdf,kpdf .
1226 To set a default value use *, for example,
1227 .Pa mime_type = video/*,mplayer .
1228 Note that the action is only passed the URL and not all applications are
1229 capable of dealing with a URL and therefore one might have to create a wrapper
1230 script to download the content first.  Alternatively one can add the
1231 .Pa @
1232 in front of the MIME type to indicate "download first".
1233 For example,
1234 .Pa mime_type = @application/pdf,xpdf .
1235 When
1236 .Pa @
1237 is use the file will be downloaded to the
1238 .Pa download_dir
1239 before the MIME handler is called.
1240 .It Cm oops_font
1241 Set the font used to display error messages.
1242 E.g.
1243 .Pa oops_font = monospace normal 9 .
1244 .It Cm pl_wl
1245 This is a plugin whitelist item.
1247 .Cm cookie_wl
1248 for semantics and more details.
1249 .It Cm read_only_cookies
1250 Mark cookies file read-only and discard all cookies once the session is
1251 terminated.
1252 .It Cm refresh_interval
1253 Refresh interval while in the download manager.
1254 The default is 10.
1255 .It Cm referer
1256 Control how 'Referer' is handled in http-requests.
1257 .Bd -literal -offset indent
1258 always      - always send referer
1259 never       - never send referer
1260 same-domain - only send referer if it's
1261               for the same public suffix - this means that
1262               it's ok for subdomains to refer to each other
1263 same-fqdn   - only send referer if it's FQDN match
1265 Any other value that is also a valid URL will use this
1266 custom value as referer. (E.g. you could set it to http://no-referer.com)
1267 The default value is "always"
1268 .It Cm resource_dir
1269 Directory that contains various
1271 resources such as icons.
1272 This is OS-specific and should be handled by the porter.
1273 .It Cm save_global_history
1274 If set the global history will be saved to
1275 .Pa ~/.xxxterm/history
1276 when quitting
1277 and restored at startup.
1278 See the
1279 .Sx KEY BINDINGS
1280 section above for how the global history is accessed.
1281 Global history is not saved to disk by default.
1282 .It Cm save_rejected_cookies
1283 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
1284 All cookies are saved and unlike a cookie jar they are never replaced.
1285 Make sure there is enough disk space to enable this feature.
1286 .It Cm search_string
1287 Default search engine string.
1288 See the
1289 .Pa xxxterm.conf
1290 file for details.
1291 .It Cm session_autosave
1292 Enable session auto-saving when changing state (e.g. adding or removing a tab).
1293 The session name is what is currently in use and is described in the
1294 .Cm session save
1296 .Cm session open
1297 commands.
1298 .It Cm session_timeout
1299 This value is the time that is added in seconds to a session cookie.
1300 .It Cm show_tabs
1301 Enable or disable showing tabs.
1302 .It Cm show_url
1303 Enable or disable showing the url and toolbar.
1304 .It Cm show_statusbar
1305 Enable or disable showing the status bar.
1306 .It Cm single_instance
1307 If set and
1308 .Cm enable_socket
1309 is enabled only one
1311 will be permitted to run.
1312 If there is a URL specified it will be opened in a new tab in the already
1313 running
1315 session.
1316 .It Cm spell_check_languages
1317 The languages to be used for spell checking, separated by commas. For example,
1318 en_US.
1319 .It Cm ssl_ca_file
1320 If set to a valid PEM file
1321 all server certificates will be validated against it.
1322 The URL bar will be colored green (or blue when saved ) when the certificate is
1323 trusted and yellow when untrusted.
1326 .Cm ssl_ca_file
1327 is not set then the URL bar will color all HTTPS connections red.
1329 WebKit only supports a single PEM file.
1330 Many OS' or distributions have many PEM files.
1331 One can simply concatenate all separate files into one large one.
1332 E.g.
1333 .Cm for i in `ls`; do cat $i >> cert.pem; done
1334 and use the resulting cert.pem file as the input to
1335 .Cm ssl_ca_file .
1336 It is advisable to periodically recreate the cert.pem file.
1337 .It Cm ssl_strict_certs
1338 If this value is set connections to untrusted sites will be aborted.
1339 This value is only used if
1340 .Cm ssl_ca_file
1341 is set.
1342 .It Cm statusbar_elems
1343 Define the components of the status bar. The possible components are:
1344 .Bd -literal -offset indent
1345 | - separator
1346 P - page progress percent
1347 B - buffer command
1348 Z - page zoom level
1350 The default is "BP".
1351 These components show nothing if there is nothing worth showing, like
1352 zoom amount 100%.
1353 .It Cm statusbar_font
1354 Set the status bar font.
1355 E.g.
1356 .Pa statusbar_font = monospace normal 9 .
1357 .It Cm tab_style
1358 Set the tab style to either
1359 .Cm normal
1360 - the default gtk notebook tabs, or
1361 .Cm compact
1362 for an alternative.
1363 You can switch the tab style with the
1364 .Pa tabnextstyle
1365 command.
1366 .It Cm tabbar_font
1367 Set the compact tab bar font.
1368 E.g.
1369 .Pa tabbar_font = monospace normal 9 .
1370 .It Cm url_regex
1371 This is the regular expression that is used to match what constitutes a valid
1372 URL when using
1373 .Pa guess_search .
1374 .It Cm user_agent
1375 Set to override the default
1377 user-agent string. May be specified several times for switching between
1378 user-agents.
1379 .It Cm userstyle_global
1380 When enabled new tabs will automatically be displayed in low contrast mode.
1381 .It Cm window_height
1382 Set the default height of the browser window.
1383 .It Cm window_width
1384 Set the default width of the browser window.
1385 .It Cm window_maximize
1386 Maximize the browser window at startup.
1387 .It Cm work_dir
1388 Set the work directory where all
1390 scratch files are stored.
1391 Default is
1392 .Cm ~/.xxxterm .
1393 .It Cm xterm_workaround
1394 When enabled
1396 will look additionally at CUT_BUFFER0 if PRIMARY clipboard is empty.
1397 Additionally when the PRIMARY clipboard is cleared it will copy CUT_BUFFER0
1398 into the PRIMARY clipboard.
1399 Default is 0.
1401 .Sh HISTORY
1403 was inspired by vimprobable2 and the bloat in other
1405 web browsers.
1406 .Sh AUTHORS
1407 .An -nosplit
1409 was written by
1410 .An Marco Peereboom Aq marco@peereboom.us ,
1411 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
1412 .An Edd Barrett Aq vext01@gmail.com ,
1413 .An Todd T. Fries Aq todd@fries.net ,
1414 .An Raphael Graf Aq r@undefined.ch ,
1416 .An Michal Mazurek Aq akfaew@jasminek.net .