aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/weltschmerz.1
blob: aaad053ad855e542f3f4cb30d8053de273565e3d (plain) (blame)
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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
.Dd July 24, 2021
.Dt WELTSCHMERZ 1
.Os
.Sh NAME
.Nm weltschmerz
.Nd a small VTE-based terminal emulator
.Sh SYNOPSIS
.Nm
.Oo
.Ar command
.Op Ar argument...
.Oc
.Sh DESCRIPTION
.Nm
is a terminal emulator using the VTE widget.
It supports clickable URLs and hyperlinks, contains basic search functionality,
and can reload its configuration whilst running.
.Pp
.Nm
executes the given command, or the program specified in the
.Ev SHELL
environment variable if no command was given.
If the
.Ev SHELL
environment variable is unset or empty,
.Nm
will fall back to the user's shell as configured in
.Pa /etc/passwd ,
or finally use
.Pa /bin/sh
if there is no such entry.
.Pp
The clipboard can be copied to and pasted from with
.Sy CTRL + Shift + C
and
.Sy CTRL + Shift + V ,
respectively.
.Pp
The font scale can be adjusted by scrolling up or down whilst holding
.Sy CTRL ,
or by using
.Sy CTRL + =
and
.Sy CTRL + - .
It can be reset to its default value with
.Sy CTRL + 0 .
.Pp
The default file manager can be opened in the current directory with
.Sy CTRL + Shift + O
and a new terminal window with
.Sy CTRL + Shift + T .
These features require the terminal application to send OSC 7 escape sequences
or for the platform to provide a Linux-style procfs at
.Pa /proc .
.Sh SEARCH OVERLAY
The search overlay can be opened by pressing
.Sy CTRL + Shift + F .
The search will be updated automatically as the user types in the search bar.
.Pp
The key bindings for the overlay are as follows:
.Bl -tag -width Ds
.It Sy Enter , CTRL + G
Go to next search result.
.It Sy Shift + Enter , CTRL + Shift + G
Go to previous search result.
.It Sy Escape
Close search overlay.
.El
.Sh CONFIGURATION
Configuration is done using a configuration file.
.Nm
will reread that file when receiving SIGUSR1, or when the user presses
.Sy CTRL + Shift + R .
.Pp
.Nm
uses GLib's key-value file parser.
The file format consists of key-value pairs collected in groups:
.Bd -literal -offset indent
[misc]
font = Iosevka Light 16

[colours]
foreground = #000000
background = #ffffff

[open-with]
mpv = mpv %
.Ed
.Pp
Refer to the GLib documentation for detailed information on this format.
.Pp
The options for the
.Em misc
group are as follows:
.Bl -tag -width Ds
.It Sy allow-hyperlinks
When set to
.Sy true ,
.Nm
will highlight and process OSC 8 hyperlinks.
When set to
.Sy false ,
hyperlink support will be disabled completely.
The default is
.Sy false .
.It Sy autohide-mouse
When set to
.Sy true ,
the mouse cursor will be hidden once the user presses a key, and shown
once the user moves the mouse.
When set to
.Sy false ,
the mouse cursor will always be shown.
The default is
.Sy false .
.It Sy cursor-shape
Specifies the shape of the terminal cursor.
Possible values are
.Sy beam ,
.Sy block ,
and
.Sy underline .
The default is
.Sy block .
.It Sy cursor-blink
Specifies whether the cursor should blink.
Possible values are
.Sy true ,
.Sy false ,
and
.Sy system .
The default is
.Sy system .
.Pp
When set to
.Sy system ,
.Nm
will honour the GTK setting
.Sy gtk-cursor-blink .
Refer to the GTK documentation for more details.
.It Sy font
Specifies the font used to draw text, in the form of a Pango font
description.
Consists of one or more font families, zero or more style options, and
the size in points (or in pixels if given a suffix of
.Dq px ) :
.Bd -literal -offset indent
Monospace 12
Iosevka, DejaVu Sans Mono bold italic 16
Gohu GohuFont 11px
.Ed
.Pp
Refer to the Pango documentation for detailed information.
.Pp
The default is
.Sy Monospace 12 .
.It Sy scrollback
Specifies how many lines of scrollback to keep.
A value of -1 means infinite scrollback.
The default is
.Sy 10000 .
.It Sy prefer-osc7
When set to
.Sy true ,
.Nm
attempts to use OSC 7 to obtain the current directory.
If this does not produce a valid local path,
.Nm
obtains the child process's working directory from
.Pa /proc .
When set to
.Sy false ,
only
.Pa /proc
is used.
The default is
.Sy true .
.It Sy scrollbar
When set to
.Sy true ,
.Nm
will draw a scrollbar at the right side of the terminal window.
When set to
.Sy false ,
no scrollbar is drawn.
The default is
.Sy true .
.Pp
Note that
.Nm
uses overlay scrolling if available.
This means that the scrollbar is drawn on top of the terminal and fades
out automatically if unused.
If you wish to turn this behaviour off, set the
.Ev GTK_OVERLAY_SCROLLING
environment variable to
.Sy 0
or modify the GTK setting
.Sy gtk-overlay-scrolling .
.El
.Pp
The
.Em colours
group contains the palette and colour overrides.
All keys in this group take a colour representation as their value:
.Bd -filled -offset indent
.TS
tab(/);
l |l
lb |l.
Representation/Example value
=
Hexadecimal/#00ffff
RGB/rgb(0, 255, 255)
RGBA/rgba(0, 255, 255, 1)
X11 colour/cyan
.TE
.Ed
.Pp
The palette defines the 16 base colours available to the terminal.
Keys for the palette are in the form of:
.Bd -literal -offset indent
<colour type>.<colour name>
.Ed
.Pp
The colour type is either
.Dq normal
or
.Dq bright ,
and the possible colour names along with their default representations
are as follows:
.Bd -filled -offset indent
.TS
tab(/);
l |l |l
lb |l |l.
Colour name/Default (normal)/Default (bright)
=
black/black/grey50
red/red3/red
green/green3/green
yellow/yellow3/yellow
blue/blue2/#5c5cff
magenta/magenta3/magenta
cyan/cyan3/cyan
white/grey90/white
.TE
.Ed
.Pp
The colour overrides specify which colour to use for certain parts of
the terminal.
The following table contains all possible keys for the colour overrides,
along with the default behaviour if the override is not set:
.Bd -filled -offset indent
.TS
tab(/);
l |l
lb |il.
Key/Default
=
foreground/normal.white
background/normal.black
cursor.foreground/reverse video
cursor.background/reverse video
selection.foreground/reverse video
selection.background/reverse video
bold/inherit colour
.TE
.Ed
.Pp
The options in the
.Em open-with
section define programs that can be invoked from the URI context menu.
The option name determines the name of the program as displayed in the
menu, and the value the command to be executed.
.Pp
.Nm
handles quotes in the command following POSIX
.Xr sh 1
rules,
but does not do wildcard or variable expansion.
Any
.Dq %
is replaced with the URI when executing the command.
.Sh FILES
.Bl -tag -width Ds
.It Em $XDG_CONFIG_HOME/weltschmerz/config
The configuration file for
.Nm .
.El
.Pp
.Nm
adheres to the XDG Base Directory Specification.
If $XDG_CONFIG_HOME is unset or empty, it will default to
.Em ~/.config
.Sh AUTHORS
.An -nosplit
.Nm
was written by
.An Wolfgang Müller Aq Mt wolf@oriole.systems