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: October 14 2011 $
  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 Backspace, M-Left
 229 Previous page
 230 .Pq Cm goback
 231 .It Cm S-BackSpace, M-Right
 232 Forward page
 233 .Pq Cm goforward
 234 .It Cm j, Down
 235 Next line on page
 236 .Pq Cm scrolldown
 237 .It Cm k, Up
 238 Previous line on page
 239 .Pq Cm scrollup
 240 .It Cm G, End
 241 Bottom of page
 242 .Pq Cm scrollbottom
 243 .It Cm gg, Home
 244 Top of page
 245 .Pq Cm scrolltop
 246 .It Cm Space, C-f, PageDown
 247 Page down
 248 .Pq Cm scrollpagedown
 249 .It Cm C-b, PageUp
 250 Page up
 251 .Pq Cm scrollpageup
 252 .It Cm l, Right
 253 Page right
 254 .Pq Cm scrollright
 255 .It Cm h, Left
 256 Page left
 257 .Pq Cm scrollleft
 258 .It Cm $
 259 Page far right
 260 .Pq Cm scrollfarright
 261 .It Cm 0
 262 Page far left
 263 .Pq Cm scrollfarleft
 264 .It Cm M-f
 265 Favorites
 266 .Pq Cm fav
 267 .It Cm M-j
 268 Cookie jar
 269 .Pq Cm cookiejar
 270 .It Cm M-d
 271 Download manager
 272 .Pq Cm dl
 273 .It Cm C-p
 274 Print page
 275 .Pq Cm print
 276 .It Cm M-h
 277 Global history
 278 .Pq Cm history
 279 .It Cm C-j
 280 Toggle Java Script enabled for FQDN
 281 .Pq Cm js
 282 .It Cm C-s
 283 Toggle source view
 284 .Pq Cm togglesrc
 285 .It Cm M-c
 286 Toggle cookie enabled for FQDN
 287 .Pq Cm cookie
 288 .El
 289 .Ss Tab Manipulation
 290 .Nm
 291 supports tabbed browsing.
 292 That is, web pages may be opened in separate tabs,
 293 allowing the user to quickly move from one page to another,
 294 and back.
 295 These commands then are used to create, destroy, and move between tabs.
 296 .Pp
 297 .Bl -tag -width "C-plus, C-equalXXX" -offset indent -compact
 298 .It Cm C-MB1
 299 Open new tab with the clicked link
 300 .It Cm C-t
 301 Create new tab with focus in URL entry
 302 .Pq Cm tabnew
 303 .It Cm C-w
 304 Destroy current tab
 305 .Pq Cm tabclose
 306 .It Cm U
 307 Undo close tab
 308 .Pq Cm tabundoclose
 309 .It Cm C-Left
 310 Go to the previous tab
 311 .Pq Cm tabprevious
 312 .It Cm C-Right
 313 Go to the next tab
 314 .Pq Cm tabnext
 315 .It Cm C-[1..9]
 316 Jump to page
 317 .Ar N
 318 .Pq Cm tabnext [1..9]
 319 .It Cm C-minus
 320 Zoom out by 4%
 321 .Pq Cm focusout
 322 .It Cm C-plus, C-equal
 323 Zoom in by 4%
 324 .Pq Cm focusin
 325 .It Cm C-0
 326 Set zoom level to 100%
 327 .Pq Cm focusreset
 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 .It Cm F
 357 Highlight all links and prefix them with a number but open in a new tab.
 358 .Pq Cm hinting_newtab
 359 .El
 360 .Ss Exiting
 361 Commands to exit the browser.
 362 .Pp
 363 .Bl -tag -width Ds -offset indent -compact
 364 .It Cm C-q
 365 Quit
 366 .Pq Cm quitall
 367 .El
 368 .Ss Low-Contrast Color Scheme
 369 This command toggles the page's style between the default CSS and a
 370 low-contrast color scheme with light grey text on a dark grey background.
 371 .Pp
 372 .Bl -tag -width Ds -offset indent -compact
 373 .It Cm i
 374 Toggle the current tab's style.
 375 .Pq Cm userstyle
 376 .El
 377 .Sh COMMAND MODE
 378 Command mode works in a similar fashion to the
 379 .Xr vi 1
 380 editor;
 381 it is entered by typing a colon and exited by typing Esc.
 382 The commands and their descriptions are listed below.
 383 .Bl -tag -width Ds -offset indent
 384 .It Cm about , version
 385 Show the "About" page.
 386 .It Cm buffers , ls , tabs
 387 Displays the currently open tabs and lets the user switch tab by typing
 388 the tab number or using the mouse.
 389 .It Cm ca
 390 Display CA certificates.
 391 .It Cm cert , cert show
 392 Download and display certificates of domain on tab.
 393 .It Cm cert save
 394 Save certificate into a local store.
 395 The next time the site is visited it is compared against the store.
 396 If the certificate matches,
 397 the address bar will be blue;
 398 if it doesn't the bar will be red.
 399 .It Cm cookie
 400 The
 401 .Cm cookie
 402 command is used to manipulate the cookie whitelist.
 403 Used by itself it expands to
 404 .Cm cookie show all .
 405 .It Cm cookiejar
 406 Show cookie jar contents.
 407 .It Cm cookie save, cookie save fqdn
 408 Save the current fully qualified domain name (FQDN)
 409 to the persistent whitelist.
 410 For example,
 411 the www.peereboom.us domain would result in saving .www.peereboom.us.
 412 .It Cm cookie save domain
 413 Save the top level domain name to the persistent whitelist.
 414 For example,
 415 the www.peereboom.us domain would result in saving .peereboom.us.
 416 .Pp
 417 This action enables cookies if it is currently disabled for this entry.
 418 .It Cm cookie show all
 419 Show all persistent and session entries in the cookie whitelist.
 420 .It Cm cookie show persistent
 421 Show all persistent entries in the cookie whitelist.
 422 .It Cm cookie show session
 423 Show all session entries in the cookie whitelist.
 424 .It Cm cookie toggle domain
 425 Toggle cookie support for the current top level domain.
 426 .It Cm cookie toggle, cookie toggle fqdn
 427 Toggle cookie support for the current FQDN.
 428 .It Cm dl
 429 Show download manager.
 430 .It Cm encoding <encoding>
 431 If
 432 .Cm <encoding>
 433 is set the tab's encoding will be set to
 434 .Cm <encoding>
 435 and
 436 .Nm
 437 reloads the tab.
 438 If
 439 .Cm <encoding>
 440 is not set
 441 .Nm
 442 will display the current tab encoding.
 443 .It Cm fav
 444 Show favorites.
 445 .It Cm favadd
 446 Add the current page to favorites.
 447 .It Cm fullscreen , f
 448 Toggle hiding tabs and url entry toolbar.
 449 .It Cm h , hist , history
 450 Show global history.
 451 .It Cm help
 452 Show help page.
 453 .It Cm home
 454 Go to home URL.
 455 .It Cm js
 456 The
 457 .Cm js
 458 command is used to manipulate the Java Script whitelist.
 459 Used by itself it expands to
 460 .Cm js show all .
 461 .It Cm js save, save fqdn
 462 Saves the FQDN to the persistent whitelist.
 463 For example,
 464 the www.peereboom.us domain would result in saving .www.peereboom.us.
 465 .It Cm js save domain
 466 Saves the top level domain name to the persistent whitelist.
 467 For example,
 468 the www.peereboom.us domain would result in saving .peereboom.us.
 469 .Pp
 470 This action enables Java Script if it is currently disabled for this entry.
 471 .It Cm js show all
 472 Shows all persistent and session entries in the JS whitelist.
 473 .It Cm js show persistent
 474 Shows all persistent entries in the JS whitelist.
 475 .It Cm js show session
 476 Shows all session entries in the JS whitelist.
 477 .It Cm js toggle, js toggle fqdn
 478 Toggle Java Script execution for the current FQDN.
 479 .It Cm js toggle domain
 480 Toggle Java Script execution for the current top level domain.
 481 .It Cm open , op , o URL
 482 Open URL.
 483 .It Cm plugin
 484 The
 485 .Cm plugin
 486 command is used to manipulate the plugin whitelist.
 487 Used by itself it expands to
 488 .Cm plugin show all .
 489 .It Cm plugin save, save fqdn
 490 Saves the FQDN to the persistent whitelist.
 491 For example,
 492 the www.peereboom.us domain would result in saving .www.peereboom.us.
 493 .It Cm plugin save domain
 494 Saves the top level domain name to the persistent whitelist.
 495 For example,
 496 the www.peereboom.us domain would result in saving .peereboom.us.
 497 .Pp
 498 This action enables plugins if they are currently disabled for this entry.
 499 .It Cm plugin show all
 500 Shows all persistent and session entries in the plugin whitelist.
 501 .It Cm plugin show persistent
 502 Shows all persistent entries in the plugin whitelist.
 503 .It Cm plugin show session
 504 Shows all session entries in the plugin whitelist.
 505 .It Cm plugin toggle, plugin toggle fqdn
 506 Toggle plugin execution for the current FQDN.
 507 .It Cm plugin toggle domain
 508 Toggle plugin execution for the current top level domain.
 509 .It Cm print
 510 Print page.
 511 .It Cm qa , qall , quitall
 512 Quit
 513 .Nm .
 514 .It Cm quit , q
 515 Close current tab and quit
 516 .Nm
 517 if it is the last tab.
 518 .It Cm restart
 519 Restart
 520 .Nm
 521 and reload all current tabs.
 522 .It Cm run_script [path_to_script]
 523 Runs the script path_to_script with the current uri as the argument.
 524 If path_to_script is not provided, the value of default_script is used
 525 instead.
 526 .It Cm session , Cm session show
 527 Display the current session name.
 528 By default the session name is main_session.
 529 To create a new session use the
 530 .Cm session save
 531 command.
 532 A session is defined as the lifetime of the browser application.
 533 .It Cm session delete <session_name>
 534 Delete session session_name from persistent storage.
 535 If session_name is the current session then the session will revert to
 536 main_session.
 537 .It Cm session open <session_name>
 538 Open session_name and close all currently open tabs.
 539 Going forward this session is named session_name.
 540 .It Cm session save <session_name>
 541 Save current tabs to session_name session.
 542 This will close the current session and going forward this session is named
 543 session_name.
 544 .It Cm set
 545 The set command is used to inspect, clear or change runtime options.
 546 There are 3 methods to use
 547 .Cm :set .
 548 When used by itself as
 549 .Cm :set
 550 the command displays all options as currently set.
 551 .Pp
 552 To set a value use
 553 .Cm :set option=value .
 554 For example,
 555 .Cm :set http_proxy=http://127.0.0.1:8080 .
 556 .Pp
 557 To clear a value use
 558 .Cm :set option= .
 559 For example,
 560 .Cm :set http_proxy= .
 561 .Pp
 562 Note, not all options can be set at runtime.
 563 .It Cm stats
 564 Show blocked cookie statistics.
 565 These statistics vary based on settings and are not persistent.
 566 .It Cm statustoggle , statust
 567 Toggle status bar.
 568 .It Cm tabclose , tabc
 569 Close current tab.
 570 .It Cm tabhide
 571 Hide tabs.
 572 .It Cm tabnew , tabedit , tabe URL
 573 Create new tab and optionally open provided URL.
 574 .It Cm tabnext , tabn
 575 Go to the next tab.
 576 .It Cm tabprevious , tabp
 577 Go to the previous tab.
 578 .It Cm tabshow
 579 Show tabs.
 580 .It Cm toplevel , toplevel toggle
 581 Toggle the top level domain name cookie and JS session whitelist.
 582 This is to enable/disable short lived full site functionality without
 583 permanently adding the top level domain to the persistent whitelist.
 584 .It Cm urlhide , urlh
 585 Hide url entry and tool bar.
 586 .It Cm urlshow , urls
 587 Show url entry and tool bar.
 588 .It Cm w
 589 Save open tabs to current session.
 590 The tabs will be restored next time the session is opened.
 591 See the session command for additional details.
 592 .It Cm wq
 593 Save open tabs and quit.
 594 The tabs will be restored next time
 595 .Nm
 596 the session is opened.
 597 See the session command for additional details.
 598 .El
 599 .Sh BUFFER COMMANDS
 600 In addition to shortcuts and commands
 601 .Nm
 602 provides buffer commands. Buffer commands are short, multi character
 603 vi-like commands, often requiring an argument. Partial buffer commands
 604 are
 605 displayed in the buffer command statusbar element (see
 606 .Cm statusbar_elems ) .
 607 Pressing Esc or switching to another tab cancels a partially entered
 608 buffer command. In the following list
 609 .Cm arg
 610 denotes the argument a buffer command accepts. Buffer commands are
 611 defined as extended regular experssions.
 612 Note that if a character is used as a shortcut it will not be interpreted
 613 as the beginning of a buffer command. This is the case with
 614 .Cm 0 .
 615 .Pp
 616 .Bl -tag -width "['][a-zA-Z0-9]XXX" -offset indent -compact
 617 .It Cm gg
 618 go to the top of the page
 619 .It Cm gG
 620 go to the bottom of the page
 621 .It Cm [0-9]+%
 622 go to the
 623 .Cm arg
 624 percent of the page
 625 .It Cm [0-9]*gU
 626 go
 627 .Cm arg
 628 levels up. If
 629 .Cm arg
 630 is missing, 1 is assumed. Going a
 631 level up means going to a uri obtained from the current one by removing
 632 the last slash ('/') character and everything that follows it
 633 .It Cm gh
 634 open the home page in the current tab
 635 .It Cm m[a-zA-Z0-9]
 636 set a mark denoted by
 637 .Cm arg
 638 at the current page position. These marks behave like those in vi or
 639 less.
 640 .It Cm ['][a-zA-Z0-9]
 641 go to the position where mark
 642 .Cm arg
 643 was set
 644 .It Cm M[a-zA-Z0-9]
 645 set the current uri as quickmark
 646 .Cm arg
 647 .It Cm go[a-zA-Z0-9]
 648 open the uri marked as quickmark
 649 .Cm arg
 650 in the current tab
 651 .It Cm gn[a-zA-Z0-9]
 652 open the uri marked as quickmark
 653 .Cm arg
 654 in a new tab
 655 .It Cm [0-9]+t
 656 activate tab number
 657 .Cm arg
 658 .It Cm ZZ
 659 quit
 660 .Nm
 661 .It Cm ZR
 662 restart
 663 .Nm
 664 .It Cm zi
 665 zoom in by 4%
 666 .It Cm zo
 667 zoom out by 4%
 668 .It Cm z0
 669 set zoom level to 100%
 670 .It Cm [0-9]+Z
 671 set zoom level to
 672 .Cm arg
 673 %
 674 .El
 675 .Sh QUICKMARKS
 676 Quickmarks are like bookmarks, except they are refered to by a single
 677 character (a letter or a digit), instead of a longer name. See the
 678 .Cm M[a-zA-Z0-9] ,
 679 .Cm go[a-zA-Z0-9]
 680 and
 681 .Cm gn[a-zA-Z0-9]
 682 buffer commands for usage. Quickmarks are stored in
 683 .Pa ~/.xxxterm/quickmarks
 684 and are saved automatically after each
 685 .Cm M[a-zA-Z0-9]
 686 buffer command.
 687 .Sh ABOUT SCREENS
 688 The about screens are internally generated web pages by
 689 .Nm
 690 for user interaction.
 691 These are entered in the address bar and the format is
 692 .Cm about:screen
 693 where screen is the desired screen to display.
 694 For example about:favorites.
 695 Any about screen can be used as the home page as specified by
 696 .Cm home
 697 in the configuration file.
 698 .Pp
 699 .Bl -tag -width "downloadsXXX" -offset indent -compact
 700 .It Cm about
 701 show the about screen
 702 .It Cm blank
 703 show a blank screen
 704 .It Cm cookiewl
 705 show the cookie whitelist screen
 706 .It Cm cookiejar
 707 show the cookiejar screen
 708 .It Cm downloads
 709 show the downloads screen
 710 .It Cm favorites
 711 show the favorites screen
 712 .It Cm help
 713 show the help web page
 714 .It Cm history
 715 show the history screen
 716 .It Cm jswl
 717 show the Java Script whitelist screen
 718 .It Cm set
 719 show the settings screen
 720 .It Cm stats
 721 show the statistics screen
 722 .El
 723 .Sh WHITELISTS
 724 This section describes advanced usage settings.
 725 Most users should use
 726 .Cm browser_mode
 727 instead to setup
 728 .Nm
 729 and skip over this section.
 730 .Pp
 731 .Nm
 732 has a number of whitelists to control blocking cookies and Java Script
 733 execution for FQDNs or domains.
 734 When properly enabled these whitelists require either the FQDN or top level
 735 domain to exist in the whitelists in order to allow cookies to be stored or
 736 Java Script to execute.
 737 Both Java Script and cookies have two whitelists associated with them.
 738 The whitelists are called session and persistent.
 739 Items in the session whitelists are only allowed for the lifetime of the
 740 .Nm
 741 instance.
 742 Items in the persistent whitelists are stored on disk and are restored
 743 upon restarting.
 744 .Pp
 745 Setting up the whitelists is a little tricky due to intricacies of WebKit.
 746 In fact the semantics are different for cookies and Java Script.
 747 .Pp
 748 Cookie whitelist requires the following configuration to be set:
 749 .Pp
 750 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
 751 .It Cm cookies_enabled
 752 This is a WebKit setting and must be set to
 753 .Pa 1
 754 (ENABLED)
 755 in order to be able to use a
 756 cookie whitelist.
 757 .It Cm enable_cookie_whitelist
 758 This needs to be set to
 759 .Pa 1
 760 to enable the cookie whitelist functionality.
 761 .It Cm cookie_wl
 762 These entries in the configuration file are the actual domains names in the
 763 cookie whitelist.
 764 .El
 765 .Pp
 766 Java Script whitelist requires the following configuration to be set:
 767 .Pp
 768 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
 769 .It Cm enable_scripts
 770 This is a WebKit setting and must be set to
 771 .Pa 0
 772 (DISABLED)
 773 in order to be able to use a
 774 Java Script whitelist.
 775 .It Cm enable_js_whitelist
 776 This needs to be set to
 777 .Pa 1
 778 to enable the Java Script whitelist functionality.
 779 .It Cm js_wl
 780 These entries in the configuration file are the actual domains names in the
 781 Java Script whitelist.
 782 .El
 783 .Pp
 784 Plugin whitelist requires the following configuration to be set:
 785 .Pp
 786 .Bl -tag -width "enable_plugin_whitelistXXX" -offset indent -compact
 787 .It Cm enable_plugins
 788 This is a WebKit setting and must be set to
 789 .Pa 1
 790 (ENABLED)
 791 in order to be able to use a
 792 plugin whitelist.
 793 .It Cm enable_plugin_whitelist
 794 This needs to be set to
 795 .Pa 1
 796 to enable the plugin whitelist functionality.
 797 .It Cm pl_wl
 798 These entries in the configuration file are the actual domains names in the
 799 plugin whitelist.
 800 .El
 801 .Pp
 802 See the
 803 .Pa FILES
 804 section for additional configuration file entries and details
 805 that alter runtime behavior.
 806 .Sh FILES
 807 .Bl -tag -width "/etc/xxxterm.confXXX" -compact
 808 .It Pa ~/.xxxterm.conf
 809 .Nm
 810 user specific settings.
 811 .It Pa ~/.xxxterm
 812 .Nm
 813 scratch directory.
 814 .El
 815 .Pp
 816 .Nm
 817 tries to open the user specific file,
 818 .Pa ~/.xxxterm.conf .
 819 If that file is unavailable,
 820 it then uses built-in defaults.
 821 .Pp
 822 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
 823 For example:
 824 .Pp
 825 .Dl http_proxy = http://127.0.0.1:8080
 826 .Pp
 827 Enabling or disabling an option is done by using 1 or 0 respectively.
 828 .Pp
 829 The file supports the following keywords:
 830 .Pp
 831 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
 832 .It Cm alias
 833 Defines an alias for a given URL, so that the URL is loaded when the alias is
 834 entered in the address bar.
 835 If the aliased URL includes a %s format specifier, then any argument given after
 836 the alias on the address bar is substituted.
 837 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
 838 then the URL http://www.google.com/search?q=foo is loaded when navigating to
 839 "g foo".
 840 .It Cm allow_volatile_cookies
 841 If set cookies are stored in the session cache but will be discarded once
 842 .Nm
 843 exits.
 844 Unfortunately enabling this does allow for some limited tracking on the web.
 845 .It Cm append_next
 846 When set a new tab is appended after the current tab instead of being appended
 847 as the last tab.
 848 .It Cm browser_mode
 849 The
 850 .Nm
 851 browser has 3 default operating modes:
 852 .Pa normal
 853 (the default),
 854 .Pa whitelist
 855 and
 856 .Pa kiosk .
 857 In the
 858 .Pa normal
 859 mode the browser allows all cookies, plugins and Java Script as any other
 860 browser would.
 861 This means that all cookies are saved to persistent storage and that all
 862 Java Script and plugins run.
 863 .Pp
 864 On the other hand, using the
 865 .Pa whitelist
 866 mode enables whitelists.
 867 This requires the user to add all the required
 868 .Pa cookie_wl ,
 869 .Pa js_wl
 870 and
 871 .Pa pl_wl
 872 items.
 873 If a domain does not appear in the whitelists
 874 .Nm
 875 disallows cookies, Java Script and plugin execution.
 876 .Pp
 877 In
 878 .Pa kiosk
 879 mode the browse works just like
 880 .Pa normal
 881 mode however the toolbar only has the backward, forward and home button.
 882 .Pp
 883 This setting must be the first entry in
 884 .Pa ~/.xxxterm.conf
 885 because it sets advanced settings that can be overridden later in the file.
 886 See the default config file for more details.
 887 .It Cm cmd_font
 888 Set the command prompt font.
 889 E.g.
 890 .Pa cmd_font = monospace normal 9 .
 891 .It Cm cookie_policy
 892 This field delineates the cookie policy.
 893 Possible values are: no3rdparty, reject 3rd party cookies.
 894 accept, accept all cookies.
 895 reject, reject all cookies.
 896 .It Cm cookie_wl
 897 This is a cookie whitelist item.
 898 Use multiple times to add multiple entries.
 899 Valid entries are for example *.moo.com and the equivalent .moo.com.
 900 A fully qualified host is also valid and is for example www.moo.com.
 901 .It Cm cookies_enabled
 902 Enable cookies.
 903 .It Cm ctrl_click_focus
 904 Give focus in newly created tab instead of opening it in the background.
 905 .It Cm default_script
 906 Path to the script used as the default value for the run_script
 907 command.
 908 .It Cm default_zoom_level
 909 Set the default browsing zoom level.
 910 .It Cm download_dir
 911 Locations where files are downloaded to.
 912 This directory must exist and
 913 .Nm
 914 validates that during startup.
 915 .It Cm enable_cookie_whitelist
 916 When enabled all cookies must be in the whitelist or they are rejected.
 917 Additionally whitelisted cookies also enable HTML5 local storage for the
 918 domain.
 919 .It Cm enable_js_whitelist
 920 When enabled all domains must be in the js whitelist in order to run Java
 921 Script.
 922 NOTE: Make sure
 923 .Cm enable_scripts
 924 is set to 0.
 925 .It Cm enable_plugin_whitelist
 926 When enabled all domains must be in the plugin whitelist in order to run
 927 plugins.
 928 NOTE: Make sure
 929 .Cm enable_plugins
 930 is set to 0.
 931 .It Cm enable_plugins
 932 Enable external plugins such as Flash and Java.
 933 .It Cm enable_scripts
 934 Enable Java Script.
 935 .It Cm enable_socket
 936 When enabled the first instance of
 937 .Nm
 938 will create a socket in the
 939 .Pa ~/.xxxterm
 940 directory.
 941 Using the -n url option on subsequent
 942 .Nm
 943 invocations will cause the specified URL to be loaded in a new tab.
 944 Only a user with identical UID and GID can use this option.
 945 .It Cm enable_localstorage
 946 Enable html5 Local Storage.
 947 .It Cm enable_spell_checking
 948 Enables spell checking. Preferred languages can be set using
 949 .Cm spell_check_languages
 950 option.
 951 .It Cm encoding
 952 Set the default encoding.
 953 E.g.
 954 .Pa encoding = ISO-8859-1 .
 955 .It Cm fancy_bar
 956 Enables a backward, forward, and stop button to the toolbar.
 957 Additionally if
 958 .Cm search_string
 959 is set it'll enable an entry box for searches.
 960 .It Cm guess_search
 961 When enabled
 962 .Nm
 963 will try to guess if the string you entered, in the URI entry widget or
 964 the command widget, is term you want to search for using search_string
 965 (see above).
 966 If the string does not contain a dot nor a slash, is not a
 967 path to a local file and does not resolves to an IP then it is assumed
 968 to be a search term.
 969 .It Cm history_autosave
 970 When enabled
 971 .Nm
 972 will save all command and search history.
 973 Upon restarting
 974 .Nm
 975 the saved command and search history will be restored.
 976 .It Cm home
 977 Homepage in URL format.
 978 .It Cm http_proxy
 979 Proxy server in URL format.
 980 .Nm
 981 overrides
 982 .Cm http_proxy
 983 if it is specified as an environment variable.
 984 It must be noted that on older webkit versions one MUST use an IP address and
 985 not a FQDN.
 986 This works as expected with webkit 1.4.2.
 987 .Pp
 988 If one desires to use a socks proxy then an intermediary tool must be used.
 989 It has been reported that tsocks works with
 990 .Nm .
 991 .It Cm icon_size
 992 Permits icon sizes to be changed if
 993 .Cm fancy_bar
 994 is enabled.
 995 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
 996 .It Cm js_wl
 997 This is a Java Script whitelist item.
 998 See
 999 .Cm cookie_wl
1000 for semantics and more details.
1001 .It Cm max_connections
1002 The maximum number of connections that
1003 .Nm
1004 can open at once.
1005 .It Cm max_host_connections
1006 The maximum number of connections that
1007 .Nm
1008 can open at once to a given host.
1009 .It Cm mime_type
1010 Sets an action for a specific or default MIME type.
1011 For example, to download and view a pdf using kpdf set
1012 .Pa mime_type = application/pdf,kpdf .
1013 To set a default value use *, for example,
1014 .Pa mime_type = video/*,mplayer .
1015 Note that the action is only passed the URL and not all applications are
1016 capable of dealing with a URL and therefore one might have to create a wrapper
1017 script to download the content first.  Alternatively one can add the
1018 .Pa @
1019 in front of the MIME type to indicate "download first".
1020 For example,
1021 .Pa mime_type = @application/pdf,xpdf .
1022 When
1023 .Pa @
1024 is use the file will be downloaded to the
1025 .Pa download_dir
1026 before the MIME handler is called.
1027 .It Cm oops_font
1028 Set the font used to display error messages.
1029 E.g.
1030 .Pa oops_font = monospace normal 9 .
1031 .It Cm pl_wl
1032 This is a plugin whitelist item.
1033 See
1034 .Cm cookie_wl
1035 for semantics and more details.
1036 .It Cm read_only_cookies
1037 Mark cookies file read-only and discard all cookies once the session is
1038 terminated.
1039 .It Cm refresh_interval
1040 Refresh interval while in the download manager.
1041 The default is 10.
1042 .It Cm resource_dir
1043 Directory that contains various
1044 .Nm
1045 resources such as icons.
1046 This is OS-specific and should be handled by the porter.
1047 .It Cm save_global_history
1048 If set the global history will be saved to
1049 .Pa ~/.xxxterm/history
1050 when quitting
1051 and restored at startup.
1052 See the
1053 .Sx KEY BINDINGS
1054 section above for how the global history is accessed.
1055 Global history is not saved to disk by default.
1056 .It Cm save_rejected_cookies
1057 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
1058 All cookies are saved and unlike a cookie jar they are never replaced.
1059 Make sure there is enough disk space to enable this feature.
1060 .It Cm search_string
1061 Default search engine string.
1062 See the
1063 .Pa xxxterm.conf
1064 file for details.
1065 .It Cm session_autosave
1066 Enable session auto-saving when changing state (e.g. adding or removing a tab).
1067 The session name is what is currently in use and is described in the
1068 .Cm session save
1069 and
1070 .Cm session open
1071 commands.
1072 .It Cm session_timeout
1073 This value is the time that is added in seconds to a session cookie.
1074 .It Cm show_tabs
1075 Enable or disable showing tabs.
1076 .It Cm show_url
1077 Enable or disable showing the url and toolbar.
1078 .It Cm show_statusbar
1079 Enable or disable showing the status bar.
1080 .It Cm single_instance
1081 If set only one
1082 .Nm
1083 will be permitted to run.
1084 If there is a URL specified it will be opened in a new tab in the already
1085 running
1086 .Nm
1087 session.
1088 .It Cm spell_check_languages
1089 The languages to be used for spell checking, separated by commas. For example,
1090 en_US.
1091 .It Cm ssl_ca_file
1092 If set to a valid PEM file
1093 all server certificates will be validated against it.
1094 The URL bar will be colored green (or blue when saved ) when the certificate is
1095 trusted and yellow when untrusted.
1096 .Pp
1097 If
1098 .Cm ssl_ca_file
1099 is not set then the URL bar will color all HTTPS connections red.
1100 .Pp
1101 WebKit only supports a single PEM file.
1102 Many OS' or distributions have many PEM files.
1103 One can simply concatenate all separate files into one large one.
1104 E.g.
1105 .Cm for i in `ls`; do cat $i >> cert.pem; done
1106 and use the resulting cert.pem file as the input to
1107 .Cm ssl_ca_file .
1108 It is advisable to periodically recreate the cert.pem file.
1109 .It Cm ssl_strict_certs
1110 If this value is set connections to untrusted sites will be aborted.
1111 This value is only used if
1112 .Cm ssl_ca_file
1113 is set.
1114 .It Cm statusbar_elems
1115 Define the components of the status bar. The possible components are:
1116 .Bd -literal -offset indent
1117 | - separator
1118 P - page progress percent
1119 B - buffer command
1120 Z - page zoom level
1121 .Ed
1122 The default is "BP".
1123 These components show nothing if there is nothing worth showing, like
1124 zoom amount 100%.
1125 .It Cm statusbar_font
1126 Set the status bar font.
1127 E.g.
1128 .Pa statusbar_font = monospace normal 9 .
1129 .It Cm tab_style
1130 Set the tab style to either
1131 .Cm normal
1132 - the default gtk notebook tabs, or
1133 .Cm compact
1134 for an alternative.
1135 You can switch the tab style with the
1136 .Pa tabnextstyle
1137 command.
1138 .It Cm tabbar_font
1139 Set the compact tab bar font.
1140 E.g.
1141 .Pa tabbar_font = monospace normal 9 .
1142 .It Cm url_regex
1143 This is the regular expression that is used to match what constitutes a valid
1144 URL when using
1145 .Pa guess_search .
1146 .It Cm user_agent
1147 Set to override the default
1148 .Nm
1149 user-agent string.
1150 .It Cm window_height
1151 Set the default height of the browser window.
1152 .It Cm window_width
1153 Set the default width of the browser window.
1154 .It Cm work_dir
1155 Set the work directory where all
1156 .Nm
1157 scratch files are stored.
1158 Default is
1159 .Cm ~/.xxxterm .
1160 .It Cm xterm_workaround
1161 When enabled
1162 .Nm
1163 will look additionally at CUT_BUFFER0 if PRIMARY clipboard is empty.
1164 Additionally when the PRIMARY clipboard is cleared it will copy CUT_BUFFER0
1165 into the PRIMARY clipboard.
1166 Default is 0.
1167 .El
1168 .Sh HISTORY
1169 .Nm
1170 was inspired by vimprobable2 and the bloat in other
1171 .Ux
1172 web browsers.
1173 .Sh AUTHORS
1174 .An -nosplit
1175 .Nm
1176 was written by
1177 .An Marco Peereboom Aq marco@peereboom.us ,
1178 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
1179 .An Edd Barrett Aq vext01@gmail.com ,
1180 .An Todd T. Fries Aq todd@fries.net ,
1181 .An Raphael Graf Aq r@undefined.ch ,
1182 and
1183 .An Michal Mazurek Aq akfaew@jasminek.net .
1184 .Sh BUGS
1185 When
1186 .Cm save_global_history
1187 is enabled
1188 .Nm
1189 is supposed to, in addition to restoring the global history, color the
1190 visited links accordingly; however due to bug #51747 in WebKit this does
1191 not happen.