xxxterm.1

   1 .\"     $xxxterm$
   2 .\"
   3 .\" Copyright (c) 2010, 2011 Marco Peereboom <marco@peereboom.us>
   4 .\" Copyright (c) 2011 Jason McIntyre <jmc@kerhand.co.uk>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate$
  19 .Dt XXXTERM 1
  20 .Os
  21 .Sh NAME
  22 .Nm xxxterm
  23 .Nd lightweight web browser
  24 .Sh SYNOPSIS
  25 .Nm xxxterm
  26 .Bk -words
  27 .Op Fl nSTtV
  28 .Op Fl f Ar file
  29 .Op Ar url ...
  30 .Ek
  31 .Sh DESCRIPTION
  32 .Nm
  33 is a minimalistic web browser that tries to stay out of the way so that
  34 valuable screen real estate can be used for much more important stuff.
  35 It has sane defaults and does not require one to learn a language to do any
  36 configuration.
  37 It was written by hackers for hackers
  38 and it strives to be small, compact, and fast.
  39 .Pp
  40 .Nm
  41 is very simple in its use.
  42 Most actions are initiated via key or mouse bindings.
  43 Key bindings are based on those of the
  44 .Xr vi 1
  45 text editor,
  46 giving web browsing a similar feel to navigating a text document.
  47 The
  48 .Sx KEY BINDINGS
  49 section below documents the various defaults and possible customizations.
  50 .Pp
  51 The options are as follows:
  52 .Bl -tag -width Ds
  53 .It Fl f Ar file
  54 Specify an alternative configuration file.
  55 .It Fl S
  56 Disable the toolbar.
  57 .It Fl T
  58 Disable visualization of tabs.
  59 .It Fl t
  60 Disable tabs.
  61 .It Fl n
  62 Open a new tab in a running
  63 .Nm
  64 for each specified URL.
  65 This option requires
  66 .Cm enable_socket
  67 to be enabled.
  68 .It Fl V
  69 Display version and exit.
  70 .El
  71 .Sh FAST STARTUP
  72 The following notation is used throughout this page:
  73 .Pp
  74 .Bl -tag -width Ds -offset indent -compact
  75 .It Cm C
  76 Control
  77 .It Cm M
  78 Meta (sometimes marked Alt)
  79 .It Cm M1
  80 Mouse button 1
  81 .It Cm S
  82 Shift
  83 .El
  84 .Pp
  85 To browse to a specific address,
  86 either use the mouse to click on the address bar
  87 or press
  88 .Cm F6
  89 to shift the keyboard focus to the address bar.
  90 The address is then entered manually.
  91 .Pp
  92 The mouse can be used to navigate the page in the traditional manner,
  93 or the keyboard can be used instead.
  94 For example,
  95 .Cm PageUp
  96 and
  97 .Cm PageDown
  98 will scroll up and down the page.
  99 .Pp
 100 To follow a link,
 101 either click on it or use the
 102 .Cm f
 103 key and have
 104 .Nm
 105 assign numbers to each link on the page;
 106 entering that number on the keyboard will prompt
 107 .Nm
 108 to follow the link.
 109 .Sh KEY BINDINGS
 110 .Nm
 111 provides many actions accessed via key or mouse bindings.
 112 Note that WebKit & GTK+ have their own set of key bindings
 113 that are not overruled and therefore are available as-is.
 114 .Ss Search Commands
 115 These commands are used to search for text strings within a web page.
 116 .Pp
 117 .Bl -tag -width Ds -offset indent -compact
 118 .It Cm /
 119 Start a search
 120 .It Cm \&?
 121 Start a backwards search
 122 .It Cm n
 123 Next item matching search
 124 .It Cm N
 125 Previous item matching search
 126 .El
 127 .Ss Focus Commands
 128 These commands are used to shift the focus of
 129 .Nm
 130 from one area to another.
 131 .Pp
 132 .Bl -tag -width Ds -offset indent -compact
 133 .It Cm F6
 134 Focus on address bar
 135 .It Cm F7
 136 Focus on search entry
 137 .El
 138 .Ss Command Aliases
 139 These commands allow the user to map specific actions to specific keys.
 140 It can be useful when the
 141 .Fl S
 142 option is used.
 143 .Pp
 144 .Bl -tag -width Ds -offset indent -compact
 145 .It Cm F9
 146 Alias for ":open"
 147 .It Cm F10
 148 Alias for ":open current-uri"
 149 .It Cm F11
 150 Alias for ":tabnew"
 151 .It Cm F12
 152 Alias for ":tabnew current-uri"
 153 .El
 154 .Ss Navigation Commands
 155 These commands allow the user to navigate web pages and,
 156 to some extent,
 157 control the browser.
 158 .Pp
 159 .Bl -tag -width "Space, C-f, PageDownXXX" -offset indent -compact
 160 .It Cm F5, C-r, C-l
 161 Reload page
 162 .It Cm C-R
 163 Reload page without using any cached data
 164 .It Cm Backspace, M-Left
 165 Previous page
 166 .It Cm S-BackSpace, M-Right
 167 Forward page
 168 .It Cm j, Down
 169 Next line on page
 170 .It Cm k, Up
 171 Previous line on page
 172 .It Cm G, End
 173 Bottom of page
 174 .It Cm gg, Home
 175 Top of page
 176 .It Cm Space, C-f, PageDown
 177 Page down
 178 .It Cm C-b, PageUp
 179 Page up
 180 .It Cm l, Right
 181 Page right
 182 .It Cm h, Left
 183 Page left
 184 .It Cm $
 185 Page far right
 186 .It Cm 0
 187 Page far left
 188 .It Cm M-f
 189 Favorites
 190 .It Cm M-j
 191 Cookie jar
 192 .It Cm M-d
 193 Download manager
 194 .It Cm C-p
 195 Print page
 196 .It Cm M-h
 197 Global history
 198 .It Cm C-j
 199 Toggle Java Script enabled for FQDN.
 200 .It Cm C-s
 201 Toggle source view
 202 .It Cm M-c
 203 Toggle cookie enabled for FQDN.
 204 .El
 205 .Ss Tab Manipulation
 206 .Nm
 207 supports tabbed browsing.
 208 That is, web pages may be opened in separate tabs,
 209 allowing the user to quickly move from one page to another,
 210 and back.
 211 These commands then are used to create, destroy, and move between tabs.
 212 .Pp
 213 .Bl -tag -width "C-plus, C-equalXXX" -offset indent -compact
 214 .It Cm C-M1
 215 Open new tab with the clicked link
 216 .It Cm C-t
 217 Create new tab with focus in URL entry
 218 .It Cm C-w
 219 Destroy current tab
 220 .It Cm U
 221 Undo close tab
 222 .It Cm C-Left
 223 Go to the previous tab
 224 .It Cm C-Right
 225 Go to the next tab
 226 .It Cm C-[1..0]
 227 Jump to page
 228 .Ar N
 229 .It Cm C-minus
 230 Shrink font size by one point
 231 .It Cm C-plus, C-equal
 232 Grow font size by one point
 233 .El
 234 .Ss Yanking and pasting
 235 These commands copy and paste text to and from the clipboard.
 236 .Pp
 237 .Bl -tag -width Ds -offset indent -compact
 238 .It Cm p
 239 Paste the contents of the clipboard into the address bar
 240 .It Cm P
 241 Paste the contents of the clipboard into a new tab
 242 .It Cm y
 243 Yank the current URL into the clipboard
 244 .El
 245 .Ss Hyperlink Following
 246 This allows the user to follow hyperlinks
 247 without using a mouse.
 248 Enter the corresponding number to follow the link.
 249 Alternatively one can type the name of the link and when there are no more
 250 possibilities
 251 .Nm
 252 will follow the link.
 253 .Pp
 254 .Bl -tag -width Ds -offset indent -compact
 255 .It Cm f
 256 Highlight all links and prefix them with a number.
 257 .El
 258 .Ss Exiting
 259 Commands to exit the browser.
 260 .Pp
 261 .Bl -tag -width Ds -offset indent -compact
 262 .It Cm C-Q
 263 Quit
 264 .El
 265 .Sh COMMAND MODE
 266 Command mode works in a similar fashion to the
 267 .Xr vi 1
 268 editor;
 269 it is entered by typing a colon and exited by typing Esc.
 270 The commands and their descriptions are listed below.
 271 .Bl -tag -width Ds -offset indent
 272 .It Cm about , version
 273 Show the "About" page.
 274 .It Cm ca
 275 Display CA certificates.
 276 .It Cm cert , cert show
 277 Download and display certificates of domain on tab.
 278 .It Cm cert save
 279 Save certificate into a local store.
 280 The next time the site is visited it is compared against the store.
 281 If the certificate matches,
 282 the address bar will be blue;
 283 if it doesn't the bar will be red.
 284 .It Cm cookie
 285 The
 286 .Cm cookie
 287 command is used to manipulate the cookie whitelist.
 288 Used by itself it expands to
 289 .Cm cookie show all .
 290 .It Cm cookies
 291 Show cookie jar contents.
 292 .It Cm cookie save, cookie save fqdn
 293 Save the current fully qualified domain name (FQDN)
 294 to the persistent whitelist.
 295 For example,
 296 the www.peereboom.us domain would result in saving .www.peereboom.us.
 297 .It Cm cookie save domain
 298 Save the top level domain name to the persistent whitelist.
 299 For example,
 300 the www.peereboom.us domain would result in saving .peereboom.us.
 301 .Pp
 302 This action enables cookies if it is currently disabled for this entry.
 303 .It Cm cookie show all
 304 Show all persistent and session entries in the cookie whitelist.
 305 .It Cm cookie show persistent
 306 Show all persistent entries in the cookie whitelist.
 307 .It Cm cookie show session
 308 Show all session entries in the cookie whitelist.
 309 .It Cm cookie toggle domain
 310 Toggle cookie support for the current top level domain.
 311 .It Cm cookie toggle, cookie toggle fqdn
 312 Toggle Java Script execution for the current FQDN.
 313 .It Cm dl
 314 Show download manager.
 315 .It Cm fav
 316 Show favorites.
 317 .It Cm favadd
 318 Add the current page to favorites.
 319 .It Cm fullscreen , f
 320 Toggle hiding tabs and url entry toolbar.
 321 .It Cm h , hist , history
 322 Show global history.
 323 .It Cm help
 324 Show help page.
 325 .It Cm home
 326 Go to home URL.
 327 .It Cm js
 328 The
 329 .Cm js
 330 command is used to manipulate the Java Script whitelist.
 331 Used by itself it expands to
 332 .Cm js show all .
 333 .It Cm js save, save fqdn
 334 Saves the FQDN to the persistent whitelist.
 335 For example,
 336 the www.peereboom.us domain would result in saving .www.peereboom.us.
 337 .It Cm js save domain
 338 Saves the top level domain name to the persistent whitelist.
 339 For example,
 340 the www.peereboom.us domain would result in saving .peereboom.us.
 341 .Pp
 342 This action enables Java Script if it is currently disabled for this entry.
 343 .It Cm js show all
 344 Shows all persistent and session entries in the JS whitelist.
 345 .It Cm js show persistent
 346 Shows all persistent entries in the JS whitelist.
 347 .It Cm js show session
 348 Shows all session entries in the JS whitelist.
 349 .It Cm js toggle, js toggle fqdn
 350 Toggle Java Script execution for the current FQDN.
 351 .It Cm js toggle domain
 352 Toggle Java Script execution for the current top level domain.
 353 .It Cm open , op , o URL
 354 Open URL.
 355 .It Cm print
 356 Print page.
 357 .It Cm qa , qa! , q!
 358 Quit
 359 .Nm .
 360 .It Cm quit , q
 361 Close current tab and quit
 362 .Nm
 363 if it is the last tab.
 364 .It Cm restart
 365 Restart
 366 .Nm
 367 and reload all current tabs.
 368 .It Cm session , Cm session show
 369 Display the current session name.
 370 By default the session name is main_session.
 371 To create a new session use the
 372 .Cm session save
 373 command.
 374 A session is defined as the lifetime of the browser application.
 375 .It Cm session delete <session_name>
 376 Delete session session_name from persistent storage.
 377 If session_name is the current session then the session will revert to
 378 main_session.
 379 .It Cm session open <session_name>
 380 Open session_name and close all currently open tabs.
 381 Going forward this session is named session_name.
 382 .It Cm session save <session_name>
 383 Save current tabs to session_name session.
 384 This will close the current session and going forward this session is named
 385 session_name.
 386 .It Cm stats
 387 Show blocked cookie statistics.
 388 These statistics vary based on settings and are not persistent.
 389 .It Cm tabclose , tabc
 390 Close current tab.
 391 .It Cm tabhide , tabh
 392 Hide tabs.
 393 .It Cm tabnew , tabedit , tabe URL
 394 Create new tab and optionally open provided URL.
 395 .It Cm tabnext , tabn
 396 Go to the next tab.
 397 .It Cm tabprevious , tabp
 398 Go to the previous tab.
 399 .It Cm tabshow , tabs
 400 Show tabs.
 401 .It Cm urlhide , urlh
 402 Hide url entry and toolbar.
 403 .It Cm urlshow , urls
 404 Show url entry and toolbar.
 405 .It Cm w
 406 Save open tabs to current session.
 407 The tabs will be restored next time
 408 .Nm
 409 the session is opened.
 410 See the session command for additional details.
 411 .It Cm wq , wq!
 412 Save open tabs and quit.
 413 The tabs will be restored next time
 414 .Nm
 415 the session is opened.
 416 See the session command for additional details.
 417 .El
 418 .Sh WHITELISTS
 419 .Nm
 420 has a number of whitelists to control blocking cookies and Java Script
 421 execution for FQDNs or domains.
 422 When properly enabled these whitelists require either the FQDN or top level
 423 domain to exist in the whitelists in order to allow cookies to be stored or
 424 Java Script to execute.
 425 Both Java Script and cookies have two whitelists associated with them.
 426 The whitelists are called session and persistent.
 427 Items in the session whitelists are only allowed for the lifetime of the
 428 .Nm
 429 instance.
 430 Items in the persistent whitelists are stored on disk and are restored
 431 upon restarting.
 432 .Pp
 433 Setting up the whitelists is a little tricky due to intricacies of WebKit.
 434 In fact the semantics are different for cookies and Java Script.
 435 .Pp
 436 Cookie whitelist requires the following configuration to be set:
 437 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
 438 .It Cm cookies_enabled
 439 This is a WebKit setting and must be set to
 440 .Pa 1 (ENABLED)
 441 in order to be able to use a
 442 cookie whitelist.
 443 .It Cm enable_cookie_whitelist
 444 This needs to be set to
 445 .Pa 1
 446 to enable the cookie whitelist functionality.
 447 .It Cm cookie_wl
 448 These entries in the configuration file are the actual domains names in the
 449 cookie whitelist.
 450 .El
 451 .Pp
 452 Java Script whitelist requires the following configuration to be set:
 453 .Bl -tag -width "enable_js_whitelistXXX" -offset indent -compact
 454 .It Cm enable_scripts
 455 This is a WebKit setting and must be set to
 456 .Pa 0 (DISABLED)
 457 in order to be able to use a
 458 Java Script whitelist.
 459 .It Cm enable_js_whitelist
 460 This needs to be set to
 461 .Pa 1
 462 to enable the Java Script whitelist functionality.
 463 .It Cm js_wl
 464 These entries in the configuration file are the actual domains names in the
 465 Java Script whitelist.
 466 .El
 467 .Pp
 468 See the
 469 .Pa FILES
 470 section for additional configuration file entries and details
 471 that alter runtime behavior.
 472 .PP
 473 .Sh FILES
 474 .Bl -tag -width "/etc/xxxterm.confXXX" -compact
 475 .It Pa ~/.xxxterm.conf
 476 .Nm
 477 user specific settings.
 478 .It Pa ~/.xxxterm
 479 .Nm
 480 scratch directory.
 481 .El
 482 .Pp
 483 .Nm
 484 tries to open the user specific file,
 485 .Pa ~/.xxxterm.conf .
 486 If that file is unavailable,
 487 it then uses built-in defaults.
 488 .Pp
 489 The format of the file is \*(Ltkeyword\*(Gt = \*(Ltsetting\*(Gt.
 490 For example:
 491 .Pp
 492 .Dl http_proxy = http://127.0.0.1:8080
 493 .Pp
 494 Enabling or disabling an option is done by using 1 or 0 respectively.
 495 .Pp
 496 The file supports the following keywords:
 497 .Pp
 498 .Bl -tag -width "enable_cookie_whitelistXXX" -offset indent -compact
 499 .It Cm alias
 500 Defines an alias for a given URL, so that the URL is loaded when the alias is
 501 entered in the address bar.
 502 If the aliased URL includes a %s format specifier, then any argument given after
 503 the alias on the address bar is substituted.
 504 For example, if g,http://www.google.com/search?q=%s is defined as an alias,
 505 then the URL http://www.google.com/search?q=foo is loaded when navigating to
 506 "g foo".
 507 .It Cm allow_volatile_cookies
 508 If set cookies are stored in the session cache but will be discarded once
 509 .Nm
 510 exits.
 511 Unfortunately enabling this does allow for some limited tracking on the web.
 512 .It Cm append_next
 513 When set a new tab is appended after the current tab instead of being appended
 514 as the last tab.
 515 .It Cm cookie_policy
 516 This field delineates the cookie policy.
 517 Possible values are: no3rdparty, reject 3rd party cookies.
 518 accept, accept all cookies.
 519 reject, reject all cookies.
 520 .It Cm cookie_wl
 521 This is a cookie whitelist item.
 522 Use multiple times to add multiple entries.
 523 Valid entries are for example *.moo.com and the equivalent .moo.com.
 524 A fully qualified host is also valid and is for example www.moo.com.
 525 .It Cm cookies_enabled
 526 Enable cookies.
 527 .It Cm ctrl_click_focus
 528 Give focus in newly created tab instead of opening it in the background.
 529 .It Cm default_font_size
 530 Set the default browsing font size.
 531 .It Cm download_dir
 532 Locations where files are downloaded to.
 533 This directory must exist and
 534 .Nm
 535 validates that during startup.
 536 .It Cm enable_cookie_whitelist
 537 When enabled all cookies must be in the whitelist or they are rejected.
 538 .It Cm enable_js_whitelist
 539 When enabled all domains must be in the js whitelist in order to run Java Script.
 540 NOTE: Make sure
 541 .Cm enable_scripts
 542 is set to 0.
 543 .It Cm enable_plugins
 544 Enable plugins.
 545 .It Cm enable_scripts
 546 Enable scripts.
 547 .It Cm enable_socket
 548 When enabled the first instance of
 549 .Nm
 550 will create a socket in the
 551 .Pa ~/.xxxterm
 552 directory.
 553 Using the -n url option on subsequent
 554 .Nm
 555 invocations will cause the specified URL to be loaded in a new tab.
 556 Only a user with identical UID and GID can use this option.
 557 .It Cm fancy_bar
 558 Enables a backward, forward, and stop button to the toolbar.
 559 Additionally if
 560 .Cm search_string
 561 is set it'll enable an entry box for searches.
 562 .It Cm http_proxy
 563 Proxy server in URL format.
 564 .Nm
 565 overrides
 566 .Cm http_proxy
 567 if it is specified as an environment variable.
 568 It must be noted that one MUST use an IP address and not a FQDN.
 569 .Pp
 570 If one desires to use a socks proxy then an intermediary tool must be used.
 571 It has been reported that tsocks works with
 572 .Nm .
 573 .It Cm icon_size
 574 Permits icon sizes to be changed if
 575 .Cm fancy_bar
 576 is enabled.
 577 Size 1 is small; 2 is normal; 3 through 6 are progressively larger.
 578 .It Cm js_wl
 579 This is a Java Script whitelist item.
 580 See
 581 .Cm cookie_wl
 582 for semantics and more details.
 583 .It Cm mime_type
 584 Sets an action for a specific or default MIME type.
 585 For example, to download and view a pdf using kpdf set mime_type =
 586 application/pdf,kpdf.
 587 To set a default value use *, for example mime_type = video/*,mplayer.
 588 Note that the action is only passed the URL and not all applications are
 589 capable of downloading content and therefore one might have to create a wrapper
 590 script to download the content first.
 591 .It Cm read_only_cookies
 592 Mark cookies file read-only and discard all cookies once the session is
 593 terminated.
 594 .It Cm refresh_interval
 595 Refresh interval while in the download manager.
 596 The default is 10.
 597 .It Cm resource_dir
 598 Directory that contains various
 599 .Nm
 600 resources such as icons.
 601 This is OS-specific and should be handled by the porter.
 602 .It Cm save_global_history
 603 If set the global history will be saved to
 604 .Pa ~/.xxxterm/history
 605 when quitting
 606 and restored at startup.
 607 See the
 608 .Sx KEY BINDINGS
 609 section above for how the global history is accessed.
 610 Global history is not saved to disk by default.
 611 .It Cm save_rejected_cookies
 612 Saves rejected cookies in cookie format in {work_dir}/rejected.txt.
 613 All cookies are saved and unlike a cookie jar they are never replaced.
 614 Make sure there is enough disk space to enable this feature.
 615 .It Cm search_string
 616 Default search engine string.
 617 See the
 618 .Pa xxxterm.conf
 619 file for details.
 620 .It Cm session_autosave
 621 Enable session auto-saving when changing state (e.g. adding or removing a tab).
 622 The session name is what is currently in use and is described in the
 623 .Cm session save
 624 and
 625 .Cm session open
 626 commands.
 627 .It Cm session_timeout
 628 This value is the time that is added in seconds to a session cookie.
 629 .It Cm show_tabs
 630 Enable or disable showing tabs.
 631 .It Cm show_url
 632 Enable or disable showing the url and toolbar.
 633 .It Cm single_instance
 634 If set only one
 635 .Nm
 636 will be permitted to run.
 637 If there is a URL specified it will be opened in a new tab in the already
 638 running
 639 .Nm
 640 session.
 641 .It Cm ssl_ca_file
 642 If set to a valid PEM file
 643 all server certificates will be validated against it.
 644 The URL bar will be colored green when the certificate is trusted
 645 and yellow when untrusted.
 646 .Pp
 647 If
 648 .Cm ssl_ca_file
 649 is not set then the URL bar will color all HTTPS connections red.
 650 .It Cm ssl_strict_certs
 651 If this value is set connections to untrusted sites will be aborted.
 652 This value is only used if
 653 .Cm ssl_ca_file
 654 is set.
 655 .It Cm user_agent
 656 Set to override the default
 657 .Nm
 658 user-agent string.
 659 .It Cm window_height
 660 Set the default height of the browser window.
 661 .It Cm window_width
 662 Set the default width of the browser window.
 663 .El
 664 .Sh HISTORY
 665 .Nm
 666 was inspired by vimprobable2 and the bloat in other
 667 .Ux
 668 web browsers.
 669 .Sh AUTHORS
 670 .An -nosplit
 671 .Nm
 672 was written by
 673 .An Marco Peereboom Aq marco@peereboom.us ,
 674 .An Stevan Andjelkovic Aq stevan@student.chalmers.se ,
 675 .An Edd Barrett Aq vext01@gmail.com ,
 676 and
 677 .An Todd T. Fries Aq todd@fries.net .
 678 .Sh BUGS
 679 When
 680 .Cm save_global_history
 681 is enabled
 682 .Nm
 683 is supposed to, in addition to restoring the global history, color the
 684 visited links accordingly; however due to bug #51747 in WebKit this does
 685 not happen.