xxxterm.1

   1 .\"     $xxxterm$
   2 .\"
   3 .\" Copyright (c) 2010, 2011 Marco Peereboom <marco@peereboom.us>
   4 .\" Copyright (c) 2011 Jason McIntyre <jmc@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate$
  19 .Dt XXXTERM 1
  20 .Os
  21 .Sh NAME
  22 .Nm xxxterm
  23 .Nd lightweight web browser
  24 .Sh SYNOPSIS
  25 .Nm xxxterm
  26 .Bk -words
  27 .Op Fl nSTtV
  28 .Op Fl f Ar file
  29 .Op Fl s Ar session_name
  30 .Op Ar url ...
  31 .Ek
  32 .Sh DESCRIPTION
  33 .Nm
  34 is a minimalistic web browser that tries to stay out of the way so that
  35 valuable screen real estate can be used for much more important stuff.
  36 It has sane defaults and does not require one to learn a language to do any
  37 configuration.
  38 It was written by hackers for hackers
  39 and it strives to be small, compact, and fast.
  40 .Pp
  41 .Nm
  42 is very simple in its use.
  43 Most actions are initiated via key or mouse bindings.
  44 Key bindings are based on those of the
  45 .Xr vi 1
  46 text editor,
  47 giving web browsing a similar feel to navigating a text document.
  48 The
  49 .Sx KEY BINDINGS
  50 section below documents the various defaults and possible customizations.
  51 .Pp
  52 The options are as follows:
  53 .Bl -tag -width Ds
  54 .It Fl f Ar file
  55 Specify an alternative configuration file.
  56 .It Fl n
  57 Open a new tab in a running
  58 .Nm
  59 for each specified URL.
  60 This option requires
  61 .Cm enable_socket
  62 to be enabled.
  63 .It Fl e Ar command
  64 Execute arbitrary command (see the
  65 .Sx COMMAND MODE
  66 section below) in a running
  67 .Nm
  68 instance. This option requires
  69 .Cm enable_socket
  70 to be enabled. Example run: xxxterm -e "tabnew openbsd.org"; xxxterm -e
  71 tabclose; xxxterm -e wq.
  72 .It Fl S
  73 Disable the toolbar.
  74 .It Fl s Ar session_name
  75 Open session that was saved with ":session save" command.
  76 .It Fl T
  77 Disable visualization of tabs.
  78 .It Fl t
  79 Disable tabs.
  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 GTK has some default keybindings for manipulating text inside input
 148 fields, such as the URI or search entry widget, for example
 149 .Cm C-w
 150 deletes a word. To override these defaults prefix your key with an
 151 exclamation mark, like this: "keybinding = tabclose,!C-w".
 152 The
 153 .Cm clearall
 154 key word is special and is meant to reset the key binding list to the GTK+
 155 and WebKit defaults.
 156 This keyword should be the first
 157 .Cm keybinding
 158 entry in the configuration file.
 159 .Pp
 160 Shift should be used sparingly since it gets in the way of non-USA keyboards.
 161 See the accompanying configuration file for examples.
 162 .Pp
 163 The various bindings are documented below.
 164 The relevant keybinding action is given afterwards, in parentheses.
 165 .Ss Search Commands
 166 These commands are used to search for text strings within a web page.
 167 .Pp
 168 .Bl -tag -width Ds -offset indent -compact
 169 .It Cm /
 170 Start a search
 171 .Pq Cm search
 172 .It Cm \&?
 173 Start a backwards search
 174 .Pq Cm searchb
 175 .It Cm n
 176 Next item matching search
 177 .Pq Cm searchnext
 178 .It Cm N
 179 Previous item matching search
 180 .Pq Cm searchprev
 181 .El
 182 .Ss Focus Commands
 183 These commands are used to shift the focus of
 184 .Nm
 185 from one area to another.
 186 .Pp
 187 .Bl -tag -width Ds -offset indent -compact
 188 .It Cm F6
 189 Focus on address bar
 190 .Pq Cm focusaddress
 191 .It Cm F7
 192 Focus on search entry
 193 .Pq Cm focussearch
 194 .El
 195 .Ss Command Aliases
 196 These commands allow the user to map specific actions to specific keys.
 197 It can be useful when the
 198 .Fl S
 199 option is used.
 200 .Pp
 201 .Bl -tag -width Ds -offset indent -compact
 202 .It Cm F1
 203 Alias for ":help"
 204 .It Cm F4
 205 Alias for ":toplevel toggle"
 206 .It Cm F9
 207 Alias for ":open"
 208 .Pq Cm promptopen
 209 .It Cm F10
 210 Alias for ":open current-uri"
 211 .Pq Cm promptopencurrent
 212 .It Cm F11
 213 Alias for ":tabnew"
 214 .Pq Cm prompttabnew
 215 .It Cm F12
 216 Alias for ":tabnew current-uri"
 217 .Pq Cm prompttabnewcurrent
 218 .El
 219 .Ss Navigation Commands
 220 These commands allow the user to navigate web pages and,
 221 to some extent,
 222 control the browser.
 223 .Pp
 224 .Bl -tag -width "Space, C-f, PageDownXXX" -offset indent -compact
 225 .It Cm F5, C-r, C-l
 226 Reload page
 227 .Pq Cm reload
 228 .It Cm C-R
 229 Reload page without using any cached data
 230 .Pq Cm reloadforce
 231 .It Cm Backspace, M-Left
 232 Previous page
 233 .Pq Cm goback
 234 .It Cm S-BackSpace, M-Right
 235 Forward page
 236 .Pq Cm goforward
 237 .It Cm j, Down
 238 Next line on page
 239 .Pq Cm scrolldown
 240 .It Cm k, Up
 241 Previous line on page
 242 .Pq Cm scrollup
 243 .It Cm G, End
 244 Bottom of page
 245 .Pq Cm scrollbottom
 246 .It Cm gg, Home
 247 Top of page
 248 .Pq Cm scrolltop
 249 .It Cm Space, C-f, PageDown
 250 Page down
 251 .Pq Cm scrollpagedown
 252 .It Cm C-b, PageUp
 253 Page up
 254 .Pq Cm scrollpageup
 255 .It Cm l, Right
 256 Page right
 257 .Pq Cm scrollright
 258 .It Cm h, Left
 259 Page left
 260 .Pq Cm scrollleft
 261 .It Cm $
 262 Page far right
 263 .Pq Cm scrollfarright
 264 .It Cm 0
 265 Page far left
 266 .Pq Cm scrollfarleft
 267 .It Cm M-f
 268 Favorites
 269 .Pq Cm fav
 270 .It Cm M-j
 271 Cookie jar
 272 .Pq Cm cookiejar
 273 .It Cm M-d
 274 Download manager
 275 .Pq Cm dl
 276 .It Cm C-p
 277 Print page
 278 .Pq Cm print
 279 .It Cm M-h
 280 Global history
 281 .Pq Cm history
 282 .It Cm C-j
 283 Toggle Java Script enabled for FQDN
 284 .Pq Cm js
 285 .It Cm C-s
 286 Toggle source view
 287 .Pq Cm togglesrc
 288 .It Cm M-c
 289 Toggle cookie enabled for FQDN
 290 .Pq Cm cookie
 291 .El
 292 .Ss Tab Manipulation
 293 .Nm
 294 supports tabbed browsing.
 295 That is, web pages may be opened in separate tabs,
 296 allowing the user to quickly move from one page to another,
 297 and back.
 298 These commands then are used to create, destroy, and move between tabs.
 299 .Pp
 300 .Bl -tag -width "C-plus, C-equalXXX" -offset indent -compact
 301 .It Cm C-MB1
 302 Open new tab with the clicked link
 303 .It Cm C-t
 304 Create new tab with focus in URL entry
 305 .Pq Cm tabnew
 306 .It Cm C-w
 307 Destroy current tab
 308 .Pq Cm tabclose
 309 .It Cm U
 310 Undo close tab
 311 .Pq Cm tabundoclose
 312 .It Cm C-Left
 313 Go to the previous tab
 314 .Pq Cm tabprevious
 315 .It Cm C-Right
 316 Go to the next tab
 317 .Pq Cm tabnext
 318 .It Cm C-[1..0]
 319 Jump to page
 320 .Ar N
 321 .Pq Cm tabnext [1..0]
 322 .It Cm C-minus
 323 Shrink font size by one point
 324 .Pq Cm focusout
 325 .It Cm C-plus, C-equal
 326 Grow font size by one point
 327 .Pq Cm focusin
 328 .El
 329 .Ss Yanking and pasting
 330 These commands copy and paste text to and from the clipboard.
 331 .Pp
 332 .Bl -tag -width Ds -offset indent -compact
 333 .It Cm p
 334 Paste the contents of the clipboard into the address bar
 335 .Pq Cm pasteuricur
 336 .It Cm P
 337 Paste the contents of the clipboard into a new tab
 338 .Pq Cm pasteurinew
 339 .It Cm y
 340 Yank the current URL into the clipboard
 341 .Pq Cm yankuri
 342 .El
 343 .Ss Hyperlink Following
 344 This allows the user to follow hyperlinks
 345 without using a mouse.
 346 Enter the corresponding number to follow the link.
 347 Alternatively one can type the name of the link and when there are no more
 348 possibilities
 349 .Nm
 350 will follow the link.
 351 .Pp
 352 .Bl -tag -width Ds -offset indent -compact
 353 .It Cm f
 354 Highlight all links and prefix them with a number.
 355 .Pq Cm hinting
 356 .El
 357 .Ss Exiting
 358 Commands to exit the browser.
 359 .Pp
 360 .Bl -tag -width Ds -offset indent -compact
 361 .It Cm C-q
 362 Quit
 363 .Pq Cm quitall
 364 .El
 365 .Ss Low-Contrast Color Scheme
 366 This command toggles the page's style between the default CSS and a
 367 low-contrast color scheme with light grey text on a dark grey background.
 368 .Pp
 369 .Bl -tag -width Ds -offset indent -compact
 370 .It Cm i
 371 Toggle the current tab's style.
 372 .Pq Cm userstyle
 373 .El
 374 .Sh COMMAND MODE
 375 Command mode works in a similar fashion to the
 376 .Xr vi 1
 377 editor;
 378 it is entered by typing a colon and exited by typing Esc.
 379 The commands and their descriptions are listed below.
 380 .Bl -tag -width Ds -offset indent
 381 .It Cm about , version
 382 Show the "About" page.
 383 .It Cm ca
 384 Display CA certificates.
 385 .It Cm cert , cert show
 386 Download and display certificates of domain on tab.
 387 .It Cm cert save
 388 Save certificate into a local store.
 389 The next time the site is visited it is compared against the store.
 390 If the certificate matches,
 391 the address bar will be blue;
 392 if it doesn't the bar will be red.
 393 .It Cm cookie
 394 The
 395 .Cm cookie
 396 command is used to manipulate the cookie whitelist.
 397 Used by itself it expands to
 398 .Cm cookie show all .
 399 .It Cm cookiejar
 400 Show cookie jar contents.
 401 .It Cm cookie save, cookie save fqdn
 402 Save the current fully qualified domain name (FQDN)
 403 to the persistent whitelist.
 404 For example,
 405 the www.peereboom.us domain would result in saving .www.peereboom.us.
 406 .It Cm cookie save domain
 407 Save the top level domain name to the persistent whitelist.
 408 For example,
 409 the www.peereboom.us domain would result in saving .peereboom.us.
 410 .Pp
 411 This action enables cookies if it is currently disabled for this entry.
 412 .It Cm cookie show all
 413 Show all persistent and session entries in the cookie whitelist.
 414 .It Cm cookie show persistent
 415 Show all persistent entries in the cookie whitelist.
 416 .It Cm cookie show session
 417 Show all session entries in the cookie whitelist.
 418 .It Cm cookie toggle domain
 419 Toggle cookie support for the current top level domain.
 420 .It Cm cookie toggle, cookie toggle fqdn
 421 Toggle cookie support for the current FQDN.
 422 .It Cm dl
 423 Show download manager.
 424 .It Cm fav
 425 Show favorites.
 426 .It Cm favadd
 427 Add the current page to favorites.
 428 .It Cm fullscreen , f
 429 Toggle hiding tabs and url entry toolbar.
 430 .It Cm h , hist , history
 431 Show global history.
 432 .It Cm help
 433 Show help page.
 434 .It Cm home
 435 Go to home URL.
 436 .It Cm js
 437 The
 438 .Cm js
 439 command is used to manipulate the Java Script whitelist.
 440 Used by itself it expands to
 441 .Cm js show all .
 442 .It Cm js save, save fqdn
 443 Saves the FQDN to the persistent whitelist.
 444 For example,
 445 the www.peereboom.us domain would result in saving .www.peereboom.us.
 446 .It Cm js save domain
 447 Saves the top level domain name to the persistent whitelist.
 448 For example,
 449 the www.peereboom.us domain would result in saving .peereboom.us.
 450 .Pp
 451 This action enables Java Script if it is currently disabled for this entry.
 452 .It Cm js show all
 453 Shows all persistent and session entries in the JS whitelist.
 454 .It Cm js show persistent
 455 Shows all persistent entries in the JS whitelist.
 456 .It Cm js show session
 457 Shows all session entries in the JS whitelist.
 458 .It Cm js toggle, js toggle fqdn
 459 Toggle Java Script execution for the current FQDN.
 460 .It Cm js toggle domain
 461 Toggle Java Script execution for the current top level domain.
 462 .It Cm open , op , o URL
 463 Open URL.
 464 .It Cm print
 465 Print page.
 466 .It Cm qa , qall , quitall
 467 Quit
 468 .Nm .
 469 .It Cm quit , q
 470 Close current tab and quit
 471 .Nm
 472 if it is the last tab.
 473 .It Cm restart
 474 Restart
 475 .Nm
 476 and reload all current tabs.
 477 .It Cm session , Cm session show
 478 Display the current session name.
 479 By default the session name is main_session.
 480 To create a new session use the
 481 .Cm session save
 482 command.
 483 A session is defined as the lifetime of the browser application.
 484 .It Cm session delete <session_name>
 485 Delete session session_name from persistent storage.
 486 If session_name is the current session then the session will revert to
 487 main_session.
 488 .It Cm session open <session_name>
 489 Open session_name and close all currently open tabs.
 490 Going forward this session is named session_name.
 491 .It Cm session save <session_name>
 492 Save current tabs to session_name session.
 493 This will close the current session and going forward this session is named
 494 session_name.
 495 .It Cm stats
 496 Show blocked cookie statistics.
 497 These statistics vary based on settings and are not persistent.
 498 .It Cm statushide , statush
 499 Hide status bar.
 500 .It Cm statusshow , statuss
 501 Show status bar.
 502 .It Cm tabclose , tabc
 503 Close current tab.
 504 .It Cm tabhide , tabh
 505 Hide tabs.
 506 .It Cm tabnew , tabedit , tabe URL
 507 Create new tab and optionally open provided URL.
 508 .It Cm tabnext , tabn
 509 Go to the next tab.
 510 .It Cm tabprevious , tabp
 511 Go to the previous tab.
 512 .It Cm tabshow , tabs
 513 Show tabs.
 514 .It Cm toplevel , toplevel toggle
 515 Toggle the top level domain name cookie and JS session whitelist.
 516 This is to enable/disable short lived full site functionality without
 517 permanently adding the top level domain to the persistent whitelist.
 518 .It Cm urlhide , urlh
 519 Hide url entry and tool bar.
 520 .It Cm urlshow , urls
 521 Show url entry and tool bar.
 522 .It Cm w
 523 Save open tabs to current session.
 524 The tabs will be restored next time
 525 .Nm
 526 the session is opened.
 527 See the session command for additional details.
 528 .It Cm wq
 529 Save open tabs and quit.
 530 The tabs will be restored next time
 531 .Nm
 532 the session is opened.
 533 See the session command for additional details.
 534 .El
 535 .Sh ABOUT SCREENS
 536 The about screens are internally generated web pages by
 537 .Nm
 538 for user interaction.
 539 These are entered in the address bar and the format is
 540 .Cm about:screen
 541 where screen is the desired screen to display.
 542 For example about:favorites.
 543 Any about screen can be used as the home page as specified by
 544 .Cm home
 545 in the configuration file.
 546 .Pp
 547 .Bl -tag -width "downloadsXXX" -offset indent -compact
 548 .It Cm about
 549 show the about screen
 550 .It Cm blank
 551 show a blank screen
 552 .It Cm cookiewl
 553 show the cookie whitelist screen
 554 .It Cm cookiejar
 555 show the cookiejar screen
 556 .It Cm downloads
 557 show the downloads screen
 558 .It Cm favorites
 559 show the favorites screen
 560 .It Cm help
 561 show the help web page
 562 .It Cm history
 563 show the history screen
 564 .It Cm jswl
 565 show the Java Script whitelist screen
 566 .It Cm set
 567 show the settings screen
 568 .It Cm stats
 569 show the statistics screen
 570 .El
 571 .Sh WHITELISTS
 572 This section descibes advanced usage settings.
 573 Most users should use
 574 .Cm browser_mode
 575 instead to setup
 576 .Nm
 577 and skip over this section.
 578 .Pp
 579 .Nm
 580 has a number of whitelists to control blocking cookies and Java Script
 581 execution for FQDNs or domains.
 582 When properly enabled these whitelists require either the FQDN or top level
 583 domain to exist in the whitelists in order to allow cookies to be stored or
 584 Java Script to execute.
 585 Both Java Script and cookies have two whitelists associated with them.
 586 The whitelists are called session and persistent.
 587 Items in the session whitelists are only allowed for the lifetime of the
 588 .Nm
 589 instance.
 590 Items in the persistent whitelists are stored on disk and are restored
 591 upon restarting.
 592 .Pp
 593 Setting up the whitelists is a little tricky due to intricacies of WebKit.
 594 In fact the semantics are different for cookies and Java Script.
 595 .Pp
 596 Cookie whitelist requires the following configuration to be set:
 597 .Pp
 598 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
 599 .It Cm cookies_enabled
 600 This is a WebKit setting and must be set to
 601 .Pa 1
 602 (ENABLED)
 603 in order to be able to use a
 604 cookie whitelist.
 605 .It Cm enable_cookie_whitelist
 606 This needs to be set to
 607 .Pa 1
 608 to enable the cookie whitelist functionality.
 609 .It Cm cookie_wl
 610 These entries in the configuration file are the actual domains names in the
 611 cookie whitelist.
 612 .El
 613 .Pp
 614 Java Script whitelist requires the following configuration to be set:
 615 .Pp
 616 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
 617 .It Cm enable_scripts
 618 This is a WebKit setting and must be set to
 619 .Pa 0
 620 (DISABLED)
 621 in order to be able to use a
 622 Java Script whitelist.
 623 .It Cm enable_js_whitelist
 624 This needs to be set to
 625 .Pa 1
 626 to enable the Java Script whitelist functionality.
 627 .It Cm js_wl
 628 These entries in the configuration file are the actual domains names in the
 629 Java Script whitelist.
 630 .El
 631 .Pp
 632 See the
 633 .Pa FILES
 634 section for additional configuration file entries and details
 635 that alter runtime behavior.
 636 .Sh FILES
 637 .Bl -tag -width "/etc/xxxterm.confXXX" -compact
 638 .It Pa ~/.xxxterm.conf
 639 .Nm
 640 user specific settings.
 641 .It Pa ~/.xxxterm
 642 .Nm
 643 scratch directory.
 644 .El
 645 .Pp
 646 .Nm
 647 tries to open the user specific file,
 648 .Pa ~/.xxxterm.conf .
 649 If that file is unavailable,
 650 it then uses built-in defaults.
 651 .Pp
 652 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
 653 For example:
 654 .Pp
 655 .Dl http_proxy = http://127.0.0.1:8080
 656 .Pp
 657 Enabling or disabling an option is done by using 1 or 0 respectively.
 658 .Pp
 659 The file supports the following keywords:
 660 .Pp
 661 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
 662 .It Cm alias
 663 Defines an alias for a given URL, so that the URL is loaded when the alias is
 664 entered in the address bar.
 665 If the aliased URL includes a %s format specifier, then any argument given after
 666 the alias on the address bar is substituted.
 667 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
 668 then the URL http://www.google.com/search?q=foo is loaded when navigating to
 669 "g foo".
 670 .It Cm allow_volatile_cookies
 671 If set cookies are stored in the session cache but will be discarded once
 672 .Nm
 673 exits.
 674 Unfortunately enabling this does allow for some limited tracking on the web.
 675 .It Cm append_next
 676 When set a new tab is appended after the current tab instead of being appended
 677 as the last tab.
 678 .It Cm browser_mode
 679 The
 680 .Nm
 681 browser has 3 default operating modes:
 682 .Pa normal
 683 (the default),
 684 .Pa whitelist
 685 and
 686 .Pa kiosk .
 687 In the
 688 .Pa normal
 689 mode the browser allows all cookies and Java Script as any other browser
 690 would.
 691 This means that all cookies are saved to persistent storage and that all
 692 Java Script runs.
 693 .Pp
 694 On the other hand, using the
 695 .Pa whitelist
 696 mode enables whitelists.
 697 This requires the user to add all the required
 698 .Pa cookie_wl
 699 and
 700 .Pa js_wl
 701 items.
 702 If a domain does not appear in the whitelists
 703 .Nm
 704 disallows cookies and Java Script execution.
 705 .Pp
 706 In
 707 .Pa kiosk
 708 mode the browse works just like
 709 .Pa normal
 710 mode however the toolbar only has the backward, forward and home button.
 711 .Pp
 712 This setting must be the first entry in
 713 .Pa ~/.xxxterm.conf
 714 because it sets advanced settings that can be overridden later in the file.
 715 See the default config file for more details.
 716 .It Cm cookie_policy
 717 This field delineates the cookie policy.
 718 Possible values are: no3rdparty, reject 3rd party cookies.
 719 accept, accept all cookies.
 720 reject, reject all cookies.
 721 .It Cm cookie_wl
 722 This is a cookie whitelist item.
 723 Use multiple times to add multiple entries.
 724 Valid entries are for example *.moo.com and the equivalent .moo.com.
 725 A fully qualified host is also valid and is for example www.moo.com.
 726 .It Cm cookies_enabled
 727 Enable cookies.
 728 .It Cm ctrl_click_focus
 729 Give focus in newly created tab instead of opening it in the background.
 730 .It Cm default_font_size
 731 Set the default browsing font size.
 732 .It Cm default_zoom_level
 733 Set the default browsing zoom level.
 734 .It Cm download_dir
 735 Locations where files are downloaded to.
 736 This directory must exist and
 737 .Nm
 738 validates that during startup.
 739 .It Cm enable_cookie_whitelist
 740 When enabled all cookies must be in the whitelist or they are rejected.
 741 .It Cm enable_js_whitelist
 742 When enabled all domains must be in the js whitelist in order to run Java Script.
 743 NOTE: Make sure
 744 .Cm enable_scripts
 745 is set to 0.
 746 .It Cm enable_plugins
 747 Enable plugins.
 748 .It Cm enable_scripts
 749 Enable scripts.
 750 .It Cm enable_socket
 751 When enabled the first instance of
 752 .Nm
 753 will create a socket in the
 754 .Pa ~/.xxxterm
 755 directory.
 756 Using the -n url option on subsequent
 757 .Nm
 758 invocations will cause the specified URL to be loaded in a new tab.
 759 Only a user with identical UID and GID can use this option.
 760 .It Cm enable_spell_checking
 761 Enables spell checking. Preferred languages can be set using
 762 .Cm spell_check_languages
 763 option.
 764 .It Cm fancy_bar
 765 Enables a backward, forward, and stop button to the toolbar.
 766 Additionally if
 767 .Cm search_string
 768 is set it'll enable an entry box for searches.
 769 .It Cm guess_search
 770 When enabled
 771 .Nm
 772 will try to guess if the string you entered, in the URI entry widget or
 773 the command widget, is term you want to search for using search_string
 774 (see above).
 775 If the string does not contain a dot nor a slash, is not a
 776 path to a local file and does not resolves to an IP then it is assumed
 777 to be a search term.
 778 .It Cm home
 779 Homepage in URL format.
 780 .It Cm http_proxy
 781 Proxy server in URL format.
 782 .Nm
 783 overrides
 784 .Cm http_proxy
 785 if it is specified as an environment variable.
 786 It must be noted that one MUST use an IP address and not a FQDN.
 787 .Pp
 788 If one desires to use a socks proxy then an intermediary tool must be used.
 789 It has been reported that tsocks works with
 790 .Nm .
 791 .It Cm icon_size
 792 Permits icon sizes to be changed if
 793 .Cm fancy_bar
 794 is enabled.
 795 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
 796 .It Cm js_wl
 797 This is a Java Script whitelist item.
 798 See
 799 .Cm cookie_wl
 800 for semantics and more details.
 801 .It Cm max_connections
 802 The maximum number of connections that
 803 .Nm
 804 can open at once.
 805 .It Cm max_host_connections
 806 The maximum number of connections that
 807 .Nm
 808 can open at once to a given host.
 809 .It Cm mime_type
 810 Sets an action for a specific or default MIME type.
 811 For example, to download and view a pdf using kpdf set
 812 .Pa mime_type = application/pdf,kpdf .
 813 To set a default value use *, for example,
 814 .Pa mime_type = video/*,mplayer .
 815 Note that the action is only passed the URL and not all applications are
 816 capable of dealing with a URL and therefore one might have to create a wrapper
 817 script to download the content first.  Alternatively one can add the
 818 .Pa @
 819 in front of the MIME type to indicate "download first".
 820 For example,
 821 .Pa mime_type = @application/pdf,xpdf .
 822 When
 823 .Pa @
 824 is use the file will be downloaded to the
 825 .Pa download_dir
 826 before the MIME handler is called.
 827 .It Cm read_only_cookies
 828 Mark cookies file read-only and discard all cookies once the session is
 829 terminated.
 830 .It Cm refresh_interval
 831 Refresh interval while in the download manager.
 832 The default is 10.
 833 .It Cm resource_dir
 834 Directory that contains various
 835 .Nm
 836 resources such as icons.
 837 This is OS-specific and should be handled by the porter.
 838 .It Cm save_global_history
 839 If set the global history will be saved to
 840 .Pa ~/.xxxterm/history
 841 when quitting
 842 and restored at startup.
 843 See the
 844 .Sx KEY BINDINGS
 845 section above for how the global history is accessed.
 846 Global history is not saved to disk by default.
 847 .It Cm save_rejected_cookies
 848 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
 849 All cookies are saved and unlike a cookie jar they are never replaced.
 850 Make sure there is enough disk space to enable this feature.
 851 .It Cm search_string
 852 Default search engine string.
 853 See the
 854 .Pa xxxterm.conf
 855 file for details.
 856 .It Cm session_autosave
 857 Enable session auto-saving when changing state (e.g. adding or removing a tab).
 858 The session name is what is currently in use and is described in the
 859 .Cm session save
 860 and
 861 .Cm session open
 862 commands.
 863 .It Cm session_timeout
 864 This value is the time that is added in seconds to a session cookie.
 865 .It Cm show_tabs
 866 Enable or disable showing tabs.
 867 .It Cm show_url
 868 Enable or disable showing the url and toolbar.
 869 .It Cm show_statusbar
 870 Enable or disable showing the status bar.
 871 .It Cm single_instance
 872 If set only one
 873 .Nm
 874 will be permitted to run.
 875 If there is a URL specified it will be opened in a new tab in the already
 876 running
 877 .Nm
 878 session.
 879 .It Cm spell_check_languages
 880 The languages to be used for spell checking, separated by commas. For example, en_US.
 881 .It Cm ssl_ca_file
 882 If set to a valid PEM file
 883 all server certificates will be validated against it.
 884 The URL bar will be colored green when the certificate is trusted
 885 and yellow when untrusted.
 886 .Pp
 887 If
 888 .Cm ssl_ca_file
 889 is not set then the URL bar will color all HTTPS connections red.
 890 .It Cm ssl_strict_certs
 891 If this value is set connections to untrusted sites will be aborted.
 892 This value is only used if
 893 .Cm ssl_ca_file
 894 is set.
 895 .It Cm user_agent
 896 Set to override the default
 897 .Nm
 898 user-agent string.
 899 .It Cm window_height
 900 Set the default height of the browser window.
 901 .It Cm window_width
 902 Set the default width of the browser window.
 903 .It Cm work_dir
 904 Set the work directory where all
 905 .Nm
 906 scratch files are stored.
 907 Default is
 908 .Cm ~/.xxxterm .
 909 .El
 910 .Sh HISTORY
 911 .Nm
 912 was inspired by vimprobable2 and the bloat in other
 913 .Ux
 914 web browsers.
 915 .Sh AUTHORS
 916 .An -nosplit
 917 .Nm
 918 was written by
 919 .An Marco Peereboom Aq marco@peereboom.us ,
 920 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
 921 .An Edd Barrett Aq vext01@gmail.com ,
 922 and
 923 .An Todd T. Fries Aq todd@fries.net .
 924 .Sh BUGS
 925 When
 926 .Cm save_global_history
 927 is enabled
 928 .Nm
 929 is supposed to, in addition to restoring the global history, color the
 930 visited links accordingly; however due to bug #51747 in WebKit this does
 931 not happen.