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