path: root/doc/cha-urimethodmap.5

.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "cha-urimethodmap" "5" "" "" "URI method map support in Chawan"
.hy
.SH URI method map support in Chawan
.PP
Chawan can be used to map unrecognized protocols to known protocols
using the \f[V]urimethodmap\f[R] format.
.PP
The main use case for this is implementing handlers to protocols unknown
to Chawan through a protocol that the browser \f[I]does\f[R] understand.
.SS Search path
.PP
The search path for urimethodmap files can be overridden using the
configuration variable \f[V]external.urimethodmap\f[R].
.PP
The default search path for urimethodmap files is:
.IP
.nf
\f[C]
$HOME/.urimethodmap:$HOME/.w3m/urimethodmap:/etc/urimethodmap:/usr/local/etc/urimethodmap
\f[R]
.fi
.SS Format
.PP
The urimethodmap format is taken 1:1 from w3m, with only some
modifications to the interpretation of templates.
.PP
A rough attempt at the formal description of this:
.IP
.nf
\f[C]
URIMethodMap-File = *URIMethodMap-line

URIMethodMap-Line = Comment / URIMethodMap-Entry

URIMethodMap-Entry = Protocol *WHITESPACE Template *WHITESPACE CR

Protocol = 1*CHAR COLON

Template = [see below]

Comment = *WHITESPACE CR / \[dq]#\[dq] *CHAR CR
\f[R]
.fi
.PP
Note that an ASCII colon sign (:) must be present after the protocol
name.
However, the whitespace may be omitted.
.PP
Examples:
.IP
.nf
\f[C]
# This is ok:
protocol:   /cgi-bin/interpret-protocol?%s
# This is ok too:
protocol:/cgi-bin/interpret-protocol?%s
# Spaces and tabs are both allowed, so this is also ok:
protocol:   /cgi-bin/interpret-protocol?%s
# However, this is incorrect, because the colon sign is missing:
protocol    /cgi-bin/interpret-protocol?%s
\f[R]
.fi
.PP
The redirection template is the target URL.
If the string \f[V]%s\f[R] is contained in the template, it will be
replaced by the target URL.
.PP
Note: Chawan used to URL-encode the substituted URL in the past, but
this is no longer the case.
.PP
For compatibility with w3m, templates starting with \f[V]/cgi-bin/\f[R]
and \f[V]file:/cgi-bin/\f[R] are special-cased and the starting string
is replaced with \f[V]cgi-bin:\f[R].
So for example, the template \f[V]/cgi-bin/w3mdict.cgi\f[R] is the same
as \f[V]cgi-bin:w3mdict.cgi\f[R] (and so is
\f[V]file:/cgi-bin/w3mdict.cgi\f[R]).
.PP
Example:
.IP
.nf
\f[C]
# The following are the same in Chawan
protocol:   /cgi-bin/interpret-protocol?%s
protocol:   file:/cgi-bin/interpret-protocol?%s
# Note: this last entry does not work in w3m.
protocol:   cgi-bin:interpret-protocol?%s
\f[R]
.fi
.PP
Note however that absolute paths to cgi scripts are NOT special cased,
so e.g.\ \f[V]file:///usr/local/libexec/w3m/cgi-bin/w3mdict.cgi\f[R]
will simply open w3mdict.cgi in the file viewer.
(Unlike in w3m, where it could run \f[V]w3mdict.cgi\f[R] depending on
the user\[cq]s configuration.)
.SS Examples
.SS In config.toml
.IP
.nf
\f[C]
# Following sets the urimethodmap search path to the path relative to the
# configuration file. So if your configuration file is in
# \[ti]/.config/chawan/config.toml, Chawan will use \[ti]/.config/chawan/urimethodmap.
# in the same directory.
[external]
urimethodmap = \[dq]urimethodmap\[dq]
\f[R]
.fi
.SS In urimethodmap
.SS magnet.cgi
.IP
.nf
\f[C]
# Use the \[ga]magnet.cgi\[ga] CGI shell script to pass magnet links to Transmission.
magnet:     /cgi-bin/magnet.cgi?%s
\f[R]
.fi
.PP
\f[V]magnet.cgi\f[R] can be found in the \f[V]bonus/\f[R] directory.
You can also write a local CGI wrapper to pass the links to your
BitTorrent client of choice.
.SS dict
.PP
In w3m, urimethodmap is commonly (ab)used to define shorthands for CGI
scripts.
.PP
This works in Chawan too; for an example, you could define a
\f[V]tl:\f[R] shorthand like this:
.IP
.nf
\f[C]
# (trans.cgi is a script you can find and study in the bonus/ directory.)
tl:     /cgi-bin/trans.cgi?%s
\f[R]
.fi
.PP
Then, you could open the translation of any word using
\f[V]tl:word\f[R].
.PP
Note however that Chawan has a more powerful facility for substitution
shorthands like this in the form of omni-rules.
So if you want to redirect to an on-line dictionary site with tl:word
instead of providing a local CGI interface, it is probably easier to
just use omni-rules instead of urimethodmap + local CGI redirection.
.PP
Rule of thumb: if you find yourself writing local CGI scripts that just
send a \f[V]Location:\f[R] header, maybe consider just using an
omni-rule.