xombrero.1

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