Add documentation about URI handler to man pages

2 files changed, 37 insertions, 0 deletions

diff --git a/man1/lariza.1 b/man1/lariza.1
index b1254b4..7db3a5e 100644
--- a/man1/lariza.1
+++ b/man1/lariza.1
@@ -102,6 +102,10 @@ Configuration file for keyword base searching. See
 \fI~/.local\:/share\:/lariza\:/web_extensions\fP
 Sets the directory where WebKit will look for web extensions. See
 \fBlariza.usage\fP(1).
+.P
+The executable \fIlariza-external-handler\fP must be located somewhere
+in your $\fBPATH\fP, if you want to make use of the external URI
+handler. See \fBlariza.usage\fP(1) for details.
 .\" --------------------------------------------------------------------
 .SH LICENSE
 \fBlariza\fP is released as \(lqPIZZA-WARE\(rq. See the accompanying
diff --git a/man1/lariza.usage.1 b/man1/lariza.usage.1
index 0b047ea..f89c3db 100644
--- a/man1/lariza.usage.1
+++ b/man1/lariza.usage.1
@@ -45,6 +45,9 @@ touched. Instead, the new file name will have a suffix such as \fB.1\fP,
 .SH "HOTKEYS"
 .SS "Main window \(em WebKit viewport focused"
 .TP
+\fBMod1\fP + \fBx\fP
+Launch the external handler for the currently loaded URI.
+.TP
 \fBMod1\fP + \fBq\fP
 Close the current window.
 .TP
@@ -107,6 +110,9 @@ Reset zoom to $\fBLARIZA_ZOOM\fP.
 .P
 .SS "Main window \(em location bar focused"
 .TP
+\fBMod1\fP + \fBx\fP
+Launch the external handler for the currently loaded URI.
+.TP
 \fBMod1\fP + \fBq\fP
 Close the current window.
 .TP
@@ -176,6 +182,33 @@ 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 "EXTERNAL URI HANDLER"
+\fBlariza\fP can launch an executable called
+\fIlariza-external-handler\fP. It will be passed the \(lqselected\(rq
+URI as a command line argument:
+.P
+.\f(CW
+.nf
+$ lariza-external-handler -u https://github.com
+.fi
+\fP
+.P
+This executable must be a user-supplied program. It can do anything it
+wants to with that URI. \fBlariza\fP ignores the exit code of the
+handler.
+.P
+The \fB\-u\fP will always be set. This allows you to use \fBgetopt\fP(1)
+like parameter parsing in your program.
+.P
+You can either use the appropriate hotkey (see list above) to launch the
+handler with the currently loaded URI, or you can perform a right click
+on any link, image or media file to use that URI.
+.P
+This mechanism allows you to implement a variety of functions. You might
+want to implement a bookmarking script or a password manager or you
+might simply load the current URI in a different browser. That's up to
+you.
+.\" --------------------------------------------------------------------
 .SH "USING LARIZA WITH TABBED"
 By default, \fBlariza\fP automatically launches an instance of suckless'
 \fBtabbed\fP(1).