aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorbptato <nincsnevem662@gmail.com>2025-04-09 02:38:04 +0200
committerbptato <nincsnevem662@gmail.com>2025-04-11 19:04:56 +0200
commitc908f05f03bac0cbccd14ab13ea8d0df8b087611 (patch)
tree7b2999729b66c6179340abdcf2efd76c065b201c /doc
parent581aa021d4b30075d01b892e78bf4757e8942c4e (diff)
downloadchawan-c908f05f03bac0cbccd14ab13ea8d0df8b087611.tar.gz
config: unify table arrays and tables
[[siteconf]] now just means [siteconf.0], etc. So you can now override parts of default siteconfs/omnirules, e.g. to change the Google search substitute-url, etc. To celebrate this, I've added some more default search engines: * wk: -> Wikipedia * wd: -> Wiktionary * ms: -> Marginalia Search These can be replaced by setting e.g. omnirule.wk = {}, etc. Also, siteconf = {} can be used to clear pre-defined siteconfs. This is an unfortunate deviation in semantics from TOML, but in practice the way it worked before didn't match the spec either, so at least it is now consistent.
Diffstat (limited to 'doc')
-rw-r--r--doc/cha-config.549
-rw-r--r--doc/config.md49
2 files changed, 59 insertions, 39 deletions
diff --git a/doc/cha-config.5 b/doc/cha-config.5
index 066d4bd2..af553073 100644
--- a/doc/cha-config.5
+++ b/doc/cha-config.5
@@ -5,21 +5,24 @@
.SH Configuration of Chawan
Chawan supports configuration of various options like keybindings, user
stylesheets, site preferences, etc.
-The configuration format is almost toml, with the following exceptions:
+The configuration format is similar to toml, with the following
+exceptions:
.IP \[bu] 2
Inline tables may span across multiple lines.
.IP \[bu] 2
-Table arrays can be cleared by setting a variable by the same to the
-empty array.
-This allows users to disable default table array rules.
-.PP
-Example:
-.IP
-.EX
-omnirule = [] # note: this must be placed at the beginning of the file.
-
-[[omnirule]] # this is legal. all default omni\-rules are now disabled.
-.EE
+Regular tables (\f[CR][table]\f[R]) and inline tables
+(\f[CR]table = {}\f[R]) have different semantics.
+The first is additive, meaning old values are not removed.
+The second is destructive, and clears all definitions in the table
+specified.
+.IP \[bu] 2
+For backwards compatibility, \f[CR]table = []\f[R] is equivalent to
+\f[CR]table = {}\f[R].
+.IP \[bu] 2
+\f[CR][[table\-array]]\f[R] is sugar for \f[CR][table\-array.n]\f[R],
+where \f[CR]n\f[R] is the number of declared table arrays.
+For example, you can declare anonymous siteconfs using the syntax
+\f[CR][[siteconf]]\f[R].
.PP
The canonical configuration file path is \[ti]/.chawan/config.toml, but
the search path accommodates XDG basedirs as well:
@@ -956,7 +959,9 @@ T}
.SS Omnirule
The omni\-bar (by default opened with C\-l) can be used to perform
searches using omni\-rules.
-These are to be placed in the table array \f[CR][[omnirule]]\f[R].
+These are to be specified as sub\-keys to table \f[CR][omnirule]\f[R].
+(The sub\-key itself is ignored; you can use anything as long it
+doesn\[cq]t conflict with other keys.)
.PP
Examples:
.IP
@@ -964,11 +969,13 @@ Examples:
# Search using DuckDuckGo Lite.
# (This rule is included in the default config, although C\-k now invokes
# Google search.)
-[[omnirule]]
+[omnirule.ddg]
match = \[aq]\[ha]ddg:\[aq]
substitute\-url = \[aq](x) => \[dq]https://lite.duckduckgo.com/lite/?kp=\-1&kd=\-1&q=\[dq] + encodeURIComponent(x.split(\[dq]:\[dq]).slice(1).join(\[dq]:\[dq]))\[aq]
# Search using Wikipedia, Firefox\-style.
+# The [[omnirule]] syntax introduces an anonymous omnirule; it is
+# equivalent to the named one.
[[omnirule]]
match = \[aq]\[ha]\[at]wikipedia\[aq]
substitute\-url = \[aq](x) => \[dq]https://en.wikipedia.org/wiki/Special:Search?search=\[dq] + encodeURIComponent(x.replace(/\[at]wikipedia/, \[dq]\[dq]))\[aq]
@@ -1011,7 +1018,9 @@ T}
.TE
.SS Siteconf
Configuration options can be specified for individual sites.
-Entries are to be placed in the table array \f[CR][[siteconf]]\f[R].
+Entries are to be specified as sub\-keys to table \f[CR][siteconf]\f[R].
+(The sub\-key itself is ignored; you can use anything as long it
+doesn\[cq]t conflict with other keys.)
.PP
Most siteconf options can also be specified globally; see the
\[lq]overrides\[rq] field.
@@ -1020,12 +1029,12 @@ Examples:
.IP
.EX
# Enable cookies on the orange website for log\-in.
-[[siteconf]]
+[siteconf.hn]
url = \[aq]https://news\[rs].ycombinator\[rs].com/.*\[aq]
cookie = true
# Redirect npr.org to text.npr.org.
-[[siteconf]]
+[siteconf.npr]
host = \[aq](www\[rs].)?npr\[rs].org\[aq]
rewrite\-url = \[aq]\[aq]\[aq]
(x) => {
@@ -1037,18 +1046,20 @@ x.pathname = s.at(s.length > 2 ? \-2 : 1);
\[aq]\[aq]\[aq]
# Allow cookie sharing on *sr.ht domains.
-[[siteconf]]
+[siteconf.sr\-ht]
host = \[aq](.*\[rs].)?sr\[rs].ht\[aq] # either \[aq]something.sr.ht\[aq] or \[aq]sr.ht\[aq]
cookie = true # enable cookies (read\-only; use \[dq]save\[dq] to persist them)
share\-cookie\-jar = \[aq]sr.ht\[aq] # use the cookie jar of \[aq]sr.ht\[aq] for all matched hosts
# Use the \[dq]vector\[dq] skin on Wikipedia.
+# The [[siteconf]] syntax introduces an anonymous siteconf; it is
+# equivalent to the above ones.
[[siteconf]]
url = \[aq]\[ha]https?://[a\-z]+\[rs].wikipedia\[rs].org/wiki/(?!.*useskin=.*)\[aq]
rewrite\-url = \[aq]x => x.searchParams.append(\[dq]useskin\[dq], \[dq]vector\[dq])\[aq]
# Make imgur send us images.
-[[siteconf]]
+[siteconf.imgur]
host = \[aq](i\[rs].)?imgur\[rs].com\[aq]
default\-headers = {
User\-Agent = \[dq]Mozilla/5.0 chawan\[dq],
diff --git a/doc/config.md b/doc/config.md
index 75905e8c..3cb68e86 100644
--- a/doc/config.md
+++ b/doc/config.md
@@ -5,19 +5,19 @@ MANOFF -->
# Configuration of Chawan
Chawan supports configuration of various options like keybindings, user
-stylesheets, site preferences, etc. The configuration format is almost
-toml, with the following exceptions:
+stylesheets, site preferences, etc. The configuration format is similar
+to toml, with the following exceptions:
* Inline tables may span across multiple lines.
-* Table arrays can be cleared by setting a variable by the same to the
- empty array. This allows users to disable default table array rules.
-
-Example:
-```
-omnirule = [] # note: this must be placed at the beginning of the file.
-
-[[omnirule]] # this is legal. all default omni-rules are now disabled.
-```
+* Regular tables (`[table]`) and inline tables (`table = {}`) have
+ different semantics. The first is additive, meaning old values are
+ not removed. The second is destructive, and clears all definitions in
+ the table specified.
+* For backwards compatibility, `table = []` is equivalent to
+ `table = {}`.
+* `[[table-array]]` is sugar for `[table-array.n]`, where `n` is the
+ number of declared table arrays. For example, you can declare
+ anonymous siteconfs using the syntax `[[siteconf]]`.
The canonical configuration file path is ~/.chawan/config.toml, but
the search path accommodates XDG basedirs as well:
@@ -760,19 +760,24 @@ protocol.</td>
## Omnirule
-The omni-bar (by default opened with C-l) can be used to perform searches using
-omni-rules. These are to be placed in the table array `[[omnirule]]`.
+The omni-bar (by default opened with C-l) can be used to perform
+searches using omni-rules. These are to be specified as sub-keys to table
+`[omnirule]`. (The sub-key itself is ignored; you can use anything as
+long it doesn't conflict with other keys.)
Examples:
+
```
# Search using DuckDuckGo Lite.
# (This rule is included in the default config, although C-k now invokes
# Google search.)
-[[omnirule]]
+[omnirule.ddg]
match = '^ddg:'
substitute-url = '(x) => "https://lite.duckduckgo.com/lite/?kp=-1&kd=-1&q=" + encodeURIComponent(x.split(":").slice(1).join(":"))'
# Search using Wikipedia, Firefox-style.
+# The [[omnirule]] syntax introduces an anonymous omnirule; it is
+# equivalent to the named one.
[[omnirule]]
match = '^@wikipedia'
substitute-url = '(x) => "https://en.wikipedia.org/wiki/Special:Search?search=" + encodeURIComponent(x.replace(/@wikipedia/, ""))'
@@ -808,8 +813,10 @@ returned, it will be parsed instead of the old one.</td>
## Siteconf
-Configuration options can be specified for individual sites. Entries are
-to be placed in the table array `[[siteconf]]`.
+Configuration options can be specified for individual sites. Entries
+are to be specified as sub-keys to table `[siteconf]`. (The sub-key
+itself is ignored; you can use anything as long it doesn't conflict with
+other keys.)
Most siteconf options can also be specified globally; see the
"overrides" field.
@@ -817,12 +824,12 @@ Most siteconf options can also be specified globally; see the
Examples:
```
# Enable cookies on the orange website for log-in.
-[[siteconf]]
+[siteconf.hn]
url = 'https://news\.ycombinator\.com/.*'
cookie = true
# Redirect npr.org to text.npr.org.
-[[siteconf]]
+[siteconf.npr]
host = '(www\.)?npr\.org'
rewrite-url = '''
(x) => {
@@ -834,18 +841,20 @@ rewrite-url = '''
'''
# Allow cookie sharing on *sr.ht domains.
-[[siteconf]]
+[siteconf.sr-ht]
host = '(.*\.)?sr\.ht' # either 'something.sr.ht' or 'sr.ht'
cookie = true # enable cookies (read-only; use "save" to persist them)
share-cookie-jar = 'sr.ht' # use the cookie jar of 'sr.ht' for all matched hosts
# Use the "vector" skin on Wikipedia.
+# The [[siteconf]] syntax introduces an anonymous siteconf; it is
+# equivalent to the above ones.
[[siteconf]]
url = '^https?://[a-z]+\.wikipedia\.org/wiki/(?!.*useskin=.*)'
rewrite-url = 'x => x.searchParams.append("useskin", "vector")'
# Make imgur send us images.
-[[siteconf]]
+[siteconf.imgur]
host = '(i\.)?imgur\.com'
default-headers = {
User-Agent = "Mozilla/5.0 chawan",