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