diff options
| -rw-r--r-- | man1/lariza.1 | 215 | ||||
| -rw-r--r-- | man1/lariza.usage.1 | 338 |
2 files changed, 272 insertions, 281 deletions
diff --git a/man1/lariza.1 b/man1/lariza.1 index e0294db..3b169d1 100644 --- a/man1/lariza.1 +++ b/man1/lariza.1 @@ -1,119 +1,108 @@ -.TH lariza 1 "2021-01-03" "lariza" "User Commands" -.\" -------------------------------------------------------------------- -.SH NAME -lariza \- simple web browser -.\" -------------------------------------------------------------------- -.SH SYNOPSIS -\fBlariza\fP -[\fB\-C\fP] -[\fIURI ...\fP] -.\" -------------------------------------------------------------------- -.SH DESCRIPTION -\fBlariza\fP is a simple web browser using GTK+ 3, GLib and WebKit2GTK+. -.\" -------------------------------------------------------------------- -.SH OPTIONS -In addition to the standard arguments of GTK+ 3, \fBlariza\fP knows -about the following options: -.TP -\fB\-C\fP +.Dd Jul 17, 2021 +.Dt lariza 1 +.Sh NAME +.Nm lariza +.Nd simple web browser +.Sh SYNOPSIS +.Nm +.Op Fl C +.Op Ar URI... +.Sh DESCRIPTION +.Nm +is a simple web browser using GTK+3, GLib and Webkit2GTK+ +.Sh OPTIONS +In addition to the standard arguments of GTK+3, +.Nm +knows about the following options: +.Bl -tag +.It Fl C Disables cooperative instances. -.P -After these options there can be any number of URIs. If no URIs are -given, $\fBLARIZA_HOME_URI\fP will be opened. -.\" -------------------------------------------------------------------- -.SH ENVIRONMENT -In addition to the standard variables of GTK+ 3, \fBlariza\fP knows -about the following environment variables: -.P -.TP -\fBLARIZA_ACCEPTED_LANGUAGE\fP -In HTTP requests, WebKit sets the \(lqAccepted-Language\(rq header to -this value. Defaults to \fBen-US\fP. -.TP -\fBLARIZA_DOWNLOAD_DIR\fP -All downloads are automatically stored in this directory. If you want to -stick to XDG directories, then you should configure your -\(lqxdg-user-dirs\(rq and use this: - -\f(CW -.nf -\&LARIZA_DOWNLOAD_DIR=$(xdg-user-dir DOWNLOAD) -.fi -\fP - -This variable defaults to \fB/var/tmp\fP. -.TP -\fBLARIZA_ENABLE_CONSOLE_TO_STDOUT\fP +.El +.Pp +After these options there can be any number of +.Ar URIs . +If no +.Ar URIs +are given, $\fBLARIZA_HOME_URI\fP will be opened. +.Sh ENVIRONMENT +In addition to the standard variables of GTK+3, +.Nm +knows about the following environment variables: +.Bl -tag +.It Sy LARIZA_ACCEPTED_LANGUAGE +In HTTP requests, WebKit sets the +.Dq Accepted-Language +header to this value. Defaults to +.Sy en-US . +.It Sy LARIZA_DOWNLOAD_DIR +All downloads are automatically stored in this directory. This variable defaults +to +.Pa /var/tmp . +.It Sy LARIZA_ENABLE_CONSOLE_TO_STDOUT Enable writing WebKit console messages to stdout. -.TP -\fBLARIZA_FIFO_SUFFIX\fP -Cooperative instances are implemented using a named pipe in the file -system. The name of this pipe usually is (at least on modern systems -following XDG \(lqstandards\(rq): -\fI/var\:/run\:/user\:/$UID\:/lariza.fifo\:-$LARIZA_FIFO_SUFFIX\fP. - -$\fBUID\fP is the id of your user. $\fBLARIZA_FIFO_SUFFIX\fP defaults to -\fBmain\fP. If you change this variable, you can launch several -independent cooperative instances of \fBlariza\fP. -.TP -\fBLARIZA_HISTORY_FILE\fP -If set, \fBlariza\fP will write each visited URI to that file. This path -can point to a named pipe, but be aware that the browser will block -until a reader at the other end of the pipe has read all pending data. -.TP -\fBLARIZA_HOME_URI\fP -This URI will be opened by pressing the appropriate hotkeys -(\(lqhomepage\(rq or \(lqnew window\(rq) and if no URIs are specified on -the command line. Defaults to \fBabout:blank\fP. -.TP -\fBLARIZA_TAB_POS\fP -Can be one of \fBtop\fP (default), \fBright\fP, \fBbottom\fP, -\fBleft\fP. -.TP -\fBLARIZA_TAB_WIDTH_CHARS\fP +.It Sy LARIZA_FIFO_SUFFIX +Cooperative instances are implemented using a named pipe in the file system. The +name of this pipe usually is +.Pq at least on modern systems following XDG Dq standards : +.Pa /var/run/user/$UID/lariza.fifo-$LARIZA_FIFO_SUFFIX . +.Pp +.Sy $UID +is the id of your user. +.Sy $LARIZA_FIFO_SUFFIX +defaults to +.Sy main . +If you change this variable, you can launch several independent cooperative +instances of +.Nm . +.It Sy LARIZA_HISTORY_FILE +If set, +.Nm +will write each visited URI to that file. This path can point to a named pipe, +but be aware that the browser will block until a reader at the other end of the +pipe has read all pending data. +.It Sy LARIZA_HOME_URI +This URI will be opened by pressing the appropriate hokeys +.Pq Do homepage Dc or Do new window Dc +and if no URIs are specified on the command line. Defaults to +.Sy about:blank . +.It Sy LARIZA_TAB_POS +Can be one of +.Sy top +.Pq default , +.Sy right , bottom, left . +.It Sy LARIZA_TAB_WIDTH_CHARS An integer, determines width of tabs. Defaults to 20. -.TP -\fBLARIZA_USER_AGENT\fP -\fBlariza\fP will identify itself with this string. Uses WebKit's -default value if unset. -.TP -\fBLARIZA_ZOOM -Zoom level for WebKit viewports. Defaults to \fB1.0\fP. -.\" -------------------------------------------------------------------- -.SH FILES +.It Sy LARIZA_USER_AGENT +.Nm +will identify itself with this string. Uses WebKit's default value if unset. +.It Sy LARIZA_ZOOM +Zoom level for WebKit viewports. Defaults to 1.0. +.El +.Sh FILES XDG variables will be used to construct these paths. -.TP -\fI~/.config\:/lariza\:/adblock\fP -Adblock patterns. See \fBlariza.usage\fP(1). -.TP -\fI~/.config\:/lariza\:/certs\fP +.Bl -tag +.It Pa ~/.config/lariza/adblock +Adblock patterns. See +.Xr lariza.usage 1 . +.It Pa ~/.config/lariza/certs Directory where trusted certificates are stored. See -\fBlariza.usage\fP(1). -.TP -\fI~/.config\:/lariza\:/scripts\fP +.Xr lariza.usage 1 . +.It Pa ~/.config/lariza/scripts Directory to store user-supplied JavaScript snippets. See -\fBlariza.usage\fP(1). -.TP -\fI~/.local\:/share\:/lariza\:/web_extensions\fP -Sets the directory where WebKit will look for web extensions. See -\fBlariza.usage\fP(1). -.TP -\fI~/.cache\:/lariza\fP -.TQ -\fI~/.cache\:/webkitgtk\fP -.TQ -\fI~/.local\:/share\:/webkitgtk\fP -WebKitGTK will dump its caches and local storage here. It is probably -wise to clean those directories regularly or to mount them as -\fBtmpfs\fP(5). -.\" -------------------------------------------------------------------- -.SH LICENSE -\fBlariza\fP is released under the MIT license. See the accompanying -\fILICENSE\fP file. -.\" -------------------------------------------------------------------- -.SH HISTORY -\fBlariza\fP was originally written by Peter Hofmann. The project -was started in June 2014. -.\" -------------------------------------------------------------------- -.SH "SEE ALSO" -.BR lariza.usage (1). +.Xr lariza.usage 1 . +.It Pa ~/.cache/lariza , ~/.cache/webkitgtk , ~/.local/share/webkitgtk +WebKitGTK will dump its caches and local storage here. +.It Pa ~/.cache/lariza/cookies.txt +.Nm +will save its cookies in this text file. +.El +.Sh LICENSE +.Nm +is released under the MIT license. See the accompanying +.Pa LICENSE +file. +.Sh HISTORY +.Nm +was originally written by Peter Hofmann. The project was started in June 2014. +.Sh SEE ALSO +.Xr lariza.usage 1 diff --git a/man1/lariza.usage.1 b/man1/lariza.usage.1 index 3682c60..86651f4 100644 --- a/man1/lariza.usage.1 +++ b/man1/lariza.usage.1 @@ -1,183 +1,185 @@ -.TH lariza 1 "2021-01-03" "lariza" "User Commands" -.\" -------------------------------------------------------------------- -.SH NAME -lariza.usage \- extended usage hints -.\" -------------------------------------------------------------------- -.SH DESCRIPTION -\fBlariza\fP is a simple web browser using GTK+ 3, GLib and WebKit2GTK+. -This manpage contains additional hints and pointers regarding its usage. -.\" -------------------------------------------------------------------- -.SH "HOTKEYS" -.SS "Global hotkeys" +.Dd Jul 17, 2021 +.Dt lariza.usage 1 +.Sh NAME +.Nm lariza +.Nd extended usage hints +.Sh DESCRIPTION +.Nm +is a simple web browser using GTK+3, GLib and WebKit2GTK+. This manpage contains +additional hints and pointers regarding its usage. +.Sh HOTKEYS +.Ss Global hotkeys These hotkeys work when either the location bar or the web view is being focused. -.TP -\fBMod1\fP + \fBq\fP -Close the current window. Quits the entire program if this was the last -window and if there are no more active downloads (download manager is -shown otherwise). -.TP -\fBMod1\fP + \fBw\fP -Go to your \(lqhomepage\(rq. See the environment variable -$\fBLARIZA_HOME_URI\fP. -.TP -\fBMod1\fP + \fBe\fP -Open a new window. -.TP -\fBMod1\fP + \fBr\fP +.Bl -tag +.It Sy Ctrl + q +Close the current window. Quits the entire program if this was the last window +and if there are no more active downloads +.Pq download manager is shown otherwise . +.It Sy Ctrl + w +Go to your +.Dq homepage . +See the environment variable +.Sy $LARIZA_HOME_URI . +.It Sy Ctrl + t +Open a new window . +.Ir Sy Ctrl + r Reload the current page. -.TP -\fBMod1\fP + \fBd\fP +.It Sy Ctrl + d Open the download manager. -.TP -\fBMod1\fP + \fBl\fP +.It Sy Ctrl + o Focus the location bar. -.TP -\fBMod1\fP + \fBk\fP -Focus the location bar and set its text to \fB:/\fP, allowing you to -easily initiate a search. -.TP -\fBMod1\fP + \fB2\fP -.TQ -\fBMod1\fP + \fBn\fP -Repeat the last search (forward). -.TP -\fBMod1\fP + \fB3\fP -Repeat the last search (backward). -.TP -\fBMod1\fP + \fBc\fP +.It Sy Ctrl + f +Focus the location bar and set its text to +.Dq :/ , +allowing you to easily initiate a search. +.It Sy Ctrl + s +Focus the location bar and set its text to +.Dq !/ , +allowin you to search through the search engine. +.It Sy Ctrl + 2 , Ctrl + n +Repeat the last search +.Pq forward . +.It Sy Ctrl + 3 +Repeat the last search +.Pq backward . +.It Sy Ctrl + c Reload trusted certificates. -.TP -\fBMod1\fP + \fBa\fP / \fBMod1\fP + \fBs\fP +.It Sy Ctrl + k / Ctrl + j Select tab to the left / right. -.TP -\fBF2\fP / \fBF3\fP -Go backward and forward in current browser history. -.P -.SS "Main window \(em WebKit viewport focused" -.TP -\fBEscape\fP +.It Sy F2 / F3 +Go backward / forward in current browser history. +.El +.Ss Main window - WebKit viewport focused +.Bl -tag +.It Sy Escape Stop loading. -.TP -\fBMiddle mouse\fP +.It Sy Middle mouse Open the link under the pointer in a new window. -.TP -\fBBackward\fP / \fBforward\fP (mouse keys 8 and 9) -Same as \fBF2\fP and \fBF3\fP. -.TP -\fBMod1\fP + \fBScroll up\fP -.TQ -\fBCtrl\fP + \fBScroll up\fP -Increase zoom level of the current page. -.TP -\fBMod1\fP + \fBScroll down\fP -.TQ -\fBCtrl\fP + \fBScroll down\fP -Decrase zoom level of the current page. -.TP -\fBMod1\fP + \fBScroll horizontally\fP -.TQ -\fBCtrl\fP + \fBScroll horizontally\fP -Reset zoom to $\fBLARIZA_ZOOM\fP. -.P -.SS "Main window \(em location bar focused" -.TP -\fBEscape\fP +.It Sy Backward / forward Pq mouse keys 8 and 9 +Same as F2 and F3. +.It Sy Ctrl + Scroll up / down +Increase / decrease zoom level of the current page. +.It Sy Ctrl + Scroll horizontally +Reset zoom to +.Sy $LARIZA_ZOOM . +.El +.Ss Main window - location bar focused +.Bl -tag +.It Sy Escape Reset the content of the location bar to the current URI. -.TP -\fBReturn\fP +.It Sy Return Commit, i.e. begin searching or open the URI. -.P -.SS "Download manager" -.TP -\fBMod1\fP + \fBd\fP -.TQ -\fBMod1\fP + \fBq\fP -Close the download manager. Active downloads are never aborted. However, -if there are no more active downloads and no more browsing windows, then -the entire program will quit. -.\" -------------------------------------------------------------------- -.SH "DOWNLOAD MANAGER" -Open the download manager using the appropriate hotkey. A new window -listing your downloads will appear. Clicking on an item will remove it -from the list and \(em if needed \(em cancel the download. -.P -There's no file manager integration, nor does \fBlariza\fP delete, -overwrite or resume downloads. If a file already exists, it won't be -touched. Instead, the new file name will have a suffix such as \fB.1\fP, -\fB.2\fP, \fB.3\fP, and so on. -.\" -------------------------------------------------------------------- -.SH "USER-SUPPLIED JAVASCRIPT FILES" +.El +.Ss Download manager +.Bl -tag +.It Sy Ctrl + d , Ctrl + q +Close the download manager. Active downloads are never aborted. However, if +there are no more active downloads and no more browsing windows, then the entire +program will quit. +.Sh DOWNLOAD MANAGER +Open the download manager using the appropriate hotkey. A new window listing +your downloads will appear. Clicking on an item will remove it from the list +and - if needed - cancel the download. +.Pp +There's no file manager integration, nor does +.Nm +delete, overwrite or resume downloads. If a file already exists, it won't be +touched. Instead, the new file name will have a suffix such as +.Sy .1 , .2 , .3 , +and so on. +.Sh USER-SUPPLIED JAVASCRIPT FILES After a page has been successfully loaded, the directory -\fI~/.config\:/lariza\:/user-scripts\fP will be scanned and each file in -it ending with \fB.js\fP will be run as a JavaScript file in the context -of said page. -.P -During development, you will most likely want to run \fBlariza\fP with -$\fBLARIZA_ENABLE_CONSOLE_TO_STDOUT\fP enabled. -.P -\fBlariza\fP comes with the following scripts: -.TP -\fBhints.js\fP -Press \fBf\fP (open link in current window) or \fBF\fP (open in new -window) to activate link hints. After typing the characters for one of -them, press \fBEnter\fP to confirm. Press \fBEscape\fP to abort. -.P -Those bundled scripts are automatically installed on \fBmake install\fP. -To use them, though, make sure to link them to the directory mentioned -above. -.\" -------------------------------------------------------------------- -.SH "WEB EXTENSIONS" -On startup, WebKit checks \fI~/.config/lariza/web_extensions\fP for any -\fB.so\fP files. See -.UR http://\:blogs.igalia.com/\:carlosgc/\:2013/\:09/\:10/\:webkit2gtk-\:web-\:process-\:extensions/ -this blog post -.UE +.Pa ~/.config/lariza/user-scripts +will be scanned and each file in it ending with +.Dq .js +will be run as a JavaScript file in the context of said page. +.Pp +During development, you will most likely want to run +.Nm +with +.Sy $LARIZA_ENABLE_CONSOLE_TO_STDOUT +enabled. +.Pp +.Nm +comes with the following scripts: +.Bl -tag +.It Sy hints.js +Press +.Sy f +.Pq open link in current window +or +.Sy F +.Pq open in new window +to activate link hints. After typing the characters for one of them press +.Sy Return +to confirm. +Press +.Sy Escape +to abort. +.El +.Pp +Those bundled scripts are automatically installed on +.Sy make install . +To use them, though, make sure to link them to the directory mentioned above. +.Sh WEB EXTENSIONS +On startup, WebKit checks +.Pa ~/.config/lariza/web_extensions +for any +.Sy .so +files. See this blog post +.Lk http://blogs.igalia.com/carlosgc/2013/09/10/webkit2gtk-web-process-extensions/ for further information on these extensions. -.P -\fBlariza\fP comes with the following extensions: -.TP -\fBwe_adblock.so\fP +.Pp +.Nm +comes with the following extensions: +.Bl -tag +.It Sy we_adblock.so Generic adblock. Reads patterns from the file -\fI~/.config/lariza/adblock\fP. Each line can contain a regular -expression. These expressions match case-insensitive and partially, i.e. -\fB.*foo.*\fP is the same as \fB.*FOO.*\fP and you can use anchors like -\fB^https?://...\fP. Please refer to -.UR https://\:developer.\:gnome.\:org/\:glib/\:stable/\:glib-\:regex-\:syntax.html -the GLib reference -.UE -for more details. Lines starting with \fB#\fP are ignored. -.P +.Pa ~/.config/lariza/adblock . +Each line can contain a regular expression. These expressions match +case-insensitive and partially, i.e. +.Sy .*foo.* +is the same as +.Sy .*FOO.* +and you can use anchors like +.Sy ^https?://... . +Please refer to the GLib reference +.Lk https://developer.gnome.org/glib/stable/glib-regex-syntax.html +for more details. Lines starting with +.Sy # +are ignored. +.El Those bundled web extensions are automatically compiled when you run -\fBmake\fP and installed on \fBmake install\fP. To use them, though, -make sure to link them to the directory mentioned above. -.\" -------------------------------------------------------------------- -.SH "TRUSTED CERTIFICATES" -By default, \fBlariza\fP trusts whatever CAs are trusted by WebKit. If -you wish to trust additional certificates, such as self-signed -certificates, the first thing you should do is try to add the -appropriate CAs to your system-wide store. -.P -If you wish to add simple exceptions, you can grab the certificate and -store it in the directory \fI~/.config/lariza/certs\fP. The filename -must be equal to the hostname: -.P -\f(CW -.nf -\&$ echo | openssl s_client -connect foo.de:443 | openssl x509 >foo.de -.fi -\fP -.P -This tells \fBlariza\fP to trust the given certificate when connecting -to host \fBfoo.de\fP. -.P -You can reload these certificates at runtime by pressing the appropriate -hotkey. Note that removed certificates will be kept in memory until you -restart \fBlariza\fP. -.P -Note: This is NOT equal to certificate pinning. WebKit ignores -user-specified certificates if the server's certificate can be validated -by any system-wide CA. -.\" -------------------------------------------------------------------- -.SH "SEE ALSO" -.BR lariza (1). +.Sy make +and installed on +.Sy make install . +To use them, though, make sure to link them to the directory mentioned above. +.Sh TRUSTED CERTIFICATES +By default, +.Nm +trusts whatever CAs are trusted by WebKit. If you wish to trust additional +certificates, such as self-signed certificates, the first thing you should do is +try to add the appropriate CAs to your system-wide store. +.Pp +If you wish to add simple exceptions, you can grab the certificate and store it +in the directory +.Pa ~/.config/lariza/certs . +The filename must be equal to the hostname: +.Bd -literal -offset indent +$ echo | openssl s_client -connect foo.de:443 | openssl x504 > foo.de +.Ed +.Pp +This tells +.Nm +to trust the given certificate when connecting to host +.Sy foo.de . +.Pp +You can reload these certificates at runtime by pressing the appropriate hotkey. +Note that removed certificates will be kept in memory until you restart +.Nm . +.Pp +Note: This is NOT equal to certificate pinning. WebKit ignores user-specified +certificates if the server's certificate can be validated by any system-wide CA. +.Sh SEE ALSO +.Xr lariza 1 |