1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
<!-- MANON
% cha-urimethodmap(5) | URI method map support in Chawan
MANOFF -->
# URI method map support in Chawan
Chawan can be used to map unrecognized protocols to known protocols using the
`urimethodmap` format.
The main use case for this is implementing handlers to protocols unknown to
Chawan through a protocol that the browser *does* understand.
## Search path
The search path for urimethodmap files can be overridden using the
configuration variable `external.urimethodmap`.
The default search path for urimethodmap files is:
```
$HOME/.urimethodmap:$HOME/.w3m/urimethodmap:/etc/urimethodmap:/usr/local/etc/urimethodmap
```
## Format
The urimethodmap format is taken 1:1 from w3m, with only some modifications
to the interpretation of templates.
A rough attempt at the formal description of this:
```
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 / "#" *CHAR CR
```
Note that an ASCII colon sign (:) must be present after the protocol
name. However, the whitespace may be omitted.
Examples:
```
# 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
```
The redirection template is the target URL. If the string `%s` is contained
in the template, it will be replaced by the target URL.
Note: Chawan used to URL-encode the substituted URL in the past, but this is
no longer the case.
For compatibility with w3m, templates starting with `/cgi-bin/` and
`file:/cgi-bin/` are special-cased and the starting string is replaced with
`cgi-bin:`. So for example, the template `/cgi-bin/w3mdict.cgi` is the same as
`cgi-bin:w3mdict.cgi` (and so is `file:/cgi-bin/w3mdict.cgi`).
Example:
```
# 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
```
Note however that absolute paths to cgi scripts are NOT special cased, so
e.g. `file:///usr/local/libexec/w3m/cgi-bin/w3mdict.cgi` will simply open
w3mdict.cgi in the file viewer. (Unlike in w3m, where it could run
`w3mdict.cgi` depending on the user's configuration.)
## Examples
### In config.toml
```
# Following sets the urimethodmap search path to the path relative to the
# configuration file. So if your configuration file is in
# ~/.config/chawan/config.toml, Chawan will use ~/.config/chawan/urimethodmap.
# in the same directory.
[external]
urimethodmap = "urimethodmap"
```
### In urimethodmap
#### magnet.cgi
```
# Use the `magnet.cgi` CGI shell script to pass magnet links to Transmission.
magnet: /cgi-bin/magnet.cgi?%s
```
`magnet.cgi` can be found in the `bonus/` directory. You can also write a
local CGI wrapper to pass the links to your BitTorrent client of choice.
#### dict
In w3m, urimethodmap is commonly (ab)used to define shorthands for CGI scripts.
This works in Chawan too; for an example, you could define a `tl:` shorthand
like this:
```
# (trans.cgi is a script you can find and study in the bonus/ directory.)
tl: /cgi-bin/trans.cgi?%s
```
Then, you could open the translation of any word using `tl:word`.
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.
Rule of thumb: if you find yourself writing local CGI scripts that just
send a `Location:` header, maybe consider just using an omni-rule.
|