.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.
.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.
.It Sy Ctrl + d
Open the download manager.
.It Sy Ctrl + o
Focus the location bar.
.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 , Ctrl + Shift + n
Repeat the last search
.Pq backward .
.It Sy Ctrl + c
Reload trusted certificates.
.It Sy Ctrl + k / Ctrl + j
Select tab to the left / right.
.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.
.It Sy Middle mouse
Open the link under the pointer in a new window.
.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.
.It Sy Return
Commit, i.e. begin searching or open the URI.
.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
.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.
.Pp
.Nm
comes with the following extensions:
.Bl -tag
.It Sy we_adblock.so
Generic adblock. Reads patterns from the file
.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
.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