.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 . By default OSC 7 path is used as the current directory, but if OSC 7 path is not set to a valid local path and the platform provides a Linux-style procfs at .Pa /proc , .Nm will use the child process's working directory instead. .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 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 . .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