Blame


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