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