Blob


1 .\" Copyright (c) 2020 Omar Polo <op@omarpolo.com>
2 .\"
3 .\" Permission to use, copy, modify, and distribute this software for any
4 .\" purpose with or without fee is hereby granted, provided that the above
5 .\" copyright notice and this permission notice appear in all copies.
6 .\"
7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 .Dd $Mdocdate: September 27 2020$
15 .Dt STAR-PLATINUM.CONF 5
16 .Os
17 .Sh NAME
18 .Nm star-platinum.conf
19 .Nd star-platinum configuration file
20 .Sh DESCRIPTION
21 .Nm
22 is the configuration file for the
23 .Xr star-platinum 1
24 program.
25 .Pp
26 Empty lines are ignored, and comments too.
27 Comments starts with a # sign and continue until the end of the line.
28 Comments can be placed everywhere, not only at the start of the line.
29 .Pp
30 The configuration file is made of blocks.
31 Every block starts with one or more
32 .Ic match
33 directives and continues with several keybinding directives.
34 If more than a single
35 .Ic match
36 directive is given, the keybinding will be used if at least one of the
37 .Ic match
38 directives matches the focused window.
39 .Pp
40 A keybinding directive is made of the
41 .Ic on
42 keyword followed by a keybinding, followed by the
43 .Ic do
44 keyword and an action.
45 The action can be another keybinding, or a special internal command.
46 .Pp
47 Special attention must be payed to quoting, as there are two different
48 types of quoting with different behaviors:
49 .Bl -bullet
50 .It
51 double quotes are used for keybindings.
52 So, for instance, "C-a" is a valid keybinding, but 'C-a' is not.
53 .It
54 single quotes are used to denote strings.
55 Strings can include any character, except the literal single quote,
56 and are kept verbatim: no special interpretation of character is made.
57 .El
58 .Sh MATCHING WINDOWS
59 The
60 .Ic match
61 keyword is used to match on windows.
62 .Ic match
63 can either accept the special keyword
64 .Ic all
65 or match on a predicate.
66 .Pp
67 .Ic match all
68 matches all windows, even the root window.
69 .Pp
70 The only predicate supported as of now is the
71 .Ic class
72 predicate.
73 .Ic class
74 takes a string and matches only windows whose class is equal to the
75 one given.
76 .Pp
77 Lastly,
78 .Ic match
79 directives are not alone: any sequence of contiguous match are joined,
80 so that the same key bindings can defined for more window.
81 This joining is extensive, and not reductive.
82 .Sh KEY BINDINGS
83 The syntax for the keybindings is inspired
84 .Xr emacs 1 .
85 A keybindings is written within double quotes and is made of modifiers
86 followed by the key.
87 Modifiers follows the
88 .Xr emacs 1
89 notation of using C- to mean control, S- for shift, M- for alt (mod1)
90 and s- for super (mod4).
91 The key can be either a plain letter (e.g. x) or the name of the key
92 written within angular brackets (e.g. <Down>).
93 See
94 .Pa /usr/X11R6/include/X11/keysymdef.h
95 and
96 .Xr XStringToKeysym 3
97 for more information on the names allowed inside the angular brackets.
98 .Pp
99 The only exceptions are a couple of keys that are available under a
100 special syntax:
101 .Bl -tag -indent keyword
102 .It Ic SPC
103 is a short-hand for
104 .Ic <space>
105 .It Ic RET
106 is a short-hand for
107 .Ic <Return>
108 .It Ic (
109 is a short-hand for
110 .Ic <parenleft>
111 .It Ic )
112 is a short-hand for
113 .Ic <parenright>
114 .El
115 .Sh ACTIONS
116 When a key bindings is matched against a specific window, the
117 appropriate action is executed.
118 There are different types of possible actions:
119 .Bl -tag -width 10m
120 .It a key
121 send the specified key to the focused window
122 .It Ic exec Ql cmd
123 exec
124 .Ql cmd
125 using the user shell'
126 .Fl c
127 flag.
128 .It Ic ignore
129 a no-op.
130 It does nothing, but prevents the focused window from seeing that key.
131 .El
132 .Sh ENVIRONMENT
133 .Bl -tag -width keyword
134 .\" XXX: keep in sync with star-platinum.1
135 .It Ev SHELL
136 The user preferred shell.
137 If not provided
138 .Pa /bin/sh
139 is assumed.
140 This executable must accept a
141 .Fl c
142 flag to execute a string.
143 .El
144 .Sh EXAMPLES
145 The following is an example of configuration file that binds some
146 .Xr emacs 1 Ns -esque keys for both Firefox and Chromium:
147 .Bd -literal -offset indent
148 # a global binding
149 match all
150 on "C-<F5>" do exec 'notify-send "hello world"'
152 match class 'Firefox' # matching firefox OR
153 match class 'Chromium-browser' # matching chromium
154 on "C-s" do "C-f"
156 # clipboard
157 on "C-w" do "C-x"
158 on "M-w" do "C-c"
159 on "C-y" do "C-v"
161 # movements
162 on "C-n" do "<Down>"
163 on "C-p" do "<Up>"
164 on "C-f" do "<Right>"
165 on "C-b" do "<Left>"
167 on "C-(" do ignore
168 .Ed