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 Java Script 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 typing Esc.
 442 The commands and their descriptions are listed below.
 443 .Bl -tag -width Ds -offset indent
 444 .It Cm about , version
 445 Show the "About" page.
 446 .It Cm buffers , ls , tabs
 447 Displays the currently open tabs and lets the user switch tab by typing
 448 the tab number or using the mouse.
 449 .It Cm ca
 450 Display CA certificates.
 451 .It Cm cert , cert show
 452 Download and display certificates of domain on 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 <encoding>
 493 If
 494 .Cm <encoding>
 495 is set the tab's encoding will be set to
 496 .Cm <encoding>
 497 and
 498 .Nm
 499 reloads the tab.
 500 If
 501 .Cm <encoding>
 502 is not set
 503 .Nm
 504 will display the current tab encoding.
 505 .It Cm editsrc
 506 Opens the source for the current tab in the editor specified by the
 507 setting
 508 .Cm external_editor
 509 and then checks for changes to the file opened. If it is changed, the
 510 page will be updated.
 511 .It Cm editelement
 512 If a text-element is currently active (<input> or <textarea>), it's
 513 contents will be opened in the same fashion as for the command
 514 .Cm editsrc
 515 above
 516 .It Cm fav
 517 Show favorites.
 518 .It Cm favadd
 519 Add the current page to favorites.
 520 .It Cm favedit
 521 Shows favorites list and links to remove entries.
 522 .It Cm fullscreen , f
 523 Toggle hiding tabs and url entry toolbar.
 524 .It Cm h , hist , history
 525 Show global history.
 526 .It Cm help
 527 Show help page.
 528 .It Cm home
 529 Go to home URL.
 530 .It Cm https
 531 The
 532 .Cm https
 533 command is used to manitulate the items in the HTTPS force list.
 534 Used by itself it expands to
 535 .Cm https show all .
 536 .It Cm https save, save fqdn
 537 Saves the FQDN to the persistent force HTTPS list.
 538 For example,
 539 the www.peereboom.us domain would result in saving www.peereboom.us.
 540 .It Cm https save domain
 541 Saves the top level domain name to the persistent whitelist.
 542 For example,
 543 the www.peereboom.us domain would result in saving .peereboom.us.
 544 .It Cm https show all
 545 Show all persistent ans session entries in the HTTPS force list.
 546 .It Cm https show persistent
 547 Shows all persistent entries in the HTTPS force list.
 548 .It Cm https show session
 549 Shows all session entries in the HTTPS force list.
 550 .It Cm https toggle, https toggle fqdn
 551 Toggle this FQDN in the HTTPS force list.
 552 .It Cm https toggle domain
 553 Toggle the top level domain in the HTTPS force list.
 554 .It Cm js
 555 The
 556 .Cm js
 557 command is used to manipulate the Java Script whitelist.
 558 Used by itself it expands to
 559 .Cm js show all .
 560 .It Cm js save, save fqdn
 561 Saves the FQDN to the persistent whitelist.
 562 For example,
 563 the www.peereboom.us domain would result in saving www.peereboom.us.
 564 .It Cm js save domain
 565 Saves the top level domain name to the persistent whitelist.
 566 For example,
 567 the www.peereboom.us domain would result in saving .peereboom.us.
 568 .Pp
 569 This action enables Java Script if it is currently disabled for this entry.
 570 .It Cm js show all
 571 Shows all persistent and session entries in the JS whitelist.
 572 .It Cm js show persistent
 573 Shows all persistent entries in the JS whitelist.
 574 .It Cm js show session
 575 Shows all session entries in the JS whitelist.
 576 .It Cm js toggle, js toggle fqdn
 577 Toggle Java Script execution for the current FQDN.
 578 .It Cm js toggle domain
 579 Toggle Java Script execution for the current top level domain.
 580 .It Cm loadimages
 581 If auto_load_images is disabled, load all images for current site.
 582 .It Cm open , op , o URL
 583 Open URL.
 584 .It Cm plugin
 585 The
 586 .Cm plugin
 587 command is used to manipulate the plugin whitelist.
 588 Used by itself it expands to
 589 .Cm plugin show all .
 590 .It Cm plugin save, save fqdn
 591 Saves the FQDN to the persistent whitelist.
 592 For example,
 593 the www.peereboom.us domain would result in saving www.peereboom.us.
 594 .It Cm plugin save domain
 595 Saves the top level domain name to the persistent whitelist.
 596 For example,
 597 the www.peereboom.us domain would result in saving .peereboom.us.
 598 .Pp
 599 This action enables plugins if they are currently disabled for this entry.
 600 .It Cm plugin show all
 601 Shows all persistent and session entries in the plugin whitelist.
 602 .It Cm plugin show persistent
 603 Shows all persistent entries in the plugin whitelist.
 604 .It Cm plugin show session
 605 Shows all session entries in the plugin whitelist.
 606 .It Cm plugin toggle, plugin toggle fqdn
 607 Toggle plugin execution for the current FQDN.
 608 .It Cm plugin toggle domain
 609 Toggle plugin execution for the current top level domain.
 610 .It Cm print
 611 Print page.
 612 .It Cm proxy
 613 The
 614 .Cm proxy
 615 command is used to manipulate the currently set proxy.
 616 Used by itself it expands to
 617 .Cm proxy show .
 618 .It Cm proxy show
 619 Displays the current
 620 .Cm http_proxy
 621 setting.
 622 .It Cm proxy toggle
 623 Enables or disables the proxy for
 624 .Nm .
 625 Note that
 626 .Cm http_proxy
 627 must be set before it can be toggled.
 628 .It Cm qa , qall , quitall
 629 Quit
 630 .Nm .
 631 .It Cm quit , q
 632 Close current tab and quit
 633 .Nm
 634 if it is the last tab.
 635 .It Cm restart
 636 Restart
 637 .Nm
 638 and reload all current tabs.
 639 .It Cm run_script [path_to_script]
 640 Runs the script path_to_script with the current uri as the argument.
 641 If path_to_script is not provided, the value of default_script is used
 642 instead.
 643 .It Cm script [filename]
 644 Run an external JavaScript script file in the current tab context.
 645 .It Cm session , Cm session show
 646 Display the current session name.
 647 By default the session name is main_session.
 648 To create a new session use the
 649 .Cm session save
 650 command.
 651 A session is defined as the lifetime of the browser application.
 652 .It Cm session delete <session_name>
 653 Delete session session_name from persistent storage.
 654 If session_name is the current session then the session will revert to
 655 main_session.
 656 .It Cm session open <session_name>
 657 Open session_name and close all currently open tabs.
 658 Going forward this session is named session_name.
 659 .It Cm session save <session_name>
 660 Save current tabs to session_name session.
 661 This will close the current session and going forward this session is named
 662 session_name.
 663 .It Cm set
 664 The set command is used to inspect, clear or change runtime options.
 665 There are 3 methods to use
 666 .Cm :set .
 667 When used by itself as
 668 .Cm :set
 669 the command displays all options as currently set.
 670 .Pp
 671 To set a value use
 672 .Cm :set option=value .
 673 For example,
 674 .Cm :set http_proxy=http://127.0.0.1:8080 .
 675 .Pp
 676 To clear a value use
 677 .Cm :set option= .
 678 For example,
 679 .Cm :set http_proxy= .
 680 .Pp
 681 Note, not all options can be set at runtime.
 682 .It Cm stats
 683 Show blocked cookie statistics.
 684 These statistics vary based on settings and are not persistent.
 685 .It Cm statustoggle , statust
 686 Toggle status bar.
 687 .It Cm stop
 688 Stop loading the current web page.
 689 .It Cm tabclose
 690 Close current tab.
 691 .It Cm tabhide
 692 Hide tabs.
 693 .It Cm tabnew , tabedit [URL]
 694 Create new tab and optionally open provided URL.
 695 .It Cm tabnext
 696 Go to the next tab.
 697 .It Cm tabonly
 698 Close all tabs except the currently focused one.
 699 .It Cm tabprevious
 700 Go to the previous tab.
 701 .It Cm tabshow
 702 Show tabs in GUI.
 703 .It Cm toplevel , toplevel toggle
 704 Toggle the top level domain name cookie and JS session whitelist.
 705 This is to enable/disable short lived full site functionality without
 706 permanently adding the top level domain to the persistent whitelist.
 707 .It Cm urlhide , urlh
 708 Hide url entry and tool bar.
 709 .It Cm urlshow , urls
 710 Show url entry and tool bar.
 711 .It Cm userstyle <stylesheet>
 712 Toggle the current tab between using a custom stylesheet and the
 713 page's default CSS.
 714 If there is no stylesheet argument to this command, the stylesheet
 715 specified by the
 716 .Cm userstyle
 717 setting will be used instead.
 718 This
 719 .Cm userstyle
 720 setting is set by default to a low-contrast color scheme.
 721 If a stylesheet is specified, the current tab will be toggled with
 722 this stylesheet instead.
 723 .Pp
 724 If the
 725 .Cm userstyle
 726 setting is left unchanged, this command without any arguments will
 727 toggle between the default page's CSS and the low-contrast color
 728 scheme.
 729 .Pp
 730 Additional stylesheets may be used in addition to the low-contrast
 731 color scheme by specifying additonal keybindings.  For example,
 732 .Pp
 733 .D1 keybinding = userstyle ~/style.css,v
 734 .D1 keybinding = userstyle_global ~/style.css,V
 735 .Pp
 736 will map toggling between ~/style.css to the v and V keys while
 737 keeping the low-contrast feature mapped to the s and S keys.
 738 .It Cm userstyle_global <stylesheet>
 739 Same as
 740 .Cm userstyle
 741 but the change affects all open tabs, and newly created tabs will use
 742 this style.
 743 .It Cm w
 744 Save open tabs to current session.
 745 The tabs will be restored next time the session is opened.
 746 See the session command for additional details.
 747 .It Cm wq
 748 Save open tabs and quit.
 749 The tabs will be restored next time
 750 .Nm
 751 the session is opened.
 752 See the session command for additional details.
 753 .El
 754 .Sh BUFFER COMMANDS
 755 In addition to shortcuts and commands
 756 .Nm
 757 provides buffer commands. Buffer commands are short, multi character
 758 vi-like commands, often requiring an argument. Partial buffer commands
 759 are
 760 displayed in the buffer command statusbar element (see
 761 .Cm statusbar_elems ) .
 762 Pressing Esc or switching to another tab cancels a partially entered
 763 buffer command. In the following list
 764 .Cm arg
 765 denotes the argument a buffer command accepts. Buffer commands are
 766 defined as extended regular experssions.
 767 Note that if a character is used as a shortcut it will not be interpreted
 768 as the beginning of a buffer command. This is the case with
 769 .Cm 0 .
 770 .Pp
 771 .Bl -tag -width "['][a-zA-Z0-9]XXX" -offset indent -compact
 772 .It Cm gg
 773 go to the top of the page
 774 .It Cm gG
 775 go to the bottom of the page
 776 .It Cm [0-9]+%
 777 go to the
 778 .Cm arg
 779 percent of the page
 780 .It Cm zz
 781 go to 50% of the page
 782 .It Cm [0-9]*gu
 783 go
 784 .Cm arg
 785 levels up. If
 786 .Cm arg
 787 is missing, 1 is assumed. Going a
 788 level up means going to a URI obtained from the current one by removing
 789 the last slash ('/') character and everything that follows it
 790 .It Cm gU
 791 go to the root level, i.e. going up as many levels as possible.
 792 .It Cm gh
 793 open the home page in the current tab
 794 .It Cm m[a-zA-Z0-9]
 795 set a mark denoted by
 796 .Cm arg
 797 at the current page position. These marks behave like those in vi or
 798 less.
 799 .It Cm ['][a-zA-Z0-9']
 800 go to the position where mark
 801 .Cm arg
 802 was set. The special mark "'" points to the previous page position, after a
 803 "gg", "gG", "zz", "%" or "'" buffer command.
 804 .It Cm M[a-zA-Z0-9]
 805 set the current uri as quickmark
 806 .Cm arg
 807 .It Cm go[a-zA-Z0-9]
 808 open the uri marked as quickmark
 809 .Cm arg
 810 in the current tab
 811 .It Cm gn[a-zA-Z0-9]
 812 open the uri marked as quickmark
 813 .Cm arg
 814 in a new tab
 815 .It Cm [0-9]+t
 816 activate tab number
 817 .It Cm g0
 818 go to first tab
 819 .It Cm g$
 820 go to last tab
 821 .It Cm [0-9]*gt
 822 go to the
 823 .Cm arg
 824 next tab
 825 .It Cm [0-9]*gT
 826 go to the
 827 .Cm arg
 828 previous tab
 829 .Cm arg
 830 .It Cm ZZ
 831 quit
 832 .Nm
 833 .It Cm ZR
 834 restart
 835 .Nm
 836 .It Cm zi
 837 zoom in by 4%
 838 .It Cm zo
 839 zoom out by 4%
 840 .It Cm z0
 841 set zoom level to 100%
 842 .It Cm [0-9]+Z
 843 set zoom level to
 844 .Cm arg
 845 %
 846 .El
 847 .Sh QUICKMARKS
 848 Quickmarks are like bookmarks, except they are refered to by a single
 849 character (a letter or a digit), instead of a longer name. See the
 850 .Cm M[a-zA-Z0-9] ,
 851 .Cm go[a-zA-Z0-9]
 852 and
 853 .Cm gn[a-zA-Z0-9]
 854 buffer commands for usage. Quickmarks are stored in
 855 .Pa ~/.xombrero/quickmarks
 856 and are saved automatically after each
 857 .Cm M[a-zA-Z0-9]
 858 buffer command.
 859 .Sh ABOUT SCREENS
 860 The about screens are internally generated web pages by
 861 .Nm
 862 for user interaction.
 863 These are entered in the address bar and the format is
 864 .Cm about:screen
 865 where screen is the desired screen to display.
 866 For example about:favorites.
 867 Any about screen can be used as the home page as specified by
 868 .Cm home
 869 in the configuration file.
 870 .Pp
 871 .Bl -tag -width "downloadsXXX" -offset indent -compact
 872 .It Cm about
 873 show the about screen
 874 .It Cm blank
 875 show a blank screen
 876 .It Cm cookiewl
 877 show the cookie whitelist screen
 878 .It Cm cookiejar
 879 show the cookiejar screen
 880 .It Cm downloads
 881 show the downloads screen
 882 .It Cm favorites
 883 show the favorites screen
 884 .It Cm help
 885 show the help web page
 886 .It Cm history
 887 show the history screen
 888 .It Cm jswl
 889 show the Java Script whitelist screen
 890 .It Cm set
 891 show the settings screen
 892 .It Cm stats
 893 show the statistics screen
 894 .El
 895 .Sh WHITELISTS
 896 This section describes advanced usage settings.
 897 Most users should use
 898 .Cm browser_mode
 899 instead to setup
 900 .Nm
 901 and skip over this section.
 902 .Pp
 903 .Nm
 904 has a number of whitelists to control blocking cookies and Java Script
 905 execution for FQDNs or domains.
 906 When properly enabled these whitelists require either the FQDN or top level
 907 domain to exist in the whitelists in order to allow cookies to be stored or
 908 Java Script to execute.
 909 Both Java Script and cookies have two whitelists associated with them.
 910 The whitelists are called session and persistent.
 911 Items in the session whitelists are only allowed for the lifetime of the
 912 .Nm
 913 instance.
 914 Items in the persistent whitelists are stored on disk and are restored
 915 upon restarting.
 916 .Pp
 917 Setting up the whitelists is a little tricky due to intricacies of WebKit.
 918 In fact the semantics are different for cookies and Java Script.
 919 .Pp
 920 Cookie whitelist requires the following configuration to be set:
 921 .Pp
 922 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
 923 .It Cm cookies_enabled
 924 This is a WebKit setting and must be set to
 925 .Pa 1
 926 (ENABLED)
 927 in order to be able to use a
 928 cookie whitelist.
 929 .It Cm enable_cookie_whitelist
 930 This needs to be set to
 931 .Pa 1
 932 to enable the cookie whitelist functionality.
 933 .It Cm cookie_wl
 934 These entries in the configuration file are the actual domains names in the
 935 cookie whitelist.
 936 .El
 937 .Pp
 938 Java Script whitelist requires the following configuration to be set:
 939 .Pp
 940 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
 941 .It Cm enable_scripts
 942 This is a WebKit setting and must be set to
 943 .Pa 0
 944 (DISABLED)
 945 in order to be able to use a
 946 Java Script whitelist.
 947 .It Cm enable_js_whitelist
 948 This needs to be set to
 949 .Pa 1
 950 to enable the Java Script whitelist functionality.
 951 .It Cm js_wl
 952 These entries in the configuration file are the actual domains names in the
 953 Java Script whitelist.
 954 .El
 955 .Pp
 956 Plugin whitelist requires the following configuration to be set:
 957 .Pp
 958 .Bl -tag -width "enable_plugin_whitelistXXX" -offset indent -compact
 959 .It Cm enable_plugins
 960 This is a WebKit setting and must be set to
 961 .Pa 1
 962 (ENABLED)
 963 in order to be able to use a
 964 plugin whitelist.
 965 .It Cm enable_plugin_whitelist
 966 This needs to be set to
 967 .Pa 1
 968 to enable the plugin whitelist functionality.
 969 .It Cm pl_wl
 970 These entries in the configuration file are the actual domains names in the
 971 plugin whitelist.
 972 .El
 973 .Pp
 974 See the
 975 .Pa FILES
 976 section for additional configuration file entries and details
 977 that alter runtime behavior.
 978 .Sh FILES
 979 .Bl -tag -width "/etc/xombrero.confXXX" -compact
 980 .It Pa ~/.xombrero.conf
 981 .Nm
 982 user specific settings.
 983 .It Pa ~/.xombrero
 984 .Nm
 985 scratch directory.
 986 .El
 987 .Pp
 988 .Nm
 989 tries to open the user specific file,
 990 .Pa ~/.xombrero.conf .
 991 If that file is unavailable,
 992 it then uses built-in defaults.
 993 Any settings saved at runtime will be saved to the file
 994 .Pa ~/.xombrero/runtime
 995 and will be loaded as well.
 996 .Pp
 997 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
 998 For example:
 999 .Pp
1000 .Dl http_proxy = http://127.0.0.1:8080
1001 .Pp
1002 Enabling or disabling an option is done by using 1 or 0 respectively.
1003 .Pp
1004 The file supports the following keywords:
1005 .Pp
1006 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
1007 .It Cm alias
1008 Defines an alias for a given URL, so that the URL is loaded when the alias is
1009 entered in the address bar.
1010 If the aliased URL includes a %s format specifier, then any argument given after
1011 the alias on the address bar is substituted.
1012 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
1013 then the URL http://www.google.com/search?q=foo is loaded when navigating to
1014 "g foo".
1015 .It Cm allow_insecure_content
1016 If set, all content referenced by a page will be loaded.
1017 If unset, encrypted pages will refuse to load content that is linked
1018 from an insecure location.
1019 .It Cm allow_insecure_scripts
1020 If set, all scripts referenced by a page will be loaded and run using
1021 the current javascript policy.
1022 If unset, encrypted pages will refuse to run scripts that are linked
1023 from an insecure location.
1024 .It Cm allow_volatile_cookies
1025 If set cookies are stored in the session cache but will be discarded once
1026 .Nm
1027 exits.
1028 Unfortunately enabling this does allow for some limited tracking on the web.
1029 .It Cm anonymize_headers
1030 If set, HTTP headers taken from the
1031 .Lk https://www.bitrig.org/ "Bitrig website"
1032 will be used to feed additional values to the
1033 .Nm xombrero
1034 HTTP header settings.
1035 Currently only the User-Agent and Http-Accept headers are modified,
1036 corresponding to the
1037 .Cm user_agent
1038 and
1039 .Cm http_accept
1040 settings, respectively.
1041 These headers are set after any header settings are read in from your
1042 .Cm ~/.xombrero.conf .
1043 Default is 0.
1044 .It Cm append_next
1045 When set a new tab is appended after the current tab instead of being appended
1046 as the last tab.
1047 .It Cm auto_load_images
1048 If disabled, images will not be loaded automatically.
1049 .It Cm autofocus_onload
1050 When set a tab that is loaded will attempt to autofocus the default input
1051 entry.
1052 This is only done for tabs that are currently visible.
1053 .It Cm browser_mode
1054 The
1055 .Nm
1056 browser has 3 default operating modes:
1057 .Pa normal
1058 (the default),
1059 .Pa whitelist
1060 and
1061 .Pa kiosk .
1062 In the
1063 .Pa normal
1064 mode the browser allows all cookies, plugins and Java Script as any other
1065 browser would.
1066 This means that all cookies are saved to persistent storage and that all
1067 Java Script and plugins run.
1068 .Pp
1069 On the other hand, using the
1070 .Pa whitelist
1071 mode enables whitelists.
1072 This requires the user to add all the required
1073 .Pa cookie_wl ,
1074 .Pa js_wl
1075 and
1076 .Pa pl_wl
1077 items.
1078 If a domain does not appear in the whitelists
1079 .Nm
1080 disallows cookies, Java Script and plugin execution.
1081 If insecure web content or scripts are referenced by a secure website,
1082 they will be blocked from loading or running.
1083 .Pp
1084 In
1085 .Pa kiosk
1086 mode the browse works just like
1087 .Pa normal
1088 mode however the toolbar only has the backward, forward and home button.
1089 .Pp
1090 This setting must be the first entry in
1091 .Pa ~/.xombrero.conf
1092 because it sets advanced settings that can be overridden later in the file.
1093 See the default config file for more details.
1094 .It Cm cmd_alias
1095 This setting is used to define an alias for a command.
1096 The syntax of this setting is
1097 .Pa cmd_alias = alias,cmd .
1098 For example, if you wanted to set an alias for the
1099 .Pa tabnew
1100 command to
1101 .Pa tn ,
1102 add the line
1103 .Pa cmd_alias = tn,tabnew
1104 to your
1105 .Pa ~/.xombrero.conf .
1106 This setting may not begin with a number.
1107 .It Cm cmd_font
1108 Set the command prompt font.
1109 E.g.
1110 .Pa cmd_font = monospace normal 9 .
1111 .It Cm color_visited_uris
1112 When enabled (the default)
1113 .Nm
1114 will color visited links. This is done while the web page loads using
1115 JavaScript, rather than WebKit's (broken, see bug #51747) built-in
1116 facility for coloring visited links. The JavaScript approach is
1117 (probably) slower and is not consistent across tabs (unless the tabs are
1118 reloaded), but has the advantage of not leaking history data to web
1119 pages (see http://wtikay.com/docs/details.html).
1120 .It Cm cookie_policy
1121 This field delineates the cookie policy.
1122 Possible values are: no3rdparty, reject 3rd party cookies.
1123 accept, accept all cookies.
1124 reject, reject all cookies.
1125 .It Cm cookie_wl
1126 This is a cookie whitelist item.
1127 Use multiple times to add multiple entries.
1128 Valid entries are for example *.moo.com and the equivalent .moo.com.
1129 This matches both moo.com, as well as all subdomains.
1130 A fully qualified host is also valid and is for example www.moo.com or
1131 moo.com.
1132 Fully qualified hosts do not modify whitelist settings for any
1133 subdomains.
1134 .Pp
1135 Unix extended regular expressions may also be used to match any set of
1136 FQDNs.
1137 Regular expressions must begin with the prefix "re:".
1138 As an example, the regular expression equivalent to moo.com would be
1139 .Pa ^moo\.com$ ,
1140 and the equivalent to .moo.com would be
1141 .Pa ^(.*\.)*moo\.com$ .
1142 If using regular expressions for whitelist items, be careful to not
1143 accidentally match other domains;
1144 you will almost always want to add the ^ and $ characters to the
1145 beginning and end of the regex so that, for example,
1146 .Pa moo\.com
1147 would not match not-moo.com.
1148 .It Cm cookies_enabled
1149 Enable cookies.
1150 .It Cm ctrl_click_focus
1151 Give focus in newly created tab instead of opening it in the background.
1152 .It Cm custom_uri
1153 This setting provides the ability to run custom executables for
1154 special URIs.
1155 The syntax for this setting is
1156 .Pa custom_uri\ =\ protocol,command .
1157 The URI is passed as a single argument to
1158 .Pa command
1159 to be parsed and executed.
1160 .Pp
1161 For example, to add the ability to use custom
1162 .Pa mailto
1163 URIs, add the setting
1164 .Pa custom_uri = mailto,command
1165 where
1166 .Pa command
1167 is a program that will parse the
1168 .Pa mailto
1169 URI and open your mail client.
1170 .It Cm default_script
1171 Path to the script used as the default value for the run_script
1172 command.
1173 .It Cm default_zoom_level
1174 Set the default browsing zoom level.
1175 .It Cm do_not_track
1176 Sets the HTTP Do Not Track header to tell sites that you wish to be
1177 opted-out of 3rd-party tracking for the use of behavioral advertising.
1178 Not all sites currently support this header, and this is only a
1179 suggestion of a user preference.
1180 Sites may still perform 3rd-party tracking even when this feature is
1181 enabled.
1182 .It Cm download_dir
1183 Locations where files are downloaded to.
1184 This directory must exist and
1185 .Nm
1186 validates that during startup.
1187 .It Cm download_mode
1188 Controls how downloads are handled.
1189 Possible values are:
1190 .Bd -literal -offset indent
1191 start - automatically start download.
1192 ask   - ask user for confirmation.
1193 add   - add to downloadmanager, but
1194         do not start.
1195 .Ed
1196 The default is "start".
1197 .It Cm download_notifications
1198 When enabled a message is shown when downloads are finished.
1199 Default is 0.
1200 .It Cm enable_autoscroll
1201 When enabled clicking MB3 will spawn the autoscroll ball, scrolling can
1202 then proceed by dragging the mouse away from the ball.
1203 .It Cm enable_cookie_whitelist
1204 When enabled all cookies must be in the whitelist or they are rejected.
1205 Additionally whitelisted cookies also enable HTML5 local storage for the
1206 domain.
1207 .It Cm enable_favicon_entry
1208 When enabled (the default)
1209 .Nm
1210 displays the favicon of the web page at the URI entry. This setting
1211 affects both
1212 .Cm normal
1213 and
1214 .Cm compact
1215 tabs.
1216 .It Cm enable_favicon_tabs
1217 When enabled (disabled by default)
1218 .Nm
1219 displays favicons at each tab. This setting only affects
1220 .Cm compact
1221 tabs.
1222 .It Cm enable_js_autorun
1223 Enables support for autorunning JavaScript after page loads.  When
1224 enabled,
1225 .Pa ~/.xombrero/js/
1226 will be searched for
1227 .Pa default.js
1228 and
1229 .Pa host.domain.js .
1230 If
1231 .Pa host.domain.js
1232 does not exist,
1233 .Pa domain.js
1234 will be tried instead.  The content of the both default and
1235 host/domain files are read and executed on each page load.
1236 Default is 1.
1237 .Pp
1238 As an example, if you add the line
1239 .Pa alert("Hello, world");
1240 to your
1241 .Pa default.js ,
1242 a pop-up displaying "Hello, world" will be shown on every page reload.
1243 While not useful, any javascript can be run through this mechanism,
1244 making it useful for global or site-specific modifications.
1245 .It Cm enable_js_whitelist
1246 When enabled all domains must be in the js whitelist in order to run Java
1247 Script.
1248 NOTE: Make sure
1249 .Cm enable_scripts
1250 is set to 0.
1251 .It Cm enable_plugin_whitelist
1252 When enabled all domains must be in the plugin whitelist in order to run
1253 plugins.
1254 NOTE: Make sure
1255 .Cm enable_plugins
1256 is set to 0.
1257 .It Cm enable_plugins
1258 Enable external plugins such as Flash and Java.
1259 .It Cm enable_strict_transport
1260 Enable support for the Strict-Transport-Security HTTP-header.
1261 When enabled, sites that set this flag will only be visited via HTTPS.
1262 Default value is 1
1263 .It Cm enable_scripts
1264 Enable Java Script.
1265 .It Cm enable_socket
1266 When enabled the first instance of
1267 .Nm
1268 will create a socket in the
1269 .Pa ~/.xombrero
1270 directory.
1271 Using the -n url option on subsequent
1272 .Nm
1273 invocations will cause the specified URL to be loaded in a new tab.
1274 Only a user with identical UID and GID can use this option.
1275 .It Cm enable_localstorage
1276 Enable html5 Local Storage.
1277 .It Cm enable_spell_checking
1278 Enables spell checking. Preferred languages can be set using
1279 .Cm spell_check_languages
1280 option.
1281 .It Cm encoding
1282 Set the default encoding.
1283 E.g.
1284 .Pa encoding = ISO-8859-1 .
1285 .It Cm external_editor
1286 Set which editor to use for external editing.
1287 the string <file> will be replaced by the current filename.
1288 E.g.
1289 .Pa external_editor = gvim -f <file>
1290 Note!
1291 .Cm xombrero
1292 relies on the editor
1293 .Pa not forking
1294 into the background.
1295 .It Cm fancy_bar
1296 Enables a backward, forward, and stop button to the toolbar.
1297 Additionally if
1298 .Cm search_string
1299 is set it'll enable an entry box for searches.
1300 .It Cm force_https
1301 This setting is used to define the domains of sites that should be
1302 only accessed over the HTTPS scheme.
1303 Any requests to these domains over HTTP will be rewritten to use HTTPS
1304 instead.
1305 See
1306 .Cm cookie_wl
1307 for semantics.
1308 .It Cm gnutls_priority_string
1309 If set, this string sets the G_TLS_GNUTLS_PRIORITY environmental
1310 variable to define the GnuTLS priority string that is used when
1311 initializing the GnuTLS session.
1312 This may be used to change the supported TLS/SSL versions and the
1313 ciphers that are used when making HTTPS connections.
1314 .Pp
1315 Full details on how to modify this setting may be found in the GnuTLS
1316 documentation, Section 8.9: Priority Strings.
1317 For example, to disable the 128-bit RC4 cipher, change this setting to
1318 .Pa NORMAL:!ARCFOUR-128 .
1319 .Pp
1320 If your glib-networking package is older than version 2.33.10, or if
1321 the G_TLS_GNUTLS_PRIORITY environmental variable is already set, this
1322 setting has no effect.
1323 .It Cm guess_search
1324 When enabled
1325 .Nm
1326 will try to guess if the string you entered, in the URI entry widget or
1327 the command widget, is term you want to search for using search_string
1328 (see above).
1329 If the string does not contain a dot nor a slash, is not a
1330 path to a local file and does not resolves to an IP then it is assumed
1331 to be a search term.
1332 .It Cm gui_mode
1333 To simplify configuring
1334 .Nm
1335 allows you pick between two GUI modes:
1336 .Pa classic
1337 (the default) and
1338 .Pa minimal .
1339 In the
1340 .Pa classic
1341 mode the GUI looks similar to that of most mainstream browsers. While in
1342 .Pa minimal
1343 mode the GUI looks more vi-like. One can get a GUI between the two by
1344 tweaking the low-level GUI settings found under the advanced GUI setting
1345 section in the configuration file.
1346 .It Cm history_autosave
1347 When enabled
1348 .Nm
1349 will save all command and search history.
1350 Upon restarting
1351 .Nm
1352 the saved command and search history will be restored.
1353 .It Cm home
1354 Homepage in URL format.
1355 .It Cm http_proxy
1356 Proxy server in URL format.
1357 .Nm
1358 overrides
1359 .Cm http_proxy
1360 if it is specified as an environment variable.
1361 It must be noted that on older webkit versions one MUST use an IP address and
1362 not a FQDN.
1363 This works as expected with webkit 1.4.2.
1364 .Pp
1365 If one desires to use a socks proxy then an intermediary tool must be used.
1366 It has been reported that tsocks and polipo work with
1367 .Nm .
1368 .It Cm http_accept
1369 If set, the HTTP Accept header will be modified for each text/html request.
1370 If this setting is set multiple times, the Accept header will be changed
1371 in a round-robin order for every text/html request on a tab.
1372 Because this setting rotates through Accept headers on each text/html
1373 request, a single page may rotate through more than one Accept header
1374 if multiple text/html requests are made.
1375 .Pp
1376 Please be aware that not all websites report browser headers correctly.
1377 Most notably, EFF's panopticlick service also reports the HTTP
1378 Accept-Encoding headers on the same line as the Accept headers.
1379 If you are trying to find the headers of another browser to model that
1380 browser's fingerprint, it is recommended to not use panopticlick for
1381 this reason.
1382 .Pp
1383 Note that this setting only rewrites the Accept header for text/html
1384 requests.  Other requests will use WebKit's default  Accept header.
1385 .It Cm http_proxy_starts_enabled
1386 If set to 0, the http_proxy will be disabled at startup. The user can later
1387 enable the proxy with the
1388 .Cm proxy toggle
1389 command or keybinding.
1390 .It Cm icon_size
1391 Permits icon sizes to be changed if
1392 .Cm fancy_bar
1393 is enabled.
1394 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
1395 .It Cm include_config
1396 This must be a path to another configuration file.
1397 Configuration files are usually read from top to bottom, however, if
1398 this option is set,
1399 .Nm
1400 will begin reading the included file at this location and continue
1401 reading the rest of the configuation after the included file has
1402 finished being read.
1403 .Pp
1404 Any simple settings set before the include may
1405 be overridden by settings in the included file, and any simple
1406 settings set in the included file may be overridden later by settings
1407 after the include or at runtime using the
1408 .Cm :set
1409 command.
1410 However, database settings (for example,
1411 .Cm cookie_wl , js_wl , pl_wl ,
1412 and
1413 .Cm keybinding )
1414 are only ever added to the database, and so the order of an included
1415 configuration file is not pertinent to these database settings.
1416 .Pp
1417 This feature is likely best used as the last item in
1418 .Pa ~/.xombrero.conf .
1419 .It Cm js_wl
1420 This is a Java Script whitelist item.
1421 See
1422 .Cm cookie_wl
1423 for semantics and more details.
1424 .It Cm max_connections
1425 The maximum number of connections that
1426 .Nm
1427 can open at once.
1428 .It Cm max_host_connections
1429 The maximum number of connections that
1430 .Nm
1431 can open at once to a given host.
1432 .It Cm mime_type
1433 Sets an action for a specific or default MIME type.
1434 For example, to download and view a pdf using kpdf set
1435 .Pa mime_type = application/pdf,kpdf .
1436 To set a default value use *, for example,
1437 .Pa mime_type = video/*,mplayer .
1438 Note that the action is only passed the URL and not all applications are
1439 capable of dealing with a URL and therefore one might have to create a wrapper
1440 script to download the content first.  Alternatively one can add the
1441 .Pa @
1442 in front of the MIME type to indicate "download first".
1443 For example,
1444 .Pa mime_type = @application/pdf,xpdf .
1445 When
1446 .Pa @
1447 is use the file will be downloaded to the
1448 .Pa download_dir
1449 before the MIME handler is called.
1450 .Pp
1451 The special binary name "donothing" may be used to ignore a MIME type
1452 without displaying any warnings from being unable to execute the
1453 binary.
1454 .It Cm oops_font
1455 Set the font used to display error messages.
1456 E.g.
1457 .Pa oops_font = monospace normal 9 .
1458 .It Cm pl_wl
1459 This is a plugin whitelist item.
1460 See
1461 .Cm cookie_wl
1462 for semantics and more details.
1463 .It Cm preload_strict_transport
1464 If enabled, a preloaded list of sites which set the HTTP Strict
1465 Transport Security header will be used to automatically set the
1466 .Cm force_https
1467 setting for these sites.
1468 This is used to prevent SSL stripping attacks when first visiting
1469 these sites, before they have been added to the strict-transport file.
1470 This list is comprised of domains chosen by the
1471 .Nm
1472 authors, as well as domains included in Chromium's preloaded HSTS
1473 list.
1474 Default is 1.
1475 .It Cm read_only_cookies
1476 Mark cookies file read-only and discard all cookies once the session is
1477 terminated.
1478 .It Cm refresh_interval
1479 Refresh interval while in the download manager.
1480 The default is 10.
1481 .It Cm referer
1482 Control how 'Referer' is handled in http-requests.
1483 .Bd -literal -offset indent
1484 always      - always send referer
1485 never       - never send referer
1486 same-domain - only send referer if it's
1487               for the same public suffix - this means that
1488               it's ok for subdomains to refer to each other
1489 same-fqdn   - only send referer if it's FQDN match
1490 .Ed
1491 Any other value that is also a valid URL will use this
1492 custom value as referer. (E.g. you could set it to http://no-referer.com)
1493 The default value is "always"
1494 .It Cm resource_dir
1495 Directory that contains various
1496 .Nm
1497 resources such as icons.
1498 This is OS-specific and should be handled by the porter.
1499 .It Cm save_global_history
1500 If set the global history will be saved to
1501 .Pa ~/.xombrero/history
1502 when quitting
1503 and restored at startup.
1504 See the
1505 .Sx KEY BINDINGS
1506 section above for how the global history is accessed.
1507 Global history is not saved to disk by default.
1508 .It Cm save_rejected_cookies
1509 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
1510 All cookies are saved and unlike a cookie jar they are never replaced.
1511 Make sure there is enough disk space to enable this feature.
1512 .It Cm search_string
1513 Default search engine string.
1514 See the
1515 .Pa xombrero.conf
1516 file for details.
1517 .It Cm session_autosave
1518 Enable session auto-saving when changing state (e.g. adding or removing a tab).
1519 The session name is what is currently in use and is described in the
1520 .Cm session save
1521 and
1522 .Cm session open
1523 commands.
1524 .It Cm session_timeout
1525 This value is the time that is added in seconds to a session cookie.
1526 .It Cm show_tabs
1527 Enable or disable showing tabs.
1528 .It Cm show_url
1529 Enable or disable showing the url and toolbar.
1530 .It Cm show_scrollbars
1531 Enable or disable the showing of the horizontal and vertical scrollbars.
1532 Disabling this setting requires GTK3.
1533 .It Cm show_statusbar
1534 Enable or disable showing the status bar.
1535 .It Cm single_instance
1536 If set and
1537 .Cm enable_socket
1538 is enabled only one
1539 .Nm
1540 will be permitted to run.
1541 If there is a URL specified it will be opened in a new tab in the already
1542 running
1543 .Nm
1544 session.
1545 .It Cm spell_check_languages
1546 The languages to be used for spell checking, separated by commas. For example,
1547 en_US.
1548 .It Cm ssl_ca_file
1549 If set to a valid PEM file
1550 all server certificates will be validated against it.
1551 The URL bar will be colored green (or blue when saved) when the certificate is
1552 trusted and yellow when untrusted.
1553 .Pp
1554 If
1555 .Cm ssl_ca_file
1556 is not set, the URL bar will be colored red if the certificate has not
1557 been saved, or blue if it has been saved.
1558 .Pp
1559 WebKit only supports a single PEM file.
1560 Many OS' or distributions have many PEM files.
1561 One can simply concatenate all separate files into one large one.
1562 E.g.
1563 .Cm for i in `ls`; do cat $i >> cert.pem; done
1564 and use the resulting cert.pem file as the input to
1565 .Cm ssl_ca_file .
1566 It is advisable to periodically recreate the cert.pem file.
1567 .It Cm ssl_strict_certs
1568 If this value is set connections to untrusted sites will be aborted.
1569 This value is only used if
1570 .Cm ssl_ca_file
1571 is set.
1572 .It Cm statusbar_elems
1573 Define the components of the status bar. The possible components are:
1574 .Bd -literal -offset indent
1575 | - separator
1576 P - page progress percent
1577 p - proxy enabled/disabled
1578 B - buffer command
1579 Z - page zoom level
1580 T - current tab number
1581 .Ed
1582 The default is "BP".
1583 These components show nothing if there is nothing worth showing, like
1584 zoom amount 100%.
1585 .It Cm statusbar_font
1586 Set the status bar font.
1587 E.g.
1588 .Pa statusbar_font = monospace normal 9 .
1589 .It Cm statusbar_style
1590 Set the status bar style to either
1591 .Cm url
1592 - display the current url, or
1593 .Cm title
1594 - display the page title. The default is
1595 .Cm url .
1596 .It Cm tab_style
1597 Set the tab style to either
1598 .Cm normal
1599 - the default gtk notebook tabs, or
1600 .Cm compact
1601 for an alternative.
1602 You can switch the tab style with the
1603 .Pa tabnextstyle
1604 command.
1605 .It Cm tabbar_font
1606 Set the compact tab bar font.
1607 E.g.
1608 .Pa tabbar_font = monospace normal 9 .
1609 .It Cm tabless
1610 Disable tabs, and open new windows instead.
1611 Note that this feature does not disable the display of tabs.
1612 Change your
1613 .Cm show_tabs
1614 setting also if you wish to disable the display of tabs.
1615 Default is 0.
1616 .It Cm url_regex
1617 This is the regular expression that is used to match what constitutes a valid
1618 URL when using
1619 .Pa guess_search .
1620 .It Cm user_agent
1621 Set to override the default
1622 .Nm
1623 user-agent string. May be specified several times for switching between
1624 user-agents.
1625 .It Cm userstyle
1626 Set the stylesheet to be used as a default for the
1627 .Cm userstyle
1628 and
1629 .Cm userstyle_global
1630 commands when no extra parameters are given.
1631 The default is a low-contrast stylesheet.
1632 .It Cm userstyle_global
1633 When enabled new tabs will automatically be displayed using the custom
1634 stylesheet specified by the
1635 .Cm userstyle
1636 setting.
1637 .It Cm warn_cert_changes
1638 When enabled all SSL certificates from HTTPS websites will be
1639 cached in the
1640 .Cm ~/.xombrero/certs_cache/
1641 directory.
1642 On each page load, if the remote certificate differs from the cached
1643 local version, a warning page with options of what to do next will be displayed
1644 instead of the requested page.
1645 This feature may be used in addition to the coloring of the URL bar and
1646 can be used to help prevent against man-in-the-middle attacks, even if
1647 the new remote certificate is signed by a trusted certificate
1648 authority in
1649 .Cm ssl_ca_file .
1650 Default is 0.
1651 .It Cm window_height
1652 Set the default height of the browser window.
1653 .It Cm window_width
1654 Set the default width of the browser window.
1655 .It Cm window_maximize
1656 Maximize the browser window at startup.
1657 .It Cm work_dir
1658 Set the work directory where all
1659 .Nm
1660 scratch files are stored.
1661 Default is
1662 .Cm ~/.xombrero .
1663 .El
1664 .Sh HISTORY
1665 .Nm
1666 was inspired by vimprobable2 and the bloat in other
1667 .Ux
1668 web browsers.
1669 .Sh AUTHORS
1670 .An -nosplit
1671 .Nm
1672 was written by
1673 .An Marco Peereboom Aq marco@peereboom.us ,
1674 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
1675 .An Edd Barrett Aq vext01@gmail.com ,
1676 .An Todd T. Fries Aq todd@fries.net ,
1677 .An Raphael Graf Aq r@undefined.ch ,
1678 .An Michal Mazurek Aq akfaew@jasminek.net ,
1679 and
1680 .An Josh Rickmar Aq jrick@devio.us .