Catch OSX Makefile up with linux.
[xombrero.git] / xombrero.1
blobb9b25daaeac1426242e20ba7cc78d05fec12b1fe
1 .\" Copyright (c) 2010, 2011, 2012 Marco Peereboom <marco@peereboom.us>
2 .\" Copyright (c) 2011 Jason McIntyre <jmc@openbsd.org>
3 .\" Copyright (c) 2012 Josh Rickmar <jrick@devio.us>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd $Mdocdate: August 23 2012 $
18 .Dt XOMBRERO 1
19 .Os
20 .Sh NAME
21 .Nm xombrero
22 .Nd lightweight web browser
23 .Sh SYNOPSIS
24 .Nm xombrero
25 .Bk -words
26 .Op Fl nSTtV
27 .Op Fl f Ar file
28 .Op Fl s Ar session_name
29 .Op Ar url ...
30 .Ek
31 .Sh DESCRIPTION
32 .Nm
33 is a minimalistic web browser that tries to stay out of the way so that
34 valuable screen real estate can be used for much more important stuff.
35 It has sane defaults and does not require one to learn a language to do any
36 configuration.
37 It was written by hackers for hackers
38 and it strives to be small, compact, and fast.
39 .Pp
40 .Nm
41 is very simple in its use.
42 Most actions are initiated via key or mouse bindings.
43 Key bindings are based on those of the
44 .Xr vi 1
45 text editor,
46 giving web browsing a similar feel to navigating a text document.
47 The
48 .Sx KEY BINDINGS
49 section below documents the various defaults and possible customizations.
50 .Pp
51 The options are as follows:
52 .Bl -tag -width Ds
53 .It Fl f Ar file
54 Specify an alternative configuration file.
55 .It Fl n
56 Open a new tab in a running
57 .Nm
58 for each specified URL.
59 This option requires
60 .Cm enable_socket
61 to be enabled.
62 .It Fl e Ar command
63 Execute arbitrary command (see the
64 .Sx COMMAND MODE
65 section below) in a running
66 .Nm
67 instance. This option requires
68 .Cm enable_socket
69 to be enabled. Example run: xombrero -e "tabnew openbsd.org"; xombrero -e
70 tabclose; xombrero -e wq.
71 .It Fl S
72 Disable the toolbar.
73 .It Fl s Ar session_name
74 Open session that was saved with ":session save" command.
75 .It Fl T
76 Disable visualization of tabs.
77 .It Fl t
78 Disable tabs.
79 Pages that would open in tabs open in new windows instead.
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.
148 Actions may be any xombrero command that can be run from the command
149 prompt.
150 There is one additional action,
151 .Cm unbind ,
152 which will unbind any previous actions to that keybinding.
154 If the action begins with a colon, the action will be entered into the
155 command prompt instead of being executed.
156 For example, "keybinding = :session open ,M1-s" will open the command
157 prompt with ":open session " entered when using the M1-s keybinding.
159 Keybindings which open the command prompt may also include the string
160 <uri>, which will be replaced by the current tab's URI.
161 For example, "keybinding = :open <uri>,F10" will open the command
162 prompt with <uri> replaced with the current URI.
164 GTK has some default keybindings for manipulating text inside input
165 fields, such as the URI or search entry widget, for example
166 .Cm C-w
167 deletes a word. To override these defaults prefix your key with an
168 exclamation mark (!), like this: "keybinding = tabclose,!C-w".
170 .Cm clearall
171 key word is special and is meant to reset the key binding list to the GTK+
172 and WebKit defaults.
173 This keyword should be the first
174 .Cm keybinding
175 entry in the configuration file.
177 Shift should be used sparingly since it gets in the way of non-USA keyboards.
178 See the accompanying configuration file for examples.
180 The various bindings are documented below.
181 The relevant keybinding action is given afterwards, in parentheses.
182 .Ss Command mode
183 These commands are used to focus or unfocus input on the default input of a web
184 page.
186 .Bl -tag -width Ds -offset indent -compact
187 .It Cm ESC
188 Go to command mode; unfocus current entry on web page.
189 .Pq Cm command_mode
190 .It Cm i
191 Go to insert mode; focus on default entry on web page.
192 .Pq Cm insert_mode
194 .Ss Search Commands
195 These commands are used to search for text strings within a web page.
197 .Bl -tag -width Ds -offset indent -compact
198 .It Cm /
199 Start a search
200 .Pq Cm search
201 .It Cm \&?
202 Start a backwards search
203 .Pq Cm searchb
204 .It Cm n
205 Next item matching search
206 .Pq Cm searchnext
207 .It Cm N
208 Previous item matching search
209 .Pq Cm searchprev
211 .Ss Focus Commands
212 These commands are used to shift the focus of
214 from one area to another.
216 .Bl -tag -width Ds -offset indent -compact
217 .It Cm F6
218 Focus on address bar
219 .Pq Cm focusaddress
220 .It Cm F7
221 Focus on search entry
222 .Pq Cm focussearch
224 .Ss Command Aliases
225 These commands allow the user to map specific actions to specific keys.
227 .Bl -tag -width Ds -offset indent -compact
228 .It Cm F1
229 Alias for "help"
230 .It Cm F2
231 Alias for "proxy toggle"
232 .It Cm F4
233 Alias for "toplevel toggle"
235 .Ss Prompt Aliases
236 These commands allow the user to open a prompt.
237 These can be useful when the
238 .Fl S
239 option is used.
241 .Bl -tag -width Ds -offset indent -compact
242 .It Cm F9
243 Alias for ":open "
244 .It Cm F10
245 Alias for ":open <uri>"
246 .It Cm F11
247 Alias for ":tabnew "
248 .It Cm F12
249 Alias for ":tabnew <uri>"
251 .Ss Navigation Commands
252 These commands allow the user to navigate web pages and,
253 to some extent,
254 control the browser.
256 .Bl -tag -width "Space, C-f, PageDownXXX" -offset indent -compact
257 .It Cm F5, C-r, C-l
258 Reload page
259 .Pq Cm reload
260 .It Cm BackSpace, M-Left
261 Previous page
262 .Pq Cm goback
263 .It Cm S-BackSpace, M-Right
264 Forward page
265 .Pq Cm goforward
266 .It Cm j, Down
267 Next line on page
268 .Pq Cm scrolldown
269 .It Cm k, Up
270 Previous line on page
271 .Pq Cm scrollup
272 .It Cm G, End
273 Bottom of page
274 .Pq Cm scrollbottom
275 .It Cm gg, Home
276 Top of page
277 .Pq Cm scrolltop
278 .It Cm Space, C-f, PageDown
279 Page down
280 .Pq Cm scrollpagedown
281 .It Cm C-b, PageUp
282 Page up
283 .Pq Cm scrollpageup
284 .It Cm l, Right
285 Page right
286 .Pq Cm scrollright
287 .It Cm h, Left
288 Page left
289 .Pq Cm scrollleft
290 .It Cm $
291 Page far right
292 .Pq Cm scrollfarright
293 .It Cm 0
294 Page far left
295 .Pq Cm scrollfarleft
296 .It Cm M-f
297 Favorites
298 .Pq Cm fav
299 .It Cm M-j
300 Cookie jar
301 .Pq Cm cookiejar
302 .It Cm M-d
303 Download manager
304 .Pq Cm dl
305 .It Cm C-p
306 Print page
307 .Pq Cm print
308 .It Cm M-h
309 Global history
310 .Pq Cm history
311 .It Cm C-j
312 Toggle JavaScript enabled for FQDN
313 .Pq Cm js
314 .It Cm C-s
315 Toggle source view
316 .Pq Cm togglesrc
317 .It Cm M-c
318 Toggle cookie enabled for FQDN
319 .Pq Cm cookie
320 .It Cm M-p
321 Toggle plugins enabled for FQDN
322 .Pq Cm plugin
324 .Ss Tab Manipulation
326 supports tabbed browsing.
327 That is, web pages may be opened in separate tabs,
328 allowing the user to quickly move from one page to another,
329 and back.
330 These commands then are used to create, destroy, and move between tabs.
332 .Bl -tag -width "C-plus, C-equalXXX" -offset indent -compact
333 .It Cm C-MB1
334 Open new tab with the clicked link
335 .It Cm C-t
336 Create new tab with focus in URL entry
337 .Pq Cm tabnew
338 .It Cm C-T
339 Create new tab with focus in URL entry as the last tab in the browser
340 .Pq Cm 999tabnew
341 .It Cm C-w
342 Destroy current tab
343 .Pq Cm tabclose
344 .It Cm U
345 Undo close tab
346 .Pq Cm tabundoclose
347 .It Cm C-Left, C-PageUp
348 Go to the previous tab
349 .Pq Cm tabprevious
350 .It Cm C-Right, C-PageDown
351 Go to the next tab
352 .Pq Cm tabnext
353 .It Cm C-[1..9]
354 Jump to page
355 .Ar N
356 .Pq Cm tabnext [1..9]
357 .It Cm C-<
358 Jump to first page
359 .Pq Cm tabfirst
360 .It Cm C->
361 Jump to last page
362 .Pq Cm tablast
363 .It Cm C-minus
364 Zoom out by 4%
365 .Pq Cm focusout
366 .It Cm C-plus, C-equal
367 Zoom in by 4%
368 .Pq Cm focusin
369 .It Cm C-0
370 Set zoom level to 100%
371 .Pq Cm focusreset
373 .Ss Yanking and pasting
374 These commands copy and paste text to and from the clipboard.
376 .Bl -tag -width Ds -offset indent -compact
377 .It Cm p
378 Paste the contents of the clipboard into the address bar
379 .Pq Cm pasteuricur
380 .It Cm P
381 Paste the contents of the clipboard into a new tab
382 .Pq Cm pasteurinew
383 .It Cm y
384 Yank the current URL into the clipboard
385 .Pq Cm yankuri
387 .Ss Hyperlink Following
388 This allows the user to follow hyperlinks
389 without using a mouse.
390 Enter the corresponding number to follow the link.
391 Alternatively one can type the name of the link and when there are no more
392 possibilities
394 will follow the link.
396 .Bl -tag -width Ds -offset indent -compact
397 .It Cm f, '.'
398 Highlight all links and prefix them with a number.
399 .Pq Cm hinting
400 .It Cm F, ','
401 Highlight all links and prefix them with a number but open in a new tab.
402 .Pq Cm hinting_newtab
404 .Ss Exiting
405 Commands to exit the browser.
407 .Bl -tag -width Ds -offset indent -compact
408 .It Cm C-q
409 Quit
410 .Pq Cm quitall
412 .Ss Low-Contrast Color Scheme
413 These commands toggle the page style between the default CSS and a
414 low-contrast color scheme with light grey text on a dark grey background.
415 If the
416 .Cm userstyle
417 setting is changed, that stylesheet will be used instead of the
418 low-contrast color scheme.
420 .Bl -tag -width Ds -offset indent -compact
421 .It Cm s
422 Toggle the current tab's style.
423 .Pq Cm userstyle
424 .It Cm S
425 Toggle the global page style mode.
426 Will also affect new tabs.
427 .Pq Cm userstyle_global
429 .Ss Insert-mode commands
430 The following commands are only available when editing an input-field
432 .Bl -tag -width Ds -offset indent -compact
433 .It Cm C-i
434 Edit the contents of the currently active input-element in an external editor.
435 .Pq Cm editelement
437 .Sh COMMAND MODE
438 Command mode works in a similar fashion to the
439 .Xr vi 1
440 editor;
441 it is entered by typing a colon and exited by pressing Esc.
442 The commands and their descriptions are listed below.
443 .Bl -tag -width Ds -offset indent
444 .It Cm about , version
445 Display the About page.
446 .It Cm buffers , ls , tabs
447 Display the currently opened tabs and let the user switch tabs by typing
448 the tab number or by using the mouse.
449 .It Cm ca
450 Display CA certificates.
451 .It Cm cert , cert show
452 Download and display certificates of the domain on current tab.
453 .It Cm cert save
454 Save certificate into a local store.
455 The next time the site is visited it is compared against the store.
456 If the certificate matches,
457 the address bar will be blue;
458 if it doesn't the bar will be red.
459 .It Cm cookie
461 .Cm cookie
462 command is used to manipulate the cookie whitelist.
463 Used by itself it expands to
464 .Cm cookie show all .
465 .It Cm cookiejar
466 Show cookie jar contents.
467 .It Cm cookie purge
468 Remove all cookies from the cookie jar.
469 .It Cm cookie save, cookie save fqdn
470 Save the current fully qualified domain name (FQDN)
471 to the persistent whitelist.
472 For example,
473 the www.peereboom.us domain would result in saving www.peereboom.us.
474 .It Cm cookie save domain
475 Save the top level domain name to the persistent whitelist.
476 For example,
477 the www.peereboom.us domain would result in saving .peereboom.us.
479 This action enables cookies if it is currently disabled for this entry.
480 .It Cm cookie show all
481 Show all persistent and session entries in the cookie whitelist.
482 .It Cm cookie show persistent
483 Show all persistent entries in the cookie whitelist.
484 .It Cm cookie show session
485 Show all session entries in the cookie whitelist.
486 .It Cm cookie toggle domain
487 Toggle cookie support for the current top level domain.
488 .It Cm cookie toggle, cookie toggle fqdn
489 Toggle cookie support for the current FQDN.
490 .It Cm dl
491 Show download manager.
492 .It Cm encoding Op Ar encoding
493 Set the current tab's encoding to
494 .Ar encoding
495 and reload the tab.
497 .Ar encoding
498 is not provided, the current tab's encoding is displayed.
499 .It Cm editsrc
500 Open the source for the current tab in the editor specified by the
501 setting
502 .Cm external_editor
503 and then check for changes to the file opened. If it is changed, the
504 page will be updated.
505 .It Cm editelement
506 If a text-element is currently active (<input> or <textarea>), it's
507 contents will be opened in the same fashion as for the command
508 .Cm editsrc
509 above
510 .It Cm fav
511 Show favorites.
512 .It Cm favadd Op Ar title
513 Add the current page to favorites.
514 The title can be overridden by specifying
515 .Ar title .
516 .It Cm favedit
517 Show favorites list and links to remove entries.
518 .It Cm fullscreen , f
519 Toggle hiding tabs and url entry toolbar.
520 .It Cm h , hist , history
521 Show global history.
522 .It Cm help
523 Show help page.
524 .It Cm home
525 Go to home URL.
526 .It Cm https
528 .Cm https
529 command is used to manipulate the items in the HTTPS force list.
530 Used by itself it expands to
531 .Cm https show all .
532 .It Cm https save, save fqdn
533 Save the FQDN to the persistent force HTTPS list.
534 For example,
535 the www.peereboom.us domain would result in saving www.peereboom.us.
536 .It Cm https save domain
537 Save the top level domain name to the persistent whitelist.
538 For example,
539 the www.peereboom.us domain would result in saving .peereboom.us.
540 .It Cm https show all
541 Show all persistent and session entries in the HTTPS force list.
542 .It Cm https show persistent
543 Show all persistent entries in the HTTPS force list.
544 .It Cm https show session
545 Shows all session entries in the HTTPS force list.
546 .It Cm https toggle, https toggle fqdn
547 Toggle this FQDN in the HTTPS force list.
548 .It Cm https toggle domain
549 Toggle the top level domain in the HTTPS force list.
550 .It Cm js
552 .Cm js
553 command is used to manipulate the JavaScript whitelist.
554 Used by itself it expands to
555 .Cm js show all .
556 .It Cm js save, save fqdn
557 Save the FQDN to the persistent whitelist.
558 For example,
559 the www.peereboom.us domain would result in saving www.peereboom.us.
560 .It Cm js save domain
561 Save the top level domain name to the persistent whitelist.
562 For example,
563 the www.peereboom.us domain would result in saving .peereboom.us.
565 This action enables JavaScript if it is currently disabled for this entry.
566 .It Cm js show all
567 Show all persistent and session entries in the JavaScript whitelist.
568 .It Cm js show persistent
569 Show all persistent entries in the JavaScript whitelist.
570 .It Cm js show session
571 Show all session entries in the JavaScript whitelist.
572 .It Cm js toggle, js toggle fqdn
573 Toggle JavaScript execution for the current FQDN.
574 .It Cm js toggle domain
575 Toggle JavaScript execution for the current top level domain.
576 .It Cm loadimages
577 If the setting
578 .Cm auto_load_images
579 is disabled, load all images for current site.
580 .It Cm open , op , o Ar URL
581 Open
582 .Ar URL .
583 .It Cm plugin
585 .Cm plugin
586 command is used to manipulate the plugin whitelist.
587 Used by itself it expands to
588 .Cm plugin show all .
589 .It Cm plugin save, save fqdn
590 Save the FQDN to the persistent whitelist.
591 For example,
592 the www.peereboom.us domain would result in saving www.peereboom.us.
593 .It Cm plugin save domain
594 Save the top level domain name to the persistent whitelist.
595 For example,
596 the www.peereboom.us domain would result in saving .peereboom.us.
598 This action enables plugins if they are currently disabled for this entry.
599 .It Cm plugin show all
600 Show all persistent and session entries in the plugin whitelist.
601 .It Cm plugin show persistent
602 Show all persistent entries in the plugin whitelist.
603 .It Cm plugin show session
604 Show all session entries in the plugin whitelist.
605 .It Cm plugin toggle, plugin toggle fqdn
606 Toggle plugin execution for the current FQDN.
607 .It Cm plugin toggle domain
608 Toggle plugin execution for the current top level domain.
609 .It Cm print
610 Print page.
611 .It Cm proxy
613 .Cm proxy
614 command is used to manipulate the currently set proxy.
615 Used by itself it expands to
616 .Cm proxy show .
617 .It Cm proxy show
618 Display the current
619 .Cm http_proxy
620 setting.
621 .It Cm proxy toggle
622 Enable or disable the proxy for
623 .Nm .
624 Note that
625 .Cm http_proxy
626 must be set before it can be toggled.
627 .It Cm qa , qall , quitall
628 Quit
629 .Nm .
630 .It Cm quit , q
631 Close current tab and quit
633 if it is the last tab.
634 .It Cm restart
635 Restart
637 and reload all current tabs.
638 .It Cm run_script Op Ar path_to_script
639 Run the script
640 .Ar path_to_script
641 with the current uri as the argument.
643 .Ar path_to_script
644 is not provided, the script specified by the
645 .Cm default_script
646 setting is used instead.
647 .It Cm script Ar filename
648 Run an external JavaScript script file in the current tab context.
649 .It Cm session , Cm session show
650 Display the current session name.
651 By default the session name is
652 .Dq main_session .
653 To create a new session use the
654 .Cm session save
655 command.
656 A session is defined as the lifetime of the browser application.
657 .It Cm session delete Ar session_name
658 Delete session
659 .Ar session_name
660 from persistent storage.
662 .Ar session_name
663 is the current session then the session will revert to
664 .Dq main_session .
665 .It Cm session open Ar session_name
666 Close all tabs and open session
667 .Ar session_name .
668 Going forward this session is named
669 .Ar session_name .
670 .It Cm session save Ar session_name
671 Save current tabs to session
672 .Ar session_name .
673 This will close the current session and going forward this session is named
674 .Ar session_name .
675 .It Cm set
677 .Cm set
678 command is used to inspect, clear or change runtime options.
679 There are 3 methods to use
680 .Cm set .
681 When used by itself as
682 .Dq Cm :set
683 the command displays all options as currently set.
685 To set a value use
686 .Dq Cm :set Ao Ar option Ac Ns = Ns Aq Ar value .
687 For example,
688 .Dq Cm :set http_proxy=http://127.0.0.1:8080 .
690 To clear a value use
691 .Dq Cm :set Ao Ar option Ac Ns = .
692 For example,
693 .Dq Cm :set http_proxy= .
695 Note, not all options can be set at runtime.
696 .It Cm stats
697 Show blocked cookie statistics.
698 These statistics vary based on settings and are not persistent.
699 .It Cm statustoggle , statust
700 Toggle status bar.
701 .It Cm stop
702 Stop loading the current web page.
703 .It Cm tabclose
704 Close current tab.
705 .It Cm tabhide
706 Hide tabs.
707 .It Cm tabnew , tabedit Op Ar URL
708 Create a new tab and optionally open provided
709 .Ar URL .
710 .It Cm tabnext
711 Go to the next tab.
712 .It Cm tabonly
713 Close all tabs except the currently focused one.
714 .It Cm tabprevious
715 Go to the previous tab.
716 .It Cm tabshow
717 Show tabs in GUI.
718 .It Cm toplevel , toplevel toggle
719 Toggle the top level domain name cookie and JS session whitelist.
720 This is to enable/disable short lived full site functionality without
721 permanently adding the top level domain to the persistent whitelist.
722 .It Cm urlhide , urlh
723 Hide url entry and toolbar.
724 .It Cm urlshow , urls
725 Show url entry and toolbar.
726 .It Cm userstyle Op Ar stylesheet
727 Toggle the current tab between using the custom stylesheet
728 .Ar stylesheet
729 and the page's default CSS.
731 .Ar stylesheet
732 is not provided, the stylesheet specified by the
733 .Cm userstyle
734 setting will be used.
735 This
736 .Cm userstyle
737 setting is set by default to a low-contrast color scheme.
739 Additional stylesheets may be used in addition to that set by
740 .Cm userstyle
741 by specifying additional keybindings.
742 For example,
744 .D1 keybinding = userstyle ~/style.css,v
745 .D1 keybinding = userstyle_global ~/style.css,V
747 will map toggling between ~/style.css to the v and V keys while
748 keeping the stylesheet specified by
749 .Cm userstyle
750 mapped to the s and S keys.
751 .It Cm userstyle_global Op Ar stylesheet
752 Same as the
753 .Cm userstyle
754 command but affects all open tabs and newly created tabs will use
755 this style.
756 .It Cm w
757 Save open tabs to current session.
758 The tabs will be restored next time the session is opened.
759 See the session command for additional details.
760 .It Cm wq
761 Save open tabs and quit.
762 The tabs will be restored next time the session is opened.
763 See the
764 .Cm session
765 command for more details.
767 .Sh BUFFER COMMANDS
768 In addition to shortcuts and commands
770 provides buffer commands. Buffer commands are short, multi character
771 vi-like commands, often requiring an argument. Partial buffer commands
773 displayed in the buffer command statusbar element (see
774 .Cm statusbar_elems ) .
775 Pressing Esc or switching to another tab cancels a partially entered
776 buffer command. In the following list
777 .Cm arg
778 denotes the argument a buffer command accepts. Buffer commands are
779 defined as extended regular expressions.
780 Note that if a character is used as a shortcut it will not be interpreted
781 as the beginning of a buffer command. This is the case with
782 .Cm 0 .
784 .Bl -tag -width "['][a-zA-Z0-9]XXX" -offset indent -compact
785 .It Cm gg
786 go to the top of the page
787 .It Cm gG
788 go to the bottom of the page
789 .It Cm [0-9]+%
790 go to the
791 .Cm arg
792 percent of the page
793 .It Cm zz
794 go to 50% of the page
795 .It Cm [0-9]*gu
797 .Cm arg
798 levels up. If
799 .Cm arg
800 is missing, 1 is assumed. Going a
801 level up means going to a URI obtained from the current one by removing
802 the last slash ('/') character and everything that follows it
803 .It Cm gU
804 go to the root level, i.e. going up as many levels as possible.
805 .It Cm gh
806 open the home page in the current tab
807 .It Cm m[a-zA-Z0-9]
808 set a mark denoted by
809 .Cm arg
810 at the current page position. These marks behave like those in vi or
811 less.
812 .It Cm ['][a-zA-Z0-9']
813 go to the position where mark
814 .Cm arg
815 was set. The special mark "'" points to the previous page position, after a
816 "gg", "gG", "zz", "%" or "'" buffer command.
817 .It Cm M[a-zA-Z0-9]
818 set the current uri as quickmark
819 .Cm arg
820 .It Cm go[a-zA-Z0-9]
821 open the uri marked as quickmark
822 .Cm arg
823 in the current tab
824 .It Cm gn[a-zA-Z0-9]
825 open the uri marked as quickmark
826 .Cm arg
827 in a new tab
828 .It Cm [0-9]+t
829 activate tab number
830 .It Cm g0
831 go to first tab
832 .It Cm g$
833 go to last tab
834 .It Cm [0-9]*gt
835 go to the
836 .Cm arg
837 next tab
838 .It Cm [0-9]*gT
839 go to the
840 .Cm arg
841 previous tab
842 .Cm arg
843 .It Cm ZZ
844 quit
846 .It Cm ZR
847 restart
849 .It Cm zi
850 zoom in by 4%
851 .It Cm zo
852 zoom out by 4%
853 .It Cm z0
854 set zoom level to 100%
855 .It Cm [0-9]+Z
856 set zoom level to
857 .Cm arg
860 .Sh QUICKMARKS
861 Quickmarks are like bookmarks, except they are referred to by a single
862 character (a letter or a digit), instead of a longer name. See the
863 .Cm M[a-zA-Z0-9] ,
864 .Cm go[a-zA-Z0-9]
866 .Cm gn[a-zA-Z0-9]
867 buffer commands for usage. Quickmarks are stored in
868 .Pa ~/.xombrero/quickmarks
869 and are saved automatically after each
870 .Cm M[a-zA-Z0-9]
871 buffer command.
872 .Sh ABOUT SCREENS
873 The about screens are internally generated web pages by
875 for user interaction.
876 These are entered in the address bar and the format is
877 .Cm about:screen
878 where screen is the desired screen to display.
879 For example about:favorites.
880 Any about screen can be used as the home page as specified by
881 .Cm home
882 in the configuration file.
884 .Bl -tag -width "downloadsXXX" -offset indent -compact
885 .It Cm about
886 show the about screen
887 .It Cm blank
888 show a blank screen
889 .It Cm cookiewl
890 show the cookie whitelist screen
891 .It Cm cookiejar
892 show the cookiejar screen
893 .It Cm downloads
894 show the downloads screen
895 .It Cm favorites
896 show the favorites screen
897 .It Cm help
898 show the help web page
899 .It Cm history
900 show the history screen
901 .It Cm jswl
902 show the JavaScript whitelist screen
903 .It Cm plwl
904 show the plugin whitelist screen
905 .It Cm set
906 show the settings screen
907 .It Cm stats
908 show the statistics screen
910 .Sh WHITELISTS
911 This section describes advanced usage settings.
912 Most users should use
913 .Cm browser_mode
914 instead to setup
916 and skip over this section.
919 has a number of whitelists to control blocking cookies and JavaScript
920 execution for FQDNs or domains.
921 When properly enabled these whitelists require either the FQDN or top level
922 domain to exist in the whitelists in order to allow cookies to be stored or
923 JavaScript to execute.
924 Both JavaScript and cookies have two whitelists associated with them.
925 The whitelists are called session and persistent.
926 Items in the session whitelists are only allowed for the lifetime of the
928 instance.
929 Items in the persistent whitelists are stored on disk and are restored
930 upon restarting.
932 Setting up the whitelists is a little tricky due to intricacies of WebKit.
933 In fact the semantics are different for cookies and JavaScript.
935 Cookie whitelist requires the following configuration to be set:
937 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
938 .It Cm cookies_enabled
939 This is a WebKit setting and must be set to
940 .Pa 1
941 (ENABLED)
942 in order to be able to use a
943 cookie whitelist.
944 .It Cm enable_cookie_whitelist
945 This needs to be set to
946 .Pa 1
947 to enable the cookie whitelist functionality.
948 .It Cm cookie_wl
949 These entries in the configuration file are the actual domains names in the
950 cookie whitelist.
953 JavaScript whitelist requires the following configuration to be set:
955 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
956 .It Cm enable_scripts
957 This is a WebKit setting and must be set to
958 .Pa 0
959 (DISABLED)
960 in order to be able to use a
961 JavaScript whitelist.
962 .It Cm enable_js_whitelist
963 This needs to be set to
964 .Pa 1
965 to enable the JavaScript whitelist functionality.
966 .It Cm js_wl
967 These entries in the configuration file are the actual domains names in the
968 JavaScript whitelist.
971 Plugin whitelist requires the following configuration to be set:
973 .Bl -tag -width "enable_plugin_whitelistXXX" -offset indent -compact
974 .It Cm enable_plugins
975 This is a WebKit setting and must be set to
976 .Pa 1
977 (ENABLED)
978 in order to be able to use a
979 plugin whitelist.
980 .It Cm enable_plugin_whitelist
981 This needs to be set to
982 .Pa 1
983 to enable the plugin whitelist functionality.
984 .It Cm pl_wl
985 These entries in the configuration file are the actual domains names in the
986 plugin whitelist.
989 See the
990 .Pa FILES
991 section for additional configuration file entries and details
992 that alter runtime behavior.
993 .Sh FILES
994 .Bl -tag -width "/etc/xombrero.confXXX" -compact
995 .It Pa ~/.xombrero.conf
997 user specific settings.
998 .It Pa ~/.xombrero
1000 scratch directory.
1004 tries to open the user specific file,
1005 .Pa ~/.xombrero.conf .
1006 If that file is unavailable,
1007 it then uses built-in defaults.
1008 Any settings saved at runtime will be saved to the file
1009 .Pa ~/.xombrero/runtime
1010 and will be loaded as well.
1012 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
1013 For example:
1015 .Dl http_proxy = http://127.0.0.1:8080
1017 Enabling or disabling an option is done by using 1 or 0 respectively.
1019 The file supports the following keywords:
1021 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
1022 .It Cm alias
1023 Defines an alias for a given URL, so that the URL is loaded when the alias is
1024 entered in the address bar.
1025 If the aliased URL includes a %s format specifier, then any argument given after
1026 the alias on the address bar is substituted.
1027 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
1028 then the URL http://www.google.com/search?q=foo is loaded when navigating to
1029 "g foo".
1030 .It Cm allow_insecure_content
1031 If set, all content referenced by a page will be loaded.
1032 If unset, encrypted pages will refuse to load content that is linked
1033 from an insecure location.
1034 .It Cm allow_insecure_scripts
1035 If set, all scripts referenced by a page will be loaded and run using
1036 the current javascript policy.
1037 If unset, encrypted pages will refuse to run scripts that are linked
1038 from an insecure location.
1039 .It Cm allow_volatile_cookies
1040 If set cookies are stored in the session cache but will be discarded once
1042 exits.
1043 Unfortunately enabling this does allow for some limited tracking on the web.
1044 .It Cm anonymize_headers
1045 If set, HTTP headers taken from the
1046 .Lk https://www.bitrig.org/ "Bitrig website"
1047 will be used to feed additional values to the
1048 .Nm xombrero
1049 HTTP header settings.
1050 Currently only the User-Agent and Http-Accept headers are modified,
1051 corresponding to the
1052 .Cm user_agent
1054 .Cm http_accept
1055 settings, respectively.
1056 These headers are set after any header settings are read in from your
1057 .Cm ~/.xombrero.conf .
1058 Default is 0.
1059 .It Cm append_next
1060 When set a new tab is appended after the current tab instead of being appended
1061 as the last tab.
1062 .It Cm auto_load_images
1063 If disabled, images will not be loaded automatically.
1064 .It Cm autofocus_onload
1065 When set a tab that is loaded will attempt to autofocus the default input
1066 entry.
1067 This is only done for tabs that are currently visible.
1068 .It Cm browser_mode
1071 browser has 3 default operating modes:
1072 .Pa normal
1073 (the default),
1074 .Pa whitelist
1076 .Pa kiosk .
1077 In the
1078 .Pa normal
1079 mode the browser allows all cookies, plugins and JavaScript as any other
1080 browser would.
1081 This means that all cookies are saved to persistent storage and that all
1082 JavaScript and plugins run.
1084 On the other hand, using the
1085 .Pa whitelist
1086 mode enables whitelists.
1087 This requires the user to add all the required
1088 .Pa cookie_wl ,
1089 .Pa js_wl
1091 .Pa pl_wl
1092 items.
1093 If a domain does not appear in the whitelists
1095 disallows cookies, JavaScript and plugin execution.
1096 If insecure web content or scripts are referenced by a secure website,
1097 they will be blocked from loading or running.
1100 .Pa kiosk
1101 mode the browse works just like
1102 .Pa normal
1103 mode however the toolbar only has the backward, forward and home button.
1105 This setting must be the first entry in
1106 .Pa ~/.xombrero.conf
1107 because it sets advanced settings that can be overridden later in the file.
1108 See the default config file for more details.
1109 .It Cm cmd_alias
1110 This setting is used to define an alias for a command.
1111 The syntax of this setting is
1112 .Pa cmd_alias = alias,cmd .
1113 For example, if you wanted to set an alias for the
1114 .Pa tabnew
1115 command to
1116 .Pa tn ,
1117 add the line
1118 .Pa cmd_alias = tn,tabnew
1119 to your
1120 .Pa ~/.xombrero.conf .
1121 This setting may not begin with a number.
1122 .It Cm cmd_font
1123 Set the command prompt font.
1124 E.g.
1125 .Pa cmd_font = monospace normal 9 .
1126 .It Cm color_visited_uris
1127 When enabled (the default)
1129 will color visited links. This is done while the web page loads using
1130 JavaScript, rather than WebKit's (broken, see bug #51747) built-in
1131 facility for coloring visited links. The JavaScript approach is
1132 (probably) slower and is not consistent across tabs (unless the tabs are
1133 reloaded), but has the advantage of not leaking history data to web
1134 pages (see http://wtikay.com/docs/details.html).
1135 .It Cm cookie_policy
1136 This field delineates the cookie policy.
1137 Possible values are: no3rdparty, reject 3rd party cookies.
1138 accept, accept all cookies.
1139 reject, reject all cookies.
1140 .It Cm cookie_wl
1141 This is a cookie whitelist item.
1142 Use multiple times to add multiple entries.
1143 Valid entries are for example *.moo.com and the equivalent .moo.com.
1144 This matches both moo.com, as well as all subdomains.
1145 A fully qualified host is also valid and is for example www.moo.com or
1146 moo.com.
1147 Fully qualified hosts do not modify whitelist settings for any
1148 subdomains.
1150 Unix extended regular expressions may also be used to match any set of
1151 FQDNs.
1152 Regular expressions must begin with the prefix "re:".
1153 As an example, the regular expression equivalent to moo.com would be
1154 .Pa ^moo\.com$ ,
1155 and the equivalent to .moo.com would be
1156 .Pa ^(.*\.)*moo\.com$ .
1157 If using regular expressions for whitelist items, be careful to not
1158 accidentally match other domains;
1159 you will almost always want to add the ^ and $ characters to the
1160 beginning and end of the regex so that, for example,
1161 .Pa moo\.com
1162 would not match not-moo.com.
1163 .It Cm cookies_enabled
1164 Enable cookies.
1165 .It Cm ctrl_click_focus
1166 Give focus in newly created tab instead of opening it in the background.
1167 .It Cm custom_uri
1168 This setting provides the ability to run custom executables for
1169 special URIs.
1170 The syntax for this setting is
1171 .Pa custom_uri\ =\ protocol,command .
1172 The URI is passed as a single argument to
1173 .Pa command
1174 to be parsed and executed.
1176 For example, to add the ability to use custom
1177 .Pa mailto
1178 URIs, add the setting
1179 .Pa custom_uri = mailto,command
1180 where
1181 .Pa command
1182 is a program that will parse the
1183 .Pa mailto
1184 URI and open your mail client.
1185 .It Cm default_script
1186 Path to the script used as the default value for the run_script
1187 command.
1188 .It Cm default_zoom_level
1189 Set the default browsing zoom level.
1190 .It Cm do_not_track
1191 Sets the HTTP Do Not Track header to tell sites that you wish to be
1192 opted-out of 3rd-party tracking for the use of behavioral advertising.
1193 Not all sites currently support this header, and this is only a
1194 suggestion of a user preference.
1195 Sites may still perform 3rd-party tracking even when this feature is
1196 enabled.
1197 .It Cm download_dir
1198 Locations where files are downloaded to.
1199 This directory must exist and
1201 validates that during startup.
1202 .It Cm download_mode
1203 Controls how downloads are handled.
1204 Possible values are:
1205 .Bd -literal -offset indent
1206 start - automatically start download.
1207 ask   - ask user for confirmation.
1208 add   - add to downloadmanager, but
1209         do not start.
1211 The default is "start".
1212 .It Cm download_notifications
1213 When enabled a message is shown when downloads are finished.
1214 Default is 0.
1215 .It Cm enable_autoscroll
1216 When enabled clicking MB3 will spawn the autoscroll ball, scrolling can
1217 then proceed by dragging the mouse away from the ball.
1218 .It Cm enable_cookie_whitelist
1219 When enabled all cookies must be in the whitelist or they are rejected.
1220 Additionally whitelisted cookies also enable HTML5 local storage for the
1221 domain.
1222 .It Cm enable_cache
1223 When enabled (disabled by default), web content will be cached into
1224 memory.
1225 .It Cm enable_favicon_entry
1226 When enabled (the default)
1228 displays the favicon of the web page at the URI entry. This setting
1229 affects both
1230 .Cm normal
1232 .Cm compact
1233 tabs.
1234 .It Cm enable_favicon_tabs
1235 When enabled (disabled by default)
1237 displays favicons at each tab. This setting only affects
1238 .Cm compact
1239 tabs.
1240 .It Cm enable_js_autorun
1241 Enables support for autorunning JavaScript after page loads.  When
1242 enabled,
1243 .Pa ~/.xombrero/js/
1244 will be searched for
1245 .Pa default.js
1247 .Pa host.domain.js .
1249 .Pa host.domain.js
1250 does not exist,
1251 .Pa domain.js
1252 will be tried instead.  The content of the both default and
1253 host/domain files are read and executed on each page load.
1254 Default is 1.
1256 As an example, if you add the line
1257 .Pa alert("Hello, world");
1258 to your
1259 .Pa default.js ,
1260 a pop-up displaying "Hello, world" will be shown on every page reload.
1261 While not useful, any javascript can be run through this mechanism,
1262 making it useful for global or site-specific modifications.
1263 .It Cm enable_js_whitelist
1264 When enabled all domains must be in the js whitelist in order to run Java
1265 Script.
1266 NOTE: Make sure
1267 .Cm enable_scripts
1268 is set to 0.
1269 .It Cm enable_plugin_whitelist
1270 When enabled all domains must be in the plugin whitelist in order to run
1271 plugins.
1272 NOTE: Make sure
1273 .Cm enable_plugins
1274 is set to 0.
1275 .It Cm enable_plugins
1276 Enable external plugins such as Flash and Java.
1277 .It Cm enable_strict_transport
1278 Enable support for the Strict-Transport-Security HTTP-header.
1279 When enabled, sites that set this flag will only be visited via HTTPS.
1280 Default value is 1
1281 .It Cm enable_scripts
1282 Enable Java Script.
1283 .It Cm enable_socket
1284 When enabled the first instance of
1286 will create a socket in the
1287 .Pa ~/.xombrero
1288 directory.
1289 Using the -n url option on subsequent
1291 invocations will cause the specified URL to be loaded in a new tab.
1292 Only a user with identical UID and GID can use this option.
1293 .It Cm enable_localstorage
1294 Enable html5 Local Storage.
1295 .It Cm enable_spell_checking
1296 Enables spell checking. Preferred languages can be set using
1297 .Cm spell_check_languages
1298 option.
1299 .It Cm encoding
1300 Set the default encoding.
1301 E.g.
1302 .Pa encoding = ISO-8859-1 .
1303 .It Cm external_editor
1304 Set which editor to use for external editing.
1305 the string <file> will be replaced by the current filename.
1306 E.g.
1307 .Pa external_editor = gvim -f <file>
1308 Note!
1309 .Cm xombrero
1310 relies on the editor
1311 .Pa not forking
1312 into the background.
1313 .It Cm fancy_bar
1314 Enables a backward, forward, and stop button to the toolbar.
1315 Additionally if
1316 .Cm search_string
1317 is set it'll enable an entry box for searches.
1318 .It Cm force_https
1319 This setting is used to define the domains of sites that should be
1320 only accessed over the HTTPS scheme.
1321 Any requests to these domains over HTTP will be rewritten to use HTTPS
1322 instead.
1324 .Cm cookie_wl
1325 for semantics.
1326 .It Cm gnutls_priority_string
1327 If set, this string sets the G_TLS_GNUTLS_PRIORITY environmental
1328 variable to define the GnuTLS priority string that is used when
1329 initializing the GnuTLS session.
1330 This may be used to change the supported TLS/SSL versions and the
1331 ciphers that are used when making HTTPS connections.
1333 Full details on how to modify this setting may be found in the GnuTLS
1334 documentation, Section 8.9: Priority Strings.
1335 For example, to disable the 128-bit RC4 cipher, change this setting to
1336 .Pa NORMAL:!ARCFOUR-128 .
1338 If your glib-networking package is older than version 2.33.10, or if
1339 the G_TLS_GNUTLS_PRIORITY environmental variable is already set, this
1340 setting has no effect.
1341 .It Cm guess_search
1342 When enabled
1344 will try to guess if the string you entered, in the URI entry widget or
1345 the command widget, is term you want to search for using search_string
1346 (see above).
1347 If the string does not contain a dot nor a slash, is not a
1348 path to a local file and does not resolves to an IP then it is assumed
1349 to be a search term.
1350 .It Cm gui_mode
1351 To simplify configuring
1353 allows you pick between two GUI modes:
1354 .Pa classic
1355 (the default) and
1356 .Pa minimal .
1357 In the
1358 .Pa classic
1359 mode the GUI looks similar to that of most mainstream browsers. While in
1360 .Pa minimal
1361 mode the GUI looks more vi-like. One can get a GUI between the two by
1362 tweaking the low-level GUI settings found under the advanced GUI setting
1363 section in the configuration file.
1364 .It Cm history_autosave
1365 When enabled
1367 will save all command and search history.
1368 Upon restarting
1370 the saved command and search history will be restored.
1371 .It Cm home
1372 Homepage in URL format.
1373 .It Cm http_proxy
1374 Proxy server in URL format.
1376 overrides
1377 .Cm http_proxy
1378 if it is specified as an environment variable.
1379 It must be noted that on older Webkit versions one MUST use an IP address and
1380 not a FQDN.
1381 This works as expected with Webkit 1.4.2.
1383 If using libsoup 2.42.2 or newer, one may use a socks proxy directly.
1384 For example:
1385 .Bd -literal -offset indent
1386 http_proxy = socks5://127.0.0.1:9050
1388 Otherwise, an intermediary tool, such as polipo or tsocks, must be used.
1389 .It Cm http_accept
1390 If set, the HTTP Accept header will be modified for each text/html request.
1391 If this setting is set multiple times, the Accept header will be changed
1392 in a round-robin order for every text/html request on a tab.
1393 Because this setting rotates through Accept headers on each text/html
1394 request, a single page may rotate through more than one Accept header
1395 if multiple text/html requests are made.
1397 Please be aware that not all websites report browser headers correctly.
1398 Most notably, EFF's panopticlick service also reports the HTTP
1399 Accept-Encoding headers on the same line as the Accept headers.
1400 If you are trying to find the headers of another browser to model that
1401 browser's fingerprint, it is recommended to not use panopticlick for
1402 this reason.
1404 Note that this setting only rewrites the Accept header for text/html
1405 requests.  Other requests will use WebKit's default  Accept header.
1406 .It Cm http_proxy_starts_enabled
1407 If set to 0, the http_proxy will be disabled at startup. The user can later
1408 enable the proxy with the
1409 .Cm proxy toggle
1410 command or keybinding.
1411 .It Cm icon_size
1412 Permits icon sizes to be changed if
1413 .Cm fancy_bar
1414 is enabled.
1415 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
1416 .It Cm include_config
1417 This must be a path to another configuration file.
1418 Configuration files are usually read from top to bottom, however, if
1419 this option is set,
1421 will begin reading the included file at this location and continue
1422 reading the rest of the configuration after the included file has
1423 finished being read.
1425 Any simple settings set before the include may
1426 be overridden by settings in the included file, and any simple
1427 settings set in the included file may be overridden later by settings
1428 after the include or at runtime using the
1429 .Cm :set
1430 command.
1431 However, database settings (for example,
1432 .Cm cookie_wl , js_wl , pl_wl ,
1434 .Cm keybinding )
1435 are only ever added to the database, and so the order of an included
1436 configuration file is not pertinent to these database settings.
1438 This feature is likely best used as the last item in
1439 .Pa ~/.xombrero.conf .
1440 .It Cm js_auto_open_windows
1441 If enabled, javascripts will be allowed to automatically open windows
1442 based on the current
1443 .Cm browser_mode .
1444 If disabled, it will never be allowed.  The default setting is 1 (enabled).
1445 .It Cm js_wl
1446 This is a JavaScript whitelist item.
1448 .Cm cookie_wl
1449 for semantics and more details.
1450 .It Cm max_connections
1451 The maximum number of connections that
1453 can open at once.
1454 .It Cm max_host_connections
1455 The maximum number of connections that
1457 can open at once to a given host.
1458 .It Cm mime_type
1459 Sets an action for a specific or default MIME type.
1460 For example, to download and view a pdf using kpdf set
1461 .Pa mime_type = application/pdf,kpdf .
1462 To set a default value use *, for example,
1463 .Pa mime_type = video/*,mplayer .
1464 Note that the action is only passed the URL and not all applications are
1465 capable of dealing with a URL and therefore one might have to create a wrapper
1466 script to download the content first.  Alternatively one can add the
1467 .Pa @
1468 in front of the MIME type to indicate "download first".
1469 For example,
1470 .Pa mime_type = @application/pdf,xpdf .
1471 When
1472 .Pa @
1473 is use the file will be downloaded to the
1474 .Pa download_dir
1475 before the MIME handler is called.
1477 The special binary name "donothing" may be used to ignore a MIME type
1478 without displaying any warnings from being unable to execute the
1479 binary.
1480 .It Cm oops_font
1481 Set the font used to display error messages.
1482 E.g.
1483 .Pa oops_font = monospace normal 9 .
1484 .It Cm pl_wl
1485 This is a plugin whitelist item.
1487 .Cm cookie_wl
1488 for semantics and more details.
1489 .It Cm preload_strict_transport
1490 If enabled, a preloaded list of sites which set the HTTP Strict
1491 Transport Security header will be used to automatically set the
1492 .Cm force_https
1493 setting for these sites.
1494 This is used to prevent SSL stripping attacks when first visiting
1495 these sites, before they have been added to the strict-transport file.
1496 This list is comprised of domains chosen by the
1498 authors, as well as domains included in Chromium's preloaded HSTS
1499 list.
1500 Default is 1.
1501 .It Cm read_only_cookies
1502 Mark cookies file read-only and discard all cookies once the session is
1503 terminated.
1504 .It Cm refresh_interval
1505 Refresh interval while in the download manager.
1506 The default is 10.
1507 .It Cm referer
1508 Control how
1509 .Dq referer
1510 is handled in http-requests.
1511 .Bd -literal -offset indent
1512 always      - always send referer
1513 never       - never send referer
1514 same-domain - only send referer if it's
1515               for the same public suffix - this means that
1516               it's OK for subdomains to refer to each other
1517 same-fqdn   - only send referer if it's FQDN match
1519 Any other value that is also a valid URL will use this
1520 custom value as referer. (E.g. you could set it to http://no-referer.com)
1521 The default value is
1522 .Dq always .
1523 .It Cm resource_dir
1524 Directory that contains various
1526 resources such as icons.
1527 This is OS-specific and should be handled by the porter.
1528 .It Cm save_global_history
1529 If set the global history will be saved to
1530 .Pa ~/.xombrero/history
1531 when quitting
1532 and restored at startup.
1533 See the
1534 .Sx KEY BINDINGS
1535 section above for how the global history is accessed.
1536 Global history is not saved to disk by default.
1537 .It Cm save_rejected_cookies
1538 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
1539 All cookies are saved and unlike a cookie jar they are never replaced.
1540 Make sure there is enough disk space to enable this feature.
1541 .It Cm search_string
1542 Default search engine string.
1543 See the
1544 .Pa xombrero.conf
1545 file for details.
1546 .It Cm session_autosave
1547 Enable session auto-saving when changing state (e.g. adding or removing a tab).
1548 The session name is what is currently in use and is described in the
1549 .Cm session save
1551 .Cm session open
1552 commands.
1553 .It Cm session_timeout
1554 This value is the time that is added in seconds to a session cookie.
1555 .It Cm show_tabs
1556 Enable or disable showing tabs.
1557 .It Cm show_url
1558 Enable or disable showing the url and toolbar.
1559 .It Cm show_scrollbars
1560 Enable or disable the showing of the horizontal and vertical scrollbars.
1561 Disabling this setting requires GTK3.
1562 .It Cm show_statusbar
1563 Enable or disable showing the status bar.
1564 .It Cm single_instance
1565 If set and
1566 .Cm enable_socket
1567 is enabled only one
1569 will be permitted to run.
1570 If there is a URL specified it will be opened in a new tab in the already
1571 running
1573 session.
1574 .It Cm spell_check_languages
1575 The languages to be used for spell checking, separated by commas. For example,
1576 en_US.
1577 .It Cm ssl_ca_file
1578 If set to a valid PEM file
1579 all server certificates will be validated against it.
1580 The URL bar will be colored green (or blue when saved) when the certificate is
1581 trusted and yellow when untrusted.
1584 .Cm ssl_ca_file
1585 is not set, the URL bar will be colored red if the certificate has not
1586 been saved, or blue if it has been saved.
1588 WebKit only supports a single PEM file.
1589 Many OS' or distributions have many PEM files.
1590 One can simply concatenate all separate files into one large one.
1591 E.g.
1592 .Cm for i in `ls`; do cat $i >> cert.pem; done
1593 and use the resulting cert.pem file as the input to
1594 .Cm ssl_ca_file .
1595 It is advisable to periodically recreate the cert.pem file.
1596 .It Cm ssl_strict_certs
1597 If this value is set connections to untrusted sites will be aborted.
1598 This value is only used if
1599 .Cm ssl_ca_file
1600 is set.
1601 .It Cm statusbar_elems
1602 Define the components of the status bar. The possible components are:
1603 .Bd -literal -offset indent
1604 | - separator
1605 P - page progress percent
1606 p - proxy enabled/disabled
1607 B - buffer command
1608 Z - page zoom level
1609 T - current tab number
1611 The default is "BP".
1612 These components show nothing if there is nothing worth showing, like
1613 zoom amount 100%.
1614 .It Cm statusbar_font
1615 Set the status bar font.
1616 E.g.
1617 .Pa statusbar_font = monospace normal 9 .
1618 .It Cm statusbar_style
1619 Set the status bar style to either
1620 .Cm url
1621 - display the current url, or
1622 .Cm title
1623 - display the page title. The default is
1624 .Cm url .
1625 .It Cm tab_style
1626 Set the tab style to either
1627 .Cm normal
1628 - the default gtk notebook tabs, or
1629 .Cm compact
1630 for an alternative.
1631 You can switch the tab style with the
1632 .Pa tabnextstyle
1633 command.
1634 .It Cm tabbar_font
1635 Set the compact tab bar font.
1636 E.g.
1637 .Pa tabbar_font = monospace normal 9 .
1638 .It Cm tabless
1639 Disable tabs, and open new windows instead.
1640 Note that this feature does not disable the display of tabs.
1641 Change your
1642 .Cm show_tabs
1643 setting also if you wish to disable the display of tabs.
1644 Default is 0.
1645 .It Cm url_regex
1646 This is the regular expression that is used to match what constitutes a valid
1647 URL when using
1648 .Pa guess_search .
1649 .It Cm user_agent
1650 Set to override the default
1652 user-agent string. May be specified several times for switching between
1653 user-agents.
1654 .It Cm userstyle
1655 Set the stylesheet to be used as a default for the
1656 .Cm userstyle
1658 .Cm userstyle_global
1659 commands when no extra parameters are given.
1660 The default is a low-contrast stylesheet.
1661 .It Cm userstyle_global
1662 When enabled new tabs will automatically be displayed using the custom
1663 stylesheet specified by the
1664 .Cm userstyle
1665 setting.
1666 .It Cm warn_cert_changes
1667 When enabled all SSL certificates from HTTPS websites will be
1668 cached in the
1669 .Cm ~/.xombrero/certs_cache/
1670 directory.
1671 On each page load, if the remote certificate differs from the cached
1672 local version, a warning page with options of what to do next will be displayed
1673 instead of the requested page.
1674 This feature may be used in addition to the coloring of the URL bar and
1675 can be used to help prevent against man-in-the-middle attacks, even if
1676 the new remote certificate is signed by a trusted certificate
1677 authority in
1678 .Cm ssl_ca_file .
1679 Default is 0.
1680 .It Cm window_height
1681 Set the default height of the browser window.
1682 .It Cm window_width
1683 Set the default width of the browser window.
1684 .It Cm window_maximize
1685 Maximize the browser window at startup.
1686 .It Cm work_dir
1687 Set the work directory where all
1689 scratch files are stored.
1690 Default is
1691 .Cm ~/.xombrero .
1693 .Sh HISTORY
1695 was inspired by vimprobable2 and the bloat in other
1697 web browsers.
1698 .Sh AUTHORS
1699 .An -nosplit
1701 was written by
1702 .An Marco Peereboom Aq marco@peereboom.us ,
1703 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
1704 .An Edd Barrett Aq vext01@gmail.com ,
1705 .An Todd T. Fries Aq todd@fries.net ,
1706 .An Raphael Graf Aq r@undefined.ch ,
1707 .An Michal Mazurek Aq akfaew@jasminek.net ,
1709 .An Josh Rickmar Aq jrick@devio.us .