| blob | 34e7f2b666fb65593332bed64f47f5090e45f2c6 |
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
103 .El
104 .Pp
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.
111 .Pp
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
116 and
117 .Cm PageDown
118 will scroll up and down the page.
119 .Pp
120 To follow a link,
121 either click on it or use the
122 .Cm f
123 key and have
124 .Nm
125 assign numbers to each link on the page;
126 entering that number on the keyboard will prompt
127 .Nm
128 to follow the link.
129 .Sh KEY BINDINGS
130 .Nm
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:
138 .Pp
139 .D1 keybinding = action,(!)keystroke(s)
140 .Pp
141 For example, "keybinding = tabnew,C-t" where
142 .Cm tabnew
143 is the action and
144 .Cm C-t
145 are
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".
152 The
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.
159 .Pp
160 Shift should be used sparingly since it gets in the way of non-USA keyboards.
161 See the accompanying configuration file for examples.
162 .Pp
163 The various bindings are documented below.
164 The relevant keybinding action is given afterwards, in parentheses.
165 .Ss Search Commands
166 These commands are used to search for text strings within a web page.
167 .Pp
168 .Bl -tag -width Ds -offset indent -compact
169 .It Cm /
170 Start a search
171 .Pq Cm search
172 .It Cm \&?
173 Start a backwards search
174 .Pq Cm searchb
175 .It Cm n
176 Next item matching search
177 .Pq Cm searchnext
178 .It Cm N
179 Previous item matching search
180 .Pq Cm searchprev
181 .El
182 .Ss Focus Commands
183 These commands are used to shift the focus of
184 .Nm
185 from one area to another.
186 .Pp
187 .Bl -tag -width Ds -offset indent -compact
188 .It Cm F6
189 Focus on address bar
190 .Pq Cm focusaddress
191 .It Cm F7
192 Focus on search entry
193 .Pq Cm focussearch
194 .El
195 .Ss Command Aliases
196 These commands allow the user to map specific actions to specific keys.
197 It can be useful when the
198 .Fl S
199 option is used.
200 .Pp
201 .Bl -tag -width Ds -offset indent -compact
202 .It Cm F1
203 Alias for ":help"
204 .It Cm F4
205 Alias for ":toplevel toggle"
206 .It Cm F9
207 Alias for ":open"
208 .Pq Cm promptopen
209 .It Cm F10
210 Alias for ":open current-uri"
211 .Pq Cm promptopencurrent
212 .It Cm F11
213 Alias for ":tabnew"
214 .Pq Cm prompttabnew
215 .It Cm F12
216 Alias for ":tabnew current-uri"
217 .Pq Cm prompttabnewcurrent
218 .El
219 .Ss Navigation Commands
220 These commands allow the user to navigate web pages and,
221 to some extent,
222 control the browser.
223 .Pp
224 .Bl -tag -width "Space, C-f, PageDownXXX" -offset indent -compact
225 .It Cm F5, C-r, C-l
226 Reload page
227 .Pq Cm reload
228 .It Cm Backspace, M-Left
229 Previous page
230 .Pq Cm goback
231 .It Cm S-BackSpace, M-Right
232 Forward page
233 .Pq Cm goforward
234 .It Cm j, Down
235 Next line on page
236 .Pq Cm scrolldown
237 .It Cm k, Up
238 Previous line on page
239 .Pq Cm scrollup
240 .It Cm G, End
241 Bottom of page
242 .Pq Cm scrollbottom
243 .It Cm gg, Home
244 Top of page
245 .Pq Cm scrolltop
246 .It Cm Space, C-f, PageDown
247 Page down
248 .Pq Cm scrollpagedown
249 .It Cm C-b, PageUp
250 Page up
251 .Pq Cm scrollpageup
252 .It Cm l, Right
253 Page right
254 .Pq Cm scrollright
255 .It Cm h, Left
256 Page left
257 .Pq Cm scrollleft
258 .It Cm $
259 Page far right
260 .Pq Cm scrollfarright
261 .It Cm 0
262 Page far left
263 .Pq Cm scrollfarleft
264 .It Cm M-f
265 Favorites
266 .Pq Cm fav
267 .It Cm M-j
268 Cookie jar
269 .Pq Cm cookiejar
270 .It Cm M-d
271 Download manager
272 .Pq Cm dl
273 .It Cm C-p
274 Print page
275 .Pq Cm print
276 .It Cm M-h
277 Global history
278 .Pq Cm history
279 .It Cm C-j
280 Toggle Java Script enabled for FQDN
281 .Pq Cm js
282 .It Cm C-s
283 Toggle source view
284 .Pq Cm togglesrc
285 .It Cm M-c
286 Toggle cookie enabled for FQDN
287 .Pq Cm cookie
288 .El
289 .Ss Tab Manipulation
290 .Nm
291 supports tabbed browsing.
292 That is, web pages may be opened in separate tabs,
293 allowing the user to quickly move from one page to another,
294 and back.
295 These commands then are used to create, destroy, and move between tabs.
296 .Pp
297 .Bl -tag -width "C-plus, C-equalXXX" -offset indent -compact
298 .It Cm C-MB1
299 Open new tab with the clicked link
300 .It Cm C-t
301 Create new tab with focus in URL entry
302 .Pq Cm tabnew
303 .It Cm C-w
304 Destroy current tab
305 .Pq Cm tabclose
306 .It Cm U
307 Undo close tab
308 .Pq Cm tabundoclose
309 .It Cm C-Left
310 Go to the previous tab
311 .Pq Cm tabprevious
312 .It Cm C-Right
313 Go to the next tab
314 .Pq Cm tabnext
315 .It Cm C-[1..9]
316 Jump to page
317 .Ar N
318 .Pq Cm tabnext [1..9]
319 .It Cm C-minus
320 Zoom out by 4%
321 .Pq Cm focusout
322 .It Cm C-plus, C-equal
323 Zoom in by 4%
324 .Pq Cm focusin
325 .It Cm C-0
326 Set zoom level to 100%
327 .Pq Cm focusreset
328 .El
329 .Ss Yanking and pasting
330 These commands copy and paste text to and from the clipboard.
331 .Pp
332 .Bl -tag -width Ds -offset indent -compact
333 .It Cm p
334 Paste the contents of the clipboard into the address bar
335 .Pq Cm pasteuricur
336 .It Cm P
337 Paste the contents of the clipboard into a new tab
338 .Pq Cm pasteurinew
339 .It Cm y
340 Yank the current URL into the clipboard
341 .Pq Cm yankuri
342 .El
343 .Ss Hyperlink Following
344 This allows the user to follow hyperlinks
345 without using a mouse.
346 Enter the corresponding number to follow the link.
347 Alternatively one can type the name of the link and when there are no more
348 possibilities
349 .Nm
350 will follow the link.
351 .Pp
352 .Bl -tag -width Ds -offset indent -compact
353 .It Cm f
354 Highlight all links and prefix them with a number.
355 .Pq Cm hinting
356 .El
357 .Ss Exiting
358 Commands to exit the browser.
359 .Pp
360 .Bl -tag -width Ds -offset indent -compact
361 .It Cm C-q
362 Quit
363 .Pq Cm quitall
364 .El
365 .Ss Low-Contrast Color Scheme
366 This command toggles the page's style between the default CSS and a
367 low-contrast color scheme with light grey text on a dark grey background.
368 .Pp
369 .Bl -tag -width Ds -offset indent -compact
370 .It Cm i
371 Toggle the current tab's style.
372 .Pq Cm userstyle
373 .El
374 .Sh COMMAND MODE
375 Command mode works in a similar fashion to the
376 .Xr vi 1
377 editor;
378 it is entered by typing a colon and exited by typing Esc.
379 The commands and their descriptions are listed below.
380 .Bl -tag -width Ds -offset indent
381 .It Cm about , version
382 Show the "About" page.
383 .It Cm buffers , ls , tabs
384 Displays the currently open tabs and lets the user switch tab by typing
385 the tab number or using the mouse.
386 .It Cm ca
387 Display CA certificates.
388 .It Cm cert , cert show
389 Download and display certificates of domain on tab.
390 .It Cm cert save
391 Save certificate into a local store.
392 The next time the site is visited it is compared against the store.
393 If the certificate matches,
394 the address bar will be blue;
395 if it doesn't the bar will be red.
396 .It Cm cookie
397 The
398 .Cm cookie
399 command is used to manipulate the cookie whitelist.
400 Used by itself it expands to
401 .Cm cookie show all .
402 .It Cm cookiejar
403 Show cookie jar contents.
404 .It Cm cookie save, cookie save fqdn
405 Save the current fully qualified domain name (FQDN)
406 to the persistent whitelist.
407 For example,
408 the www.peereboom.us domain would result in saving .www.peereboom.us.
409 .It Cm cookie save domain
410 Save the top level domain name to the persistent whitelist.
411 For example,
412 the www.peereboom.us domain would result in saving .peereboom.us.
413 .Pp
414 This action enables cookies if it is currently disabled for this entry.
415 .It Cm cookie show all
416 Show all persistent and session entries in the cookie whitelist.
417 .It Cm cookie show persistent
418 Show all persistent entries in the cookie whitelist.
419 .It Cm cookie show session
420 Show all session entries in the cookie whitelist.
421 .It Cm cookie toggle domain
422 Toggle cookie support for the current top level domain.
423 .It Cm cookie toggle, cookie toggle fqdn
424 Toggle cookie support for the current FQDN.
425 .It Cm dl
426 Show download manager.
427 .It Cm encoding <encoding>
428 If
429 .Cm <encoding>
430 is set the tab's encoding will be set to
431 .Cm <encoding>
432 and
433 .Nm
434 reloads the tab.
435 If
436 .Cm <encoding>
437 is not set
438 .Nm
439 will display the current tab encoding.
440 .It Cm fav
441 Show favorites.
442 .It Cm favadd
443 Add the current page to favorites.
444 .It Cm fullscreen , f
445 Toggle hiding tabs and url entry toolbar.
446 .It Cm h , hist , history
447 Show global history.
448 .It Cm help
449 Show help page.
450 .It Cm home
451 Go to home URL.
452 .It Cm js
453 The
454 .Cm js
455 command is used to manipulate the Java Script whitelist.
456 Used by itself it expands to
457 .Cm js show all .
458 .It Cm js save, save fqdn
459 Saves the FQDN to the persistent whitelist.
460 For example,
461 the www.peereboom.us domain would result in saving .www.peereboom.us.
462 .It Cm js save domain
463 Saves the top level domain name to the persistent whitelist.
464 For example,
465 the www.peereboom.us domain would result in saving .peereboom.us.
466 .Pp
467 This action enables Java Script if it is currently disabled for this entry.
468 .It Cm js show all
469 Shows all persistent and session entries in the JS whitelist.
470 .It Cm js show persistent
471 Shows all persistent entries in the JS whitelist.
472 .It Cm js show session
473 Shows all session entries in the JS whitelist.
474 .It Cm js toggle, js toggle fqdn
475 Toggle Java Script execution for the current FQDN.
476 .It Cm js toggle domain
477 Toggle Java Script execution for the current top level domain.
478 .It Cm open , op , o URL
479 Open URL.
480 .It Cm print
481 Print page.
482 .It Cm qa , qall , quitall
483 Quit
484 .Nm .
485 .It Cm quit , q
486 Close current tab and quit
487 .Nm
488 if it is the last tab.
489 .It Cm restart
490 Restart
491 .Nm
492 and reload all current tabs.
493 .It Cm run_script [path_to_script]
494 Runs the script path_to_script with the current uri as the argument.
495 If path_to_script is not provided, the value of default_script is used
496 instead.
497 .It Cm session , Cm session show
498 Display the current session name.
499 By default the session name is main_session.
500 To create a new session use the
501 .Cm session save
502 command.
503 A session is defined as the lifetime of the browser application.
504 .It Cm session delete <session_name>
505 Delete session session_name from persistent storage.
506 If session_name is the current session then the session will revert to
507 main_session.
508 .It Cm session open <session_name>
509 Open session_name and close all currently open tabs.
510 Going forward this session is named session_name.
511 .It Cm session save <session_name>
512 Save current tabs to session_name session.
513 This will close the current session and going forward this session is named
514 session_name.
515 .It Cm set
516 The set command is used to inspect, clear or change runtime options.
517 There are 3 methods to use
518 .Cm :set .
519 When used by itself as
520 .Cm :set
521 the command displays all options as currently set.
522 .Pp
523 To set a value use
524 .Cm :set option=value .
525 For example,
526 .Cm :set http_proxy=http://127.0.0.1:8080 .
527 .Pp
528 To clear a value use
529 .Cm :set option= .
530 For example,
531 .Cm :set http_proxy= .
532 .Pp
533 Note, not all options can be set at runtime.
534 .It Cm stats
535 Show blocked cookie statistics.
536 These statistics vary based on settings and are not persistent.
537 .It Cm statustoggle , statust
538 Toggle status bar.
539 .It Cm tabclose , tabc
540 Close current tab.
541 .It Cm tabhide
542 Hide tabs.
543 .It Cm tabnew , tabedit , tabe URL
544 Create new tab and optionally open provided URL.
545 .It Cm tabnext , tabn
546 Go to the next tab.
547 .It Cm tabprevious , tabp
548 Go to the previous tab.
549 .It Cm tabshow
550 Show tabs.
551 .It Cm toplevel , toplevel toggle
552 Toggle the top level domain name cookie and JS session whitelist.
553 This is to enable/disable short lived full site functionality without
554 permanently adding the top level domain to the persistent whitelist.
555 .It Cm urlhide , urlh
556 Hide url entry and tool bar.
557 .It Cm urlshow , urls
558 Show url entry and tool bar.
559 .It Cm w
560 Save open tabs to current session.
561 The tabs will be restored next time the session is opened.
562 See the session command for additional details.
563 .It Cm wq
564 Save open tabs and quit.
565 The tabs will be restored next time
566 .Nm
567 the session is opened.
568 See the session command for additional details.
569 .El
570 .Sh BUFFER COMMANDS
571 In addition to shortcuts and commands
572 .Nm
573 provides buffer commands. Buffer commands are short, multi character
574 vi-like commands, often requiring an argument. Partial buffer commands
575 are
576 displayed in the buffer command statusbar element (see
577 .Cm statusbar_elems ) .
578 Pressing Esc or switching to another tab cancels a partially entered
579 buffer command. In the following list
580 .Cm arg
581 denotes the argument a buffer command accepts. Buffer commands are
582 defined as extended regular experssions.
583 Note that if a character is used as a shortcut it will not be interpreted
584 as the beginning of a buffer command. This is the case with
585 .Cm 0 .
586 .Pp
587 .Bl -tag -width "['][a-zA-Z0-9]XXX" -offset indent -compact
588 .It Cm gg
589 go to the top of the page
590 .It Cm gG
591 go to the bottom of the page
592 .It Cm [0-9]+%
593 go to the
594 .Cm arg
595 percent of the page
596 .It Cm [0-9]*gU
597 go
598 .Cm arg
599 levels up. If
600 .Cm arg
601 is missing, 1 is assumed. Going a
602 level up means going to a uri obtained from the current one by removing
603 the last slash ('/') character and everything that follows it
604 .It Cm gh
605 open the home page in the current tab
606 .It Cm m[a-zA-Z0-9]
607 set a mark denoted by
608 .Cm arg
609 at the current page position. These marks behave like those in vi or
610 less.
611 .It Cm ['][a-zA-Z0-9]
612 go to the position where mark
613 .Cm arg
614 was set
615 .It Cm M[a-zA-Z0-9]
616 set the current uri as quickmark
617 .Cm arg
618 .It Cm go[a-zA-Z0-9]
619 open the uri marked as quickmark
620 .Cm arg
621 in the current tab
622 .It Cm gn[a-zA-Z0-9]
623 open the uri marked as quickmark
624 .Cm arg
625 in a new tab
626 .It Cm [0-9]+t
627 activate tab number
628 .Cm arg
629 .It Cm ZZ
630 quit
631 .Nm
632 .It Cm ZR
633 restart
634 .Nm
635 .It Cm zi
636 zoom in by 4%
637 .It Cm zo
638 zoom out by 4%
639 .It Cm z0
640 set zoom level to 100%
641 .It Cm [0-9]+Z
642 set zoom level to
643 .Cm arg
644 %
645 .El
646 .Sh QUICKMARKS
647 Quickmarks are like bookmarks, except they are refered to by a single
648 character (a letter or a digit), instead of a longer name. See the
649 .Cm M[a-zA-Z0-9] ,
650 .Cm go[a-zA-Z0-9]
651 and
652 .Cm gn[a-zA-Z0-9]
653 buffer commands for usage. Quickmarks are stored in
654 .Pa ~/.xxxterm/quickmarks
655 and are saved automatically after each
656 .Cm M[a-zA-Z0-9]
657 buffer command.
658 .Sh ABOUT SCREENS
659 The about screens are internally generated web pages by
660 .Nm
661 for user interaction.
662 These are entered in the address bar and the format is
663 .Cm about:screen
664 where screen is the desired screen to display.
665 For example about:favorites.
666 Any about screen can be used as the home page as specified by
667 .Cm home
668 in the configuration file.
669 .Pp
670 .Bl -tag -width "downloadsXXX" -offset indent -compact
671 .It Cm about
672 show the about screen
673 .It Cm blank
674 show a blank screen
675 .It Cm cookiewl
676 show the cookie whitelist screen
677 .It Cm cookiejar
678 show the cookiejar screen
679 .It Cm downloads
680 show the downloads screen
681 .It Cm favorites
682 show the favorites screen
683 .It Cm help
684 show the help web page
685 .It Cm history
686 show the history screen
687 .It Cm jswl
688 show the Java Script whitelist screen
689 .It Cm set
690 show the settings screen
691 .It Cm stats
692 show the statistics screen
693 .El
694 .Sh WHITELISTS
695 This section describes advanced usage settings.
696 Most users should use
697 .Cm browser_mode
698 instead to setup
699 .Nm
700 and skip over this section.
701 .Pp
702 .Nm
703 has a number of whitelists to control blocking cookies and Java Script
704 execution for FQDNs or domains.
705 When properly enabled these whitelists require either the FQDN or top level
706 domain to exist in the whitelists in order to allow cookies to be stored or
707 Java Script to execute.
708 Both Java Script and cookies have two whitelists associated with them.
709 The whitelists are called session and persistent.
710 Items in the session whitelists are only allowed for the lifetime of the
711 .Nm
712 instance.
713 Items in the persistent whitelists are stored on disk and are restored
714 upon restarting.
715 .Pp
716 Setting up the whitelists is a little tricky due to intricacies of WebKit.
717 In fact the semantics are different for cookies and Java Script.
718 .Pp
719 Cookie whitelist requires the following configuration to be set:
720 .Pp
721 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
722 .It Cm cookies_enabled
723 This is a WebKit setting and must be set to
724 .Pa 1
725 (ENABLED)
726 in order to be able to use a
727 cookie whitelist.
728 .It Cm enable_cookie_whitelist
729 This needs to be set to
730 .Pa 1
731 to enable the cookie whitelist functionality.
732 .It Cm cookie_wl
733 These entries in the configuration file are the actual domains names in the
734 cookie whitelist.
735 .El
736 .Pp
737 Java Script whitelist requires the following configuration to be set:
738 .Pp
739 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
740 .It Cm enable_scripts
741 This is a WebKit setting and must be set to
742 .Pa 0
743 (DISABLED)
744 in order to be able to use a
745 Java Script whitelist.
746 .It Cm enable_js_whitelist
747 This needs to be set to
748 .Pa 1
749 to enable the Java Script whitelist functionality.
750 .It Cm js_wl
751 These entries in the configuration file are the actual domains names in the
752 Java Script whitelist.
753 .El
754 .Pp
755 See the
756 .Pa FILES
757 section for additional configuration file entries and details
758 that alter runtime behavior.
759 .Sh FILES
760 .Bl -tag -width "/etc/xxxterm.confXXX" -compact
761 .It Pa ~/.xxxterm.conf
762 .Nm
763 user specific settings.
764 .It Pa ~/.xxxterm
765 .Nm
766 scratch directory.
767 .El
768 .Pp
769 .Nm
770 tries to open the user specific file,
771 .Pa ~/.xxxterm.conf .
772 If that file is unavailable,
773 it then uses built-in defaults.
774 .Pp
775 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
776 For example:
777 .Pp
778 .Dl http_proxy = http://127.0.0.1:8080
779 .Pp
780 Enabling or disabling an option is done by using 1 or 0 respectively.
781 .Pp
782 The file supports the following keywords:
783 .Pp
784 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
785 .It Cm alias
786 Defines an alias for a given URL, so that the URL is loaded when the alias is
787 entered in the address bar.
788 If the aliased URL includes a %s format specifier, then any argument given after
789 the alias on the address bar is substituted.
790 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
791 then the URL http://www.google.com/search?q=foo is loaded when navigating to
792 "g foo".
793 .It Cm allow_volatile_cookies
794 If set cookies are stored in the session cache but will be discarded once
795 .Nm
796 exits.
797 Unfortunately enabling this does allow for some limited tracking on the web.
798 .It Cm append_next
799 When set a new tab is appended after the current tab instead of being appended
800 as the last tab.
801 .It Cm browser_mode
802 The
803 .Nm
804 browser has 3 default operating modes:
805 .Pa normal
806 (the default),
807 .Pa whitelist
808 and
809 .Pa kiosk .
810 In the
811 .Pa normal
812 mode the browser allows all cookies and Java Script as any other browser
813 would.
814 This means that all cookies are saved to persistent storage and that all
815 Java Script runs.
816 .Pp
817 On the other hand, using the
818 .Pa whitelist
819 mode enables whitelists.
820 This requires the user to add all the required
821 .Pa cookie_wl
822 and
823 .Pa js_wl
824 items.
825 If a domain does not appear in the whitelists
826 .Nm
827 disallows cookies and Java Script execution.
828 .Pp
829 In
830 .Pa kiosk
831 mode the browse works just like
832 .Pa normal
833 mode however the toolbar only has the backward, forward and home button.
834 .Pp
835 This setting must be the first entry in
836 .Pa ~/.xxxterm.conf
837 because it sets advanced settings that can be overridden later in the file.
838 See the default config file for more details.
839 .It Cm cmd_font
840 Set the command prompt font.
841 E.g.
842 .Pa cmd_font = monospace normal 9 .
843 .It Cm cookie_policy
844 This field delineates the cookie policy.
845 Possible values are: no3rdparty, reject 3rd party cookies.
846 accept, accept all cookies.
847 reject, reject all cookies.
848 .It Cm cookie_wl
849 This is a cookie whitelist item.
850 Use multiple times to add multiple entries.
851 Valid entries are for example *.moo.com and the equivalent .moo.com.
852 A fully qualified host is also valid and is for example www.moo.com.
853 .It Cm cookies_enabled
854 Enable cookies.
855 .It Cm ctrl_click_focus
856 Give focus in newly created tab instead of opening it in the background.
857 .It Cm default_script
858 Path to the script used as the default value for the run_script
859 command.
860 .It Cm default_zoom_level
861 Set the default browsing zoom level.
862 .It Cm download_dir
863 Locations where files are downloaded to.
864 This directory must exist and
865 .Nm
866 validates that during startup.
867 .It Cm enable_cookie_whitelist
868 When enabled all cookies must be in the whitelist or they are rejected.
869 Additionally whitelisted cookies also enable HTML5 local storage for the
870 domain.
871 .It Cm enable_js_whitelist
872 When enabled all domains must be in the js whitelist in order to run Java
873 Script.
874 NOTE: Make sure
875 .Cm enable_scripts
876 is set to 0.
877 .It Cm enable_plugins
878 Enable plugins.
879 .It Cm enable_scripts
880 Enable scripts.
881 .It Cm enable_socket
882 When enabled the first instance of
883 .Nm
884 will create a socket in the
885 .Pa ~/.xxxterm
886 directory.
887 Using the -n url option on subsequent
888 .Nm
889 invocations will cause the specified URL to be loaded in a new tab.
890 Only a user with identical UID and GID can use this option.
891 .It Cm enable_localstorage
892 Enable html5 Local Storage.
893 .It Cm enable_spell_checking
894 Enables spell checking. Preferred languages can be set using
895 .Cm spell_check_languages
896 option.
897 .It Cm encoding
898 Set the default encoding.
899 E.g.
900 .Pa encoding = ISO-8859-1 .
901 .It Cm fancy_bar
902 Enables a backward, forward, and stop button to the toolbar.
903 Additionally if
904 .Cm search_string
905 is set it'll enable an entry box for searches.
906 .It Cm guess_search
907 When enabled
908 .Nm
909 will try to guess if the string you entered, in the URI entry widget or
910 the command widget, is term you want to search for using search_string
911 (see above).
912 If the string does not contain a dot nor a slash, is not a
913 path to a local file and does not resolves to an IP then it is assumed
914 to be a search term.
915 .It Cm history_autosave
916 When enabled
917 .Nm
918 will save all command and search history.
919 Upon restarting
920 .Nm
921 the saved command and search history will be restored.
922 .It Cm home
923 Homepage in URL format.
924 .It Cm http_proxy
925 Proxy server in URL format.
926 .Nm
927 overrides
928 .Cm http_proxy
929 if it is specified as an environment variable.
930 It must be noted that on older webkit versions one MUST use an IP address and
931 not a FQDN.
932 This works as expected with webkit 1.4.2.
933 .Pp
934 If one desires to use a socks proxy then an intermediary tool must be used.
935 It has been reported that tsocks works with
936 .Nm .
937 .It Cm icon_size
938 Permits icon sizes to be changed if
939 .Cm fancy_bar
940 is enabled.
941 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
942 .It Cm js_wl
943 This is a Java Script whitelist item.
944 See
945 .Cm cookie_wl
946 for semantics and more details.
947 .It Cm max_connections
948 The maximum number of connections that
949 .Nm
950 can open at once.
951 .It Cm max_host_connections
952 The maximum number of connections that
953 .Nm
954 can open at once to a given host.
955 .It Cm mime_type
956 Sets an action for a specific or default MIME type.
957 For example, to download and view a pdf using kpdf set
958 .Pa mime_type = application/pdf,kpdf .
959 To set a default value use *, for example,
960 .Pa mime_type = video/*,mplayer .
961 Note that the action is only passed the URL and not all applications are
962 capable of dealing with a URL and therefore one might have to create a wrapper
963 script to download the content first. Alternatively one can add the
964 .Pa @
965 in front of the MIME type to indicate "download first".
966 For example,
967 .Pa mime_type = @application/pdf,xpdf .
968 When
969 .Pa @
970 is use the file will be downloaded to the
971 .Pa download_dir
972 before the MIME handler is called.
973 .It Cm oops_font
974 Set the font used to display error messages.
975 E.g.
976 .Pa oops_font = monospace normal 9 .
977 .It Cm read_only_cookies
978 Mark cookies file read-only and discard all cookies once the session is
979 terminated.
980 .It Cm refresh_interval
981 Refresh interval while in the download manager.
982 The default is 10.
983 .It Cm resource_dir
984 Directory that contains various
985 .Nm
986 resources such as icons.
987 This is OS-specific and should be handled by the porter.
988 .It Cm save_global_history
989 If set the global history will be saved to
990 .Pa ~/.xxxterm/history
991 when quitting
992 and restored at startup.
993 See the
994 .Sx KEY BINDINGS
995 section above for how the global history is accessed.
996 Global history is not saved to disk by default.
997 .It Cm save_rejected_cookies
998 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
999 All cookies are saved and unlike a cookie jar they are never replaced.
1000 Make sure there is enough disk space to enable this feature.
1001 .It Cm search_string
1002 Default search engine string.
1003 See the
1004 .Pa xxxterm.conf
1005 file for details.
1006 .It Cm session_autosave
1007 Enable session auto-saving when changing state (e.g. adding or removing a tab).
1008 The session name is what is currently in use and is described in the
1009 .Cm session save
1010 and
1011 .Cm session open
1012 commands.
1013 .It Cm session_timeout
1014 This value is the time that is added in seconds to a session cookie.
1015 .It Cm show_tabs
1016 Enable or disable showing tabs.
1017 .It Cm show_url
1018 Enable or disable showing the url and toolbar.
1019 .It Cm show_statusbar
1020 Enable or disable showing the status bar.
1021 .It Cm single_instance
1022 If set only one
1023 .Nm
1024 will be permitted to run.
1025 If there is a URL specified it will be opened in a new tab in the already
1026 running
1027 .Nm
1028 session.
1029 .It Cm spell_check_languages
1030 The languages to be used for spell checking, separated by commas. For example,
1031 en_US.
1032 .It Cm ssl_ca_file
1033 If set to a valid PEM file
1034 all server certificates will be validated against it.
1035 The URL bar will be colored green (or blue when saved ) when the certificate is
1036 trusted and yellow when untrusted.
1037 .Pp
1038 If
1039 .Cm ssl_ca_file
1040 is not set then the URL bar will color all HTTPS connections red.
1041 .Pp
1042 WebKit only supports a single PEM file.
1043 Many OS' or distributions have many PEM files.
1044 One can simply concatenate all separate files into one large one.
1045 E.g.
1046 .Cm for i in `ls`; do cat $i >> cert.pem; done
1047 and use the resulting cert.pem file as the input to
1048 .Cm ssl_ca_file .
1049 It is advisable to periodically recreate the cert.pem file.
1050 .It Cm ssl_strict_certs
1051 If this value is set connections to untrusted sites will be aborted.
1052 This value is only used if
1053 .Cm ssl_ca_file
1054 is set.
1055 .It Cm statusbar_elems
1056 Define the components of the status bar. The possible components are:
1057 .Bd -literal -offset indent
1058 | - separator
1059 P - page progress percent
1060 B - buffer command
1061 Z - page zoom level
1062 .Ed
1063 The default is "BP".
1064 These components show nothing if there is nothing worth showing, like
1065 zoom amount 100%.
1066 .It Cm statusbar_font
1067 Set the status bar font.
1068 E.g.
1069 .Pa statusbar_font = monospace normal 9 .
1070 .It Cm tab_style
1071 Set the tab style to either
1072 .Cm normal
1073 - the default gtk notebook tabs, or
1074 .Cm compact
1075 for an alternative.
1076 You can switch the tab style with the
1077 .Pa tabnextstyle
1078 command.
1079 .It Cm tabbar_font
1080 Set the compact tab bar font.
1081 E.g.
1082 .Pa tabbar_font = monospace normal 9 .
1083 .It Cm url_regex
1084 This is the regular expression that is used to match what constitutes a valid
1085 URL when using
1086 .Pa guess_search .
1087 .It Cm user_agent
1088 Set to override the default
1089 .Nm
1090 user-agent string.
1091 .It Cm window_height
1092 Set the default height of the browser window.
1093 .It Cm window_width
1094 Set the default width of the browser window.
1095 .It Cm work_dir
1096 Set the work directory where all
1097 .Nm
1098 scratch files are stored.
1099 Default is
1100 .Cm ~/.xxxterm .
1101 .It Cm xterm_workaround
1102 When enabled
1103 .Nm
1104 will look additionally at CUT_BUFFER0 if PRIMARY clipboard is empty.
1105 Additionally when the PRIMARY clipboard is cleared it will copy CUT_BUFFER0
1106 into the PRIMARY clipboard.
1107 Default is 0.
1108 .El
1109 .Sh HISTORY
1110 .Nm
1111 was inspired by vimprobable2 and the bloat in other
1112 .Ux
1113 web browsers.
1114 .Sh AUTHORS
1115 .An -nosplit
1116 .Nm
1117 was written by
1118 .An Marco Peereboom Aq marco@peereboom.us ,
1119 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
1120 .An Edd Barrett Aq vext01@gmail.com ,
1121 .An Todd T. Fries Aq todd@fries.net ,
1122 .An Raphael Graf Aq r@undefined.ch ,
1123 and
1124 .An Michal Mazurek Aq akfaew@jasminek.net .
1125 .Sh BUGS
1126 When
1127 .Cm save_global_history
1128 is enabled
1129 .Nm
1130 is supposed to, in addition to restoring the global history, color the
1131 visited links accordingly; however due to bug #51747 in WebKit this does
1132 not happen.