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 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
 103 .El
 104 .Pp
 105 To browse to a specific address,
 106 either use the mouse to click on the address bar
 107 or press
 108 .Cm F6
 109 to shift the keyboard focus to the address bar.
 110 The address is then entered manually.
 111 .Pp
 112 The mouse can be used to navigate the page in the traditional manner,
 113 or the keyboard can be used instead.
 114 For example,
 115 .Cm PageUp
 116 and
 117 .Cm PageDown
 118 will scroll up and down the page.
 119 .Pp
 120 To follow a link,
 121 either click on it or use the
 122 .Cm f
 123 key and have
 124 .Nm
 125 assign numbers to each link on the page;
 126 entering that number on the keyboard will prompt
 127 .Nm
 128 to follow the link.
 129 .Sh KEY BINDINGS
 130 .Nm
 131 provides many actions accessed via key or mouse bindings.
 132 Most can be reprogrammed using a
 133 .Cm keybinding
 134 entry in the configuration file.
 135 Each keyboard shortcut requires exactly one entry in the configuration file.
 136 A shortcut can have multiple entries in the configuration file.
 137 The format of the keybinding entry is as follows:
 138 .Pp
 139 .D1 keybinding = (:)action,(!)keystroke(s)
 140 .Pp
 141 For example, "keybinding = tabnew,C-t" where
 142 .Cm tabnew
 143 is the action and
 144 .Cm C-t
 145 are
 146 the keystrokes.
 147 .Pp
 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.
 153 .Pp
 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.
 158 .Pp
 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.
 163 .Pp
 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".
 169 The
 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.
 176 .Pp
 177 Shift should be used sparingly since it gets in the way of non-USA keyboards.
 178 See the accompanying configuration file for examples.
 179 .Pp
 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.
 185 .Pp
 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
 193 .El
 194 .Ss Search Commands
 195 These commands are used to search for text strings within a web page.
 196 .Pp
 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
 210 .El
 211 .Ss Focus Commands
 212 These commands are used to shift the focus of
 213 .Nm
 214 from one area to another.
 215 .Pp
 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
 223 .El
 224 .Ss Command Aliases
 225 These commands allow the user to map specific actions to specific keys.
 226 .Pp
 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"
 234 .El
 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.
 240 .Pp
 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>"
 250 .El
 251 .Ss Navigation Commands
 252 These commands allow the user to navigate web pages and,
 253 to some extent,
 254 control the browser.
 255 .Pp
 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
 323 .El
 324 .Ss Tab Manipulation
 325 .Nm
 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.
 331 .Pp
 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
 372 .El
 373 .Ss Yanking and pasting
 374 These commands copy and paste text to and from the clipboard.
 375 .Pp
 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
 386 .El
 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
 393 .Nm
 394 will follow the link.
 395 .Pp
 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
 403 .El
 404 .Ss Exiting
 405 Commands to exit the browser.
 406 .Pp
 407 .Bl -tag -width Ds -offset indent -compact
 408 .It Cm C-q
 409 Quit
 410 .Pq Cm quitall
 411 .El
 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.
 419 .Pp
 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
 428 .El
 429 .Ss Insert-mode commands
 430 The following commands are only available when editing an input-field
 431 .Pp
 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
 436 .El
 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
 460 The
 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.
 478 .Pp
 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.
 496 If
 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
 527 The
 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
 551 The
 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.
 564 .Pp
 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
 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 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.
 597 .Pp
 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
 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 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
 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 Op Ar path_to_script
 639 Run the script
 640 .Ar path_to_script
 641 with the current uri as the argument.
 642 If
 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.
 661 If
 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
 676 The
 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.
 684 .Pp
 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 .
 689 .Pp
 690 To clear a value use
 691 .Dq Cm :set Ao Ar option Ac Ns = .
 692 For example,
 693 .Dq Cm :set http_proxy= .
 694 .Pp
 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.
 730 If
 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.
 738 .Pp
 739 Additional stylesheets may be used in addition to that set by
 740 .Cm userstyle
 741 by specifying additional keybindings.
 742 For example,
 743 .Pp
 744 .D1 keybinding = userstyle ~/style.css,v
 745 .D1 keybinding = userstyle_global ~/style.css,V
 746 .Pp
 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.
 766 .El
 767 .Sh BUFFER COMMANDS
 768 In addition to shortcuts and commands
 769 .Nm
 770 provides buffer commands. Buffer commands are short, multi character
 771 vi-like commands, often requiring an argument. Partial buffer commands
 772 are
 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 .
 783 .Pp
 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
 796 go
 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
 845 .Nm
 846 .It Cm ZR
 847 restart
 848 .Nm
 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
 858 %
 859 .El
 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]
 865 and
 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
 874 .Nm
 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.
 883 .Pp
 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 set
 904 show the settings screen
 905 .It Cm stats
 906 show the statistics screen
 907 .El
 908 .Sh WHITELISTS
 909 This section describes advanced usage settings.
 910 Most users should use
 911 .Cm browser_mode
 912 instead to setup
 913 .Nm
 914 and skip over this section.
 915 .Pp
 916 .Nm
 917 has a number of whitelists to control blocking cookies and JavaScript
 918 execution for FQDNs or domains.
 919 When properly enabled these whitelists require either the FQDN or top level
 920 domain to exist in the whitelists in order to allow cookies to be stored or
 921 JavaScript to execute.
 922 Both JavaScript and cookies have two whitelists associated with them.
 923 The whitelists are called session and persistent.
 924 Items in the session whitelists are only allowed for the lifetime of the
 925 .Nm
 926 instance.
 927 Items in the persistent whitelists are stored on disk and are restored
 928 upon restarting.
 929 .Pp
 930 Setting up the whitelists is a little tricky due to intricacies of WebKit.
 931 In fact the semantics are different for cookies and JavaScript.
 932 .Pp
 933 Cookie whitelist requires the following configuration to be set:
 934 .Pp
 935 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
 936 .It Cm cookies_enabled
 937 This is a WebKit setting and must be set to
 938 .Pa 1
 939 (ENABLED)
 940 in order to be able to use a
 941 cookie whitelist.
 942 .It Cm enable_cookie_whitelist
 943 This needs to be set to
 944 .Pa 1
 945 to enable the cookie whitelist functionality.
 946 .It Cm cookie_wl
 947 These entries in the configuration file are the actual domains names in the
 948 cookie whitelist.
 949 .El
 950 .Pp
 951 JavaScript whitelist requires the following configuration to be set:
 952 .Pp
 953 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
 954 .It Cm enable_scripts
 955 This is a WebKit setting and must be set to
 956 .Pa 0
 957 (DISABLED)
 958 in order to be able to use a
 959 JavaScript whitelist.
 960 .It Cm enable_js_whitelist
 961 This needs to be set to
 962 .Pa 1
 963 to enable the JavaScript whitelist functionality.
 964 .It Cm js_wl
 965 These entries in the configuration file are the actual domains names in the
 966 JavaScript whitelist.
 967 .El
 968 .Pp
 969 Plugin whitelist requires the following configuration to be set:
 970 .Pp
 971 .Bl -tag -width "enable_plugin_whitelistXXX" -offset indent -compact
 972 .It Cm enable_plugins
 973 This is a WebKit setting and must be set to
 974 .Pa 1
 975 (ENABLED)
 976 in order to be able to use a
 977 plugin whitelist.
 978 .It Cm enable_plugin_whitelist
 979 This needs to be set to
 980 .Pa 1
 981 to enable the plugin whitelist functionality.
 982 .It Cm pl_wl
 983 These entries in the configuration file are the actual domains names in the
 984 plugin whitelist.
 985 .El
 986 .Pp
 987 See the
 988 .Pa FILES
 989 section for additional configuration file entries and details
 990 that alter runtime behavior.
 991 .Sh FILES
 992 .Bl -tag -width "/etc/xombrero.confXXX" -compact
 993 .It Pa ~/.xombrero.conf
 994 .Nm
 995 user specific settings.
 996 .It Pa ~/.xombrero
 997 .Nm
 998 scratch directory.
 999 .El
1000 .Pp
1001 .Nm
1002 tries to open the user specific file,
1003 .Pa ~/.xombrero.conf .
1004 If that file is unavailable,
1005 it then uses built-in defaults.
1006 Any settings saved at runtime will be saved to the file
1007 .Pa ~/.xombrero/runtime
1008 and will be loaded as well.
1009 .Pp
1010 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
1011 For example:
1012 .Pp
1013 .Dl http_proxy = http://127.0.0.1:8080
1014 .Pp
1015 Enabling or disabling an option is done by using 1 or 0 respectively.
1016 .Pp
1017 The file supports the following keywords:
1018 .Pp
1019 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
1020 .It Cm alias
1021 Defines an alias for a given URL, so that the URL is loaded when the alias is
1022 entered in the address bar.
1023 If the aliased URL includes a %s format specifier, then any argument given after
1024 the alias on the address bar is substituted.
1025 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
1026 then the URL http://www.google.com/search?q=foo is loaded when navigating to
1027 "g foo".
1028 .It Cm allow_insecure_content
1029 If set, all content referenced by a page will be loaded.
1030 If unset, encrypted pages will refuse to load content that is linked
1031 from an insecure location.
1032 .It Cm allow_insecure_scripts
1033 If set, all scripts referenced by a page will be loaded and run using
1034 the current javascript policy.
1035 If unset, encrypted pages will refuse to run scripts that are linked
1036 from an insecure location.
1037 .It Cm allow_volatile_cookies
1038 If set cookies are stored in the session cache but will be discarded once
1039 .Nm
1040 exits.
1041 Unfortunately enabling this does allow for some limited tracking on the web.
1042 .It Cm anonymize_headers
1043 If set, HTTP headers taken from the
1044 .Lk https://www.bitrig.org/ "Bitrig website"
1045 will be used to feed additional values to the
1046 .Nm xombrero
1047 HTTP header settings.
1048 Currently only the User-Agent and Http-Accept headers are modified,
1049 corresponding to the
1050 .Cm user_agent
1051 and
1052 .Cm http_accept
1053 settings, respectively.
1054 These headers are set after any header settings are read in from your
1055 .Cm ~/.xombrero.conf .
1056 Default is 0.
1057 .It Cm append_next
1058 When set a new tab is appended after the current tab instead of being appended
1059 as the last tab.
1060 .It Cm auto_load_images
1061 If disabled, images will not be loaded automatically.
1062 .It Cm autofocus_onload
1063 When set a tab that is loaded will attempt to autofocus the default input
1064 entry.
1065 This is only done for tabs that are currently visible.
1066 .It Cm browser_mode
1067 The
1068 .Nm
1069 browser has 3 default operating modes:
1070 .Pa normal
1071 (the default),
1072 .Pa whitelist
1073 and
1074 .Pa kiosk .
1075 In the
1076 .Pa normal
1077 mode the browser allows all cookies, plugins and JavaScript as any other
1078 browser would.
1079 This means that all cookies are saved to persistent storage and that all
1080 JavaScript and plugins run.
1081 .Pp
1082 On the other hand, using the
1083 .Pa whitelist
1084 mode enables whitelists.
1085 This requires the user to add all the required
1086 .Pa cookie_wl ,
1087 .Pa js_wl
1088 and
1089 .Pa pl_wl
1090 items.
1091 If a domain does not appear in the whitelists
1092 .Nm
1093 disallows cookies, JavaScript and plugin execution.
1094 If insecure web content or scripts are referenced by a secure website,
1095 they will be blocked from loading or running.
1096 .Pp
1097 In
1098 .Pa kiosk
1099 mode the browse works just like
1100 .Pa normal
1101 mode however the toolbar only has the backward, forward and home button.
1102 .Pp
1103 This setting must be the first entry in
1104 .Pa ~/.xombrero.conf
1105 because it sets advanced settings that can be overridden later in the file.
1106 See the default config file for more details.
1107 .It Cm cmd_alias
1108 This setting is used to define an alias for a command.
1109 The syntax of this setting is
1110 .Pa cmd_alias = alias,cmd .
1111 For example, if you wanted to set an alias for the
1112 .Pa tabnew
1113 command to
1114 .Pa tn ,
1115 add the line
1116 .Pa cmd_alias = tn,tabnew
1117 to your
1118 .Pa ~/.xombrero.conf .
1119 This setting may not begin with a number.
1120 .It Cm cmd_font
1121 Set the command prompt font.
1122 E.g.
1123 .Pa cmd_font = monospace normal 9 .
1124 .It Cm color_visited_uris
1125 When enabled (the default)
1126 .Nm
1127 will color visited links. This is done while the web page loads using
1128 JavaScript, rather than WebKit's (broken, see bug #51747) built-in
1129 facility for coloring visited links. The JavaScript approach is
1130 (probably) slower and is not consistent across tabs (unless the tabs are
1131 reloaded), but has the advantage of not leaking history data to web
1132 pages (see http://wtikay.com/docs/details.html).
1133 .It Cm cookie_policy
1134 This field delineates the cookie policy.
1135 Possible values are: no3rdparty, reject 3rd party cookies.
1136 accept, accept all cookies.
1137 reject, reject all cookies.
1138 .It Cm cookie_wl
1139 This is a cookie whitelist item.
1140 Use multiple times to add multiple entries.
1141 Valid entries are for example *.moo.com and the equivalent .moo.com.
1142 This matches both moo.com, as well as all subdomains.
1143 A fully qualified host is also valid and is for example www.moo.com or
1144 moo.com.
1145 Fully qualified hosts do not modify whitelist settings for any
1146 subdomains.
1147 .Pp
1148 Unix extended regular expressions may also be used to match any set of
1149 FQDNs.
1150 Regular expressions must begin with the prefix "re:".
1151 As an example, the regular expression equivalent to moo.com would be
1152 .Pa ^moo\.com$ ,
1153 and the equivalent to .moo.com would be
1154 .Pa ^(.*\.)*moo\.com$ .
1155 If using regular expressions for whitelist items, be careful to not
1156 accidentally match other domains;
1157 you will almost always want to add the ^ and $ characters to the
1158 beginning and end of the regex so that, for example,
1159 .Pa moo\.com
1160 would not match not-moo.com.
1161 .It Cm cookies_enabled
1162 Enable cookies.
1163 .It Cm ctrl_click_focus
1164 Give focus in newly created tab instead of opening it in the background.
1165 .It Cm custom_uri
1166 This setting provides the ability to run custom executables for
1167 special URIs.
1168 The syntax for this setting is
1169 .Pa custom_uri\ =\ protocol,command .
1170 The URI is passed as a single argument to
1171 .Pa command
1172 to be parsed and executed.
1173 .Pp
1174 For example, to add the ability to use custom
1175 .Pa mailto
1176 URIs, add the setting
1177 .Pa custom_uri = mailto,command
1178 where
1179 .Pa command
1180 is a program that will parse the
1181 .Pa mailto
1182 URI and open your mail client.
1183 .It Cm default_script
1184 Path to the script used as the default value for the run_script
1185 command.
1186 .It Cm default_zoom_level
1187 Set the default browsing zoom level.
1188 .It Cm do_not_track
1189 Sets the HTTP Do Not Track header to tell sites that you wish to be
1190 opted-out of 3rd-party tracking for the use of behavioral advertising.
1191 Not all sites currently support this header, and this is only a
1192 suggestion of a user preference.
1193 Sites may still perform 3rd-party tracking even when this feature is
1194 enabled.
1195 .It Cm download_dir
1196 Locations where files are downloaded to.
1197 This directory must exist and
1198 .Nm
1199 validates that during startup.
1200 .It Cm download_mode
1201 Controls how downloads are handled.
1202 Possible values are:
1203 .Bd -literal -offset indent
1204 start - automatically start download.
1205 ask   - ask user for confirmation.
1206 add   - add to downloadmanager, but
1207         do not start.
1208 .Ed
1209 The default is "start".
1210 .It Cm download_notifications
1211 When enabled a message is shown when downloads are finished.
1212 Default is 0.
1213 .It Cm enable_autoscroll
1214 When enabled clicking MB3 will spawn the autoscroll ball, scrolling can
1215 then proceed by dragging the mouse away from the ball.
1216 .It Cm enable_cookie_whitelist
1217 When enabled all cookies must be in the whitelist or they are rejected.
1218 Additionally whitelisted cookies also enable HTML5 local storage for the
1219 domain.
1220 .It Cm enable_cache
1221 When enabled (disabled by default), web content will be cached into
1222 memory.
1223 .It Cm enable_favicon_entry
1224 When enabled (the default)
1225 .Nm
1226 displays the favicon of the web page at the URI entry. This setting
1227 affects both
1228 .Cm normal
1229 and
1230 .Cm compact
1231 tabs.
1232 .It Cm enable_favicon_tabs
1233 When enabled (disabled by default)
1234 .Nm
1235 displays favicons at each tab. This setting only affects
1236 .Cm compact
1237 tabs.
1238 .It Cm enable_js_autorun
1239 Enables support for autorunning JavaScript after page loads.  When
1240 enabled,
1241 .Pa ~/.xombrero/js/
1242 will be searched for
1243 .Pa default.js
1244 and
1245 .Pa host.domain.js .
1246 If
1247 .Pa host.domain.js
1248 does not exist,
1249 .Pa domain.js
1250 will be tried instead.  The content of the both default and
1251 host/domain files are read and executed on each page load.
1252 Default is 1.
1253 .Pp
1254 As an example, if you add the line
1255 .Pa alert("Hello, world");
1256 to your
1257 .Pa default.js ,
1258 a pop-up displaying "Hello, world" will be shown on every page reload.
1259 While not useful, any javascript can be run through this mechanism,
1260 making it useful for global or site-specific modifications.
1261 .It Cm enable_js_whitelist
1262 When enabled all domains must be in the js whitelist in order to run Java
1263 Script.
1264 NOTE: Make sure
1265 .Cm enable_scripts
1266 is set to 0.
1267 .It Cm enable_plugin_whitelist
1268 When enabled all domains must be in the plugin whitelist in order to run
1269 plugins.
1270 NOTE: Make sure
1271 .Cm enable_plugins
1272 is set to 0.
1273 .It Cm enable_plugins
1274 Enable external plugins such as Flash and Java.
1275 .It Cm enable_strict_transport
1276 Enable support for the Strict-Transport-Security HTTP-header.
1277 When enabled, sites that set this flag will only be visited via HTTPS.
1278 Default value is 1
1279 .It Cm enable_scripts
1280 Enable Java Script.
1281 .It Cm enable_socket
1282 When enabled the first instance of
1283 .Nm
1284 will create a socket in the
1285 .Pa ~/.xombrero
1286 directory.
1287 Using the -n url option on subsequent
1288 .Nm
1289 invocations will cause the specified URL to be loaded in a new tab.
1290 Only a user with identical UID and GID can use this option.
1291 .It Cm enable_localstorage
1292 Enable html5 Local Storage.
1293 .It Cm enable_spell_checking
1294 Enables spell checking. Preferred languages can be set using
1295 .Cm spell_check_languages
1296 option.
1297 .It Cm encoding
1298 Set the default encoding.
1299 E.g.
1300 .Pa encoding = ISO-8859-1 .
1301 .It Cm external_editor
1302 Set which editor to use for external editing.
1303 the string <file> will be replaced by the current filename.
1304 E.g.
1305 .Pa external_editor = gvim -f <file>
1306 Note!
1307 .Cm xombrero
1308 relies on the editor
1309 .Pa not forking
1310 into the background.
1311 .It Cm fancy_bar
1312 Enables a backward, forward, and stop button to the toolbar.
1313 Additionally if
1314 .Cm search_string
1315 is set it'll enable an entry box for searches.
1316 .It Cm force_https
1317 This setting is used to define the domains of sites that should be
1318 only accessed over the HTTPS scheme.
1319 Any requests to these domains over HTTP will be rewritten to use HTTPS
1320 instead.
1321 See
1322 .Cm cookie_wl
1323 for semantics.
1324 .It Cm gnutls_priority_string
1325 If set, this string sets the G_TLS_GNUTLS_PRIORITY environmental
1326 variable to define the GnuTLS priority string that is used when
1327 initializing the GnuTLS session.
1328 This may be used to change the supported TLS/SSL versions and the
1329 ciphers that are used when making HTTPS connections.
1330 .Pp
1331 Full details on how to modify this setting may be found in the GnuTLS
1332 documentation, Section 8.9: Priority Strings.
1333 For example, to disable the 128-bit RC4 cipher, change this setting to
1334 .Pa NORMAL:!ARCFOUR-128 .
1335 .Pp
1336 If your glib-networking package is older than version 2.33.10, or if
1337 the G_TLS_GNUTLS_PRIORITY environmental variable is already set, this
1338 setting has no effect.
1339 .It Cm guess_search
1340 When enabled
1341 .Nm
1342 will try to guess if the string you entered, in the URI entry widget or
1343 the command widget, is term you want to search for using search_string
1344 (see above).
1345 If the string does not contain a dot nor a slash, is not a
1346 path to a local file and does not resolves to an IP then it is assumed
1347 to be a search term.
1348 .It Cm gui_mode
1349 To simplify configuring
1350 .Nm
1351 allows you pick between two GUI modes:
1352 .Pa classic
1353 (the default) and
1354 .Pa minimal .
1355 In the
1356 .Pa classic
1357 mode the GUI looks similar to that of most mainstream browsers. While in
1358 .Pa minimal
1359 mode the GUI looks more vi-like. One can get a GUI between the two by
1360 tweaking the low-level GUI settings found under the advanced GUI setting
1361 section in the configuration file.
1362 .It Cm history_autosave
1363 When enabled
1364 .Nm
1365 will save all command and search history.
1366 Upon restarting
1367 .Nm
1368 the saved command and search history will be restored.
1369 .It Cm home
1370 Homepage in URL format.
1371 .It Cm http_proxy
1372 Proxy server in URL format.
1373 .Nm
1374 overrides
1375 .Cm http_proxy
1376 if it is specified as an environment variable.
1377 It must be noted that on older Webkit versions one MUST use an IP address and
1378 not a FQDN.
1379 This works as expected with Webkit 1.4.2.
1380 .Pp
1381 If using libsoup 2.42.2 or newer, one may use a socks proxy directly.
1382 For example:
1383 .Bd -literal -offset indent
1384 http_proxy = socks5://127.0.0.1:9050
1385 .Ed
1386 Otherwise, an intermediary tool, such as polipo or tsocks, must be used.
1387 .It Cm http_accept
1388 If set, the HTTP Accept header will be modified for each text/html request.
1389 If this setting is set multiple times, the Accept header will be changed
1390 in a round-robin order for every text/html request on a tab.
1391 Because this setting rotates through Accept headers on each text/html
1392 request, a single page may rotate through more than one Accept header
1393 if multiple text/html requests are made.
1394 .Pp
1395 Please be aware that not all websites report browser headers correctly.
1396 Most notably, EFF's panopticlick service also reports the HTTP
1397 Accept-Encoding headers on the same line as the Accept headers.
1398 If you are trying to find the headers of another browser to model that
1399 browser's fingerprint, it is recommended to not use panopticlick for
1400 this reason.
1401 .Pp
1402 Note that this setting only rewrites the Accept header for text/html
1403 requests.  Other requests will use WebKit's default  Accept header.
1404 .It Cm http_proxy_starts_enabled
1405 If set to 0, the http_proxy will be disabled at startup. The user can later
1406 enable the proxy with the
1407 .Cm proxy toggle
1408 command or keybinding.
1409 .It Cm icon_size
1410 Permits icon sizes to be changed if
1411 .Cm fancy_bar
1412 is enabled.
1413 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
1414 .It Cm include_config
1415 This must be a path to another configuration file.
1416 Configuration files are usually read from top to bottom, however, if
1417 this option is set,
1418 .Nm
1419 will begin reading the included file at this location and continue
1420 reading the rest of the configuration after the included file has
1421 finished being read.
1422 .Pp
1423 Any simple settings set before the include may
1424 be overridden by settings in the included file, and any simple
1425 settings set in the included file may be overridden later by settings
1426 after the include or at runtime using the
1427 .Cm :set
1428 command.
1429 However, database settings (for example,
1430 .Cm cookie_wl , js_wl , pl_wl ,
1431 and
1432 .Cm keybinding )
1433 are only ever added to the database, and so the order of an included
1434 configuration file is not pertinent to these database settings.
1435 .Pp
1436 This feature is likely best used as the last item in
1437 .Pa ~/.xombrero.conf .
1438 .It Cm js_auto_open_windows
1439 If enabled, javascripts will be allowed to automatically open windows
1440 based on the current
1441 .Cm browser_mode .
1442 If disabled, it will never be allowed.  The default setting is 1 (enabled).
1443 .It Cm js_wl
1444 This is a JavaScript whitelist item.
1445 See
1446 .Cm cookie_wl
1447 for semantics and more details.
1448 .It Cm max_connections
1449 The maximum number of connections that
1450 .Nm
1451 can open at once.
1452 .It Cm max_host_connections
1453 The maximum number of connections that
1454 .Nm
1455 can open at once to a given host.
1456 .It Cm mime_type
1457 Sets an action for a specific or default MIME type.
1458 For example, to download and view a pdf using kpdf set
1459 .Pa mime_type = application/pdf,kpdf .
1460 To set a default value use *, for example,
1461 .Pa mime_type = video/*,mplayer .
1462 Note that the action is only passed the URL and not all applications are
1463 capable of dealing with a URL and therefore one might have to create a wrapper
1464 script to download the content first.  Alternatively one can add the
1465 .Pa @
1466 in front of the MIME type to indicate "download first".
1467 For example,
1468 .Pa mime_type = @application/pdf,xpdf .
1469 When
1470 .Pa @
1471 is use the file will be downloaded to the
1472 .Pa download_dir
1473 before the MIME handler is called.
1474 .Pp
1475 The special binary name "donothing" may be used to ignore a MIME type
1476 without displaying any warnings from being unable to execute the
1477 binary.
1478 .It Cm oops_font
1479 Set the font used to display error messages.
1480 E.g.
1481 .Pa oops_font = monospace normal 9 .
1482 .It Cm pl_wl
1483 This is a plugin whitelist item.
1484 See
1485 .Cm cookie_wl
1486 for semantics and more details.
1487 .It Cm preload_strict_transport
1488 If enabled, a preloaded list of sites which set the HTTP Strict
1489 Transport Security header will be used to automatically set the
1490 .Cm force_https
1491 setting for these sites.
1492 This is used to prevent SSL stripping attacks when first visiting
1493 these sites, before they have been added to the strict-transport file.
1494 This list is comprised of domains chosen by the
1495 .Nm
1496 authors, as well as domains included in Chromium's preloaded HSTS
1497 list.
1498 Default is 1.
1499 .It Cm read_only_cookies
1500 Mark cookies file read-only and discard all cookies once the session is
1501 terminated.
1502 .It Cm refresh_interval
1503 Refresh interval while in the download manager.
1504 The default is 10.
1505 .It Cm referer
1506 Control how
1507 .Dq referer
1508 is handled in http-requests.
1509 .Bd -literal -offset indent
1510 always      - always send referer
1511 never       - never send referer
1512 same-domain - only send referer if it's
1513               for the same public suffix - this means that
1514               it's OK for subdomains to refer to each other
1515 same-fqdn   - only send referer if it's FQDN match
1516 .Ed
1517 Any other value that is also a valid URL will use this
1518 custom value as referer. (E.g. you could set it to http://no-referer.com)
1519 The default value is
1520 .Dq always .
1521 .It Cm resource_dir
1522 Directory that contains various
1523 .Nm
1524 resources such as icons.
1525 This is OS-specific and should be handled by the porter.
1526 .It Cm save_global_history
1527 If set the global history will be saved to
1528 .Pa ~/.xombrero/history
1529 when quitting
1530 and restored at startup.
1531 See the
1532 .Sx KEY BINDINGS
1533 section above for how the global history is accessed.
1534 Global history is not saved to disk by default.
1535 .It Cm save_rejected_cookies
1536 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
1537 All cookies are saved and unlike a cookie jar they are never replaced.
1538 Make sure there is enough disk space to enable this feature.
1539 .It Cm search_string
1540 Default search engine string.
1541 See the
1542 .Pa xombrero.conf
1543 file for details.
1544 .It Cm session_autosave
1545 Enable session auto-saving when changing state (e.g. adding or removing a tab).
1546 The session name is what is currently in use and is described in the
1547 .Cm session save
1548 and
1549 .Cm session open
1550 commands.
1551 .It Cm session_timeout
1552 This value is the time that is added in seconds to a session cookie.
1553 .It Cm show_tabs
1554 Enable or disable showing tabs.
1555 .It Cm show_url
1556 Enable or disable showing the url and toolbar.
1557 .It Cm show_scrollbars
1558 Enable or disable the showing of the horizontal and vertical scrollbars.
1559 Disabling this setting requires GTK3.
1560 .It Cm show_statusbar
1561 Enable or disable showing the status bar.
1562 .It Cm single_instance
1563 If set and
1564 .Cm enable_socket
1565 is enabled only one
1566 .Nm
1567 will be permitted to run.
1568 If there is a URL specified it will be opened in a new tab in the already
1569 running
1570 .Nm
1571 session.
1572 .It Cm spell_check_languages
1573 The languages to be used for spell checking, separated by commas. For example,
1574 en_US.
1575 .It Cm ssl_ca_file
1576 If set to a valid PEM file
1577 all server certificates will be validated against it.
1578 The URL bar will be colored green (or blue when saved) when the certificate is
1579 trusted and yellow when untrusted.
1580 .Pp
1581 If
1582 .Cm ssl_ca_file
1583 is not set, the URL bar will be colored red if the certificate has not
1584 been saved, or blue if it has been saved.
1585 .Pp
1586 WebKit only supports a single PEM file.
1587 Many OS' or distributions have many PEM files.
1588 One can simply concatenate all separate files into one large one.
1589 E.g.
1590 .Cm for i in `ls`; do cat $i >> cert.pem; done
1591 and use the resulting cert.pem file as the input to
1592 .Cm ssl_ca_file .
1593 It is advisable to periodically recreate the cert.pem file.
1594 .It Cm ssl_strict_certs
1595 If this value is set connections to untrusted sites will be aborted.
1596 This value is only used if
1597 .Cm ssl_ca_file
1598 is set.
1599 .It Cm statusbar_elems
1600 Define the components of the status bar. The possible components are:
1601 .Bd -literal -offset indent
1602 | - separator
1603 P - page progress percent
1604 p - proxy enabled/disabled
1605 B - buffer command
1606 Z - page zoom level
1607 T - current tab number
1608 .Ed
1609 The default is "BP".
1610 These components show nothing if there is nothing worth showing, like
1611 zoom amount 100%.
1612 .It Cm statusbar_font
1613 Set the status bar font.
1614 E.g.
1615 .Pa statusbar_font = monospace normal 9 .
1616 .It Cm statusbar_style
1617 Set the status bar style to either
1618 .Cm url
1619 - display the current url, or
1620 .Cm title
1621 - display the page title. The default is
1622 .Cm url .
1623 .It Cm tab_style
1624 Set the tab style to either
1625 .Cm normal
1626 - the default gtk notebook tabs, or
1627 .Cm compact
1628 for an alternative.
1629 You can switch the tab style with the
1630 .Pa tabnextstyle
1631 command.
1632 .It Cm tabbar_font
1633 Set the compact tab bar font.
1634 E.g.
1635 .Pa tabbar_font = monospace normal 9 .
1636 .It Cm tabless
1637 Disable tabs, and open new windows instead.
1638 Note that this feature does not disable the display of tabs.
1639 Change your
1640 .Cm show_tabs
1641 setting also if you wish to disable the display of tabs.
1642 Default is 0.
1643 .It Cm url_regex
1644 This is the regular expression that is used to match what constitutes a valid
1645 URL when using
1646 .Pa guess_search .
1647 .It Cm user_agent
1648 Set to override the default
1649 .Nm
1650 user-agent string. May be specified several times for switching between
1651 user-agents.
1652 .It Cm userstyle
1653 Set the stylesheet to be used as a default for the
1654 .Cm userstyle
1655 and
1656 .Cm userstyle_global
1657 commands when no extra parameters are given.
1658 The default is a low-contrast stylesheet.
1659 .It Cm userstyle_global
1660 When enabled new tabs will automatically be displayed using the custom
1661 stylesheet specified by the
1662 .Cm userstyle
1663 setting.
1664 .It Cm warn_cert_changes
1665 When enabled all SSL certificates from HTTPS websites will be
1666 cached in the
1667 .Cm ~/.xombrero/certs_cache/
1668 directory.
1669 On each page load, if the remote certificate differs from the cached
1670 local version, a warning page with options of what to do next will be displayed
1671 instead of the requested page.
1672 This feature may be used in addition to the coloring of the URL bar and
1673 can be used to help prevent against man-in-the-middle attacks, even if
1674 the new remote certificate is signed by a trusted certificate
1675 authority in
1676 .Cm ssl_ca_file .
1677 Default is 0.
1678 .It Cm window_height
1679 Set the default height of the browser window.
1680 .It Cm window_width
1681 Set the default width of the browser window.
1682 .It Cm window_maximize
1683 Maximize the browser window at startup.
1684 .It Cm work_dir
1685 Set the work directory where all
1686 .Nm
1687 scratch files are stored.
1688 Default is
1689 .Cm ~/.xombrero .
1690 .El
1691 .Sh HISTORY
1692 .Nm
1693 was inspired by vimprobable2 and the bloat in other
1694 .Ux
1695 web browsers.
1696 .Sh AUTHORS
1697 .An -nosplit
1698 .Nm
1699 was written by
1700 .An Marco Peereboom Aq marco@peereboom.us ,
1701 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
1702 .An Edd Barrett Aq vext01@gmail.com ,
1703 .An Todd T. Fries Aq todd@fries.net ,
1704 .An Raphael Graf Aq r@undefined.ch ,
1705 .An Michal Mazurek Aq akfaew@jasminek.net ,
1706 and
1707 .An Josh Rickmar Aq jrick@devio.us .