diff options
Diffstat (limited to 'doc/cha-urimethodmap.5')
| -rw-r--r-- | doc/cha-urimethodmap.5 | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/doc/cha-urimethodmap.5 b/doc/cha-urimethodmap.5 new file mode 100644 index 00000000..98dd6dbe --- /dev/null +++ b/doc/cha-urimethodmap.5 @@ -0,0 +1,163 @@ +.\" 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. |