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