#+TITLE: Zutty user guide
#+OPTIONS: author:nil timestamp:nil num:nil val:nil html-style:nil H:3 ^:{}
#+HTML_HEAD:
* Installation
Nowadays Zutty comes packaged by most major Linux distributions as
well as BSDs, so you might want to install Zutty from a package
provided by your Linux distro or BSD port. It is recommended that you
check whether it is up-to-date. Refuse anything older than the latest
published release (and ask your package provider to update it). Please
refer to [[https://git.hq.sig7.se/zutty.git/tags][git tags]] for authoritative release information.
If you want to run the very latest commit, you will probably need to
install Zutty from source. You will also have to do this if you want
to make your own modifications and debug the program. This is not as
scary as it might seem, because Zutty has very few dependencies and is
a relatively small program. Below are all the steps you need to go
through.
** 1. Install build dependencies
On a current (stable or testing) Debian, or a Debian-derivative such
as Ubuntu, the following command will make sure everything you need to
build Zutty is in place. It also gives you an idea of what you need to
install Zutty on other flavours of Linux.
: sudo apt-get install \
: build-essential pkg-config python3 \
: libegl-dev libfreetype-dev libgles-dev libxmu-dev
Hint: You might need to substitute =libfreetype6-dev= for
=libfreetype-dev= and =libgles2-mesa-dev= for =libgles-dev=.
When in doubt, use your distribution's package manager along with your
favourite Internet search engine.
** 2. Obtain the source
Clone the source from git:
: git clone https://git.hq.sig7.se/zutty.git
: cd zutty
** 3. Configure the source
You are supposed to be inside the repository directory structure,
i.e., the =zutty= directory created above should be your working
directory. Issue this command:
: ./waf configure
You should see some output with a confirmation of the Zutty version
you are going to build, and whether you are creating a Debug build (it
should say "no" at this point; read the [[./HACKING.org][Developer guide]] if you are
interested in debugging Zutty).
By default, g++ (the gcc compiler for C++) will be used to compile
Zutty. To use clang instead, pass =--check-cxx-compiler=clang++= to
the above script.
In the configure output, you will see checks for the presence of the
build dependencies. If anything is missing, the configure script will
terminate with an error. Otherwise, the configure output will finish
with a line like this:
: 'configure' finished successfully (0.373s)
In case you will want to install the =zutty= executable to somewhere
other than =/usr/local/bin=, use the =--prefix= option to specify the
installation prefix (the default is =/usr/local=). For example, I
often install stuff for my user account only, in which case I would
issue =./waf configure --prefix=/home/tom/root= so that later on,
=zutty= would end up installed as =/home/tom/root/bin/zutty=.
If you would like to learn more, =./waf --help= lists a reference of
every option you can use.
** 4. Compile the source
Just type:
: ./waf
Alternatively, if you want to specify the number of jobs to run in
parallel, issue =./waf -j 4= (substitute your number of CPU cores in
place of 4).
The compilation messages should be self-explanatory (assuming you do
not run into C++ error messages -- decoding those is an art form in its
own right). A successful compile ends with a line like this:
: 'build' finished successfully (23.524s)
At this point, the =zutty= executable is complete and ready to be run
at =build/src/zutty= and you might want to launch it just to see if it
works. You can run it without arguments to start it up with defaults,
or add =-h= (or =-help=) to learn about available options.
** 5. Install Zutty
For regular use, it is best to copy the =zutty= executable to a
system-wide directory for binaries where it will be found as part of
the default executable search path. This makes it easier to launch and
also decouples it from any local changes. You can manually copy the
executable built in the previous step, but it might be easier to use
the built-in install step in the =waf= script. Running it with =sudo=
will ensure that it is able to write to protected system-wide
locations:
: sudo ./waf install
Note that your ability to run the above command (with =sudo=) is
contingent on the presence of =sudo=, the setup of your user account
with respect to sudo, etc. If it does not work, please search the web
or ask your friendly local guru. Also, if you have specified an
install location that is actually yours (like the one I showed above)
then of course there is no point in using =sudo=.
At the end, you should see something like this:
: 'install' finished successfully (0.135s)
Congratulations, you are now ready to start using Zutty as your
terminal!
* Usage reference
** User interface actions
The following list summarizes user-triggered actions. Note that these
are hooks handled by the terminal itself, and will not reach the
program running in the terminal. For the specification of how the
terminal encodes keypresses to the program running inside it, see the
[[./KEYS.org][Key mapping sequences]] reference.
| Trigger | Action |
|-------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Shift+PageUp, Shift+PageDown | Page screen upwards (into earlier scrollback history) or downwards by half the page height. If on the alternate screen with =-altScroll= enabled, emit synthetic arrow key events to move up/down half the screen height. |
| Scroll wheel up/down | Page screen up/down by 5 lines; if on the alternate screen with =-altScroll= enabled, emit a single synthetic up/down arrow key event. |
| Left mouse button press (and hold) | Start a new selection. Adjust by moving the mouse with the button held down. |
| Right mouse button press (and hold) | Adjust current selection (will grab the edge closest to the pointer); adjust by moving the mouse with the button held down. |
| Quickly release and re-engage left/right mouse button | While a selection is in progress, this will cycle between snap-to-char, snap-to-word and snap-to-line. (In rectangular selection mode, only snap-to-char exists.) |
| Space key while left/right mouse button is held | Toggle between /regular/ and /rectangular/ selection mode. |
| Middle mouse button, Shift+Insert | Paste the current content of the primary selection into the terminal. |
| Control+Shift+C | Copy the current content of the primary selection into the clipboard selection. (With =-autoCopy= enabled, this happens automatically whenever the primary selection is set.) |
| Control+Shift+V | Paste the current content of the clipboard selection into the terminal. |
|-------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
** Environment variables
Zutty sets or alters the below environment variables in the process
spawned to run the shell. All other environment variables accessible
to Zutty will be passed unaltered to the shell program.
| Environment variable | Treatment |
|----------------------+-----------------------------------------------------------------------------------------------------------------------------|
| =DISPLAY= | Set to the current X display. |
| =SHELL= | Set to the full (resolved) pathname of the shell being run; unset if the program is not a valid shell as per =/etc/shells=. |
| =TERM= | Set to =xterm-256color=. |
| =COLORTERM= | Set to =truecolor=. |
| =WINDOWID= | Set to the current X window id of the Zutty window. |
| =ZUTTY_VERSION= | Set to the build version of Zutty. |
* Configuration
Zutty has a set of configuration options, all of which have:
- a command line option;
- an X resource database (Xrdb) key;
- a sensible hard default.
For each option, the above list defines the order of preference. That
is, the command line can be used to define or override a setting in a
transient way; Xrdb entries may be used to persistently alter the
default value for an option; and lastly, without any option or
configuration, Zutty will still have a workable default.
There is also a set of [[Extra resources]] available for persistent
configuration, but not settable via command line options.
To view the list of options, issue =zutty -h= (short for =-help=):
: Usage:
: zutty [-option ...] [shell]
:
: Options:
: -altScroll Alternate scroll mode
: -autoCopy Sync primary to clipboard
: -bg Background color (default: #000)
: -boldColors Enable bright for bold
: -border Border width in pixels (default: 2)
: -cr Cursor color
: -display Display to connect to
: -dwfont Double-width font to use (default: 18x18ja)
: -fg Foreground color (default: #fff)
: -font Font to use (default: 9x18)
: -fontsize Font size (default: 16)
: -fontpath Font search path (default: /usr/share/fonts)
: -geometry Terminal size in chars (default: 80x24)
: -glinfo Print OpenGL information
: -help Print usage listing and quit
: -listres Print resource listing and quit
: -login Start shell as a login shell
: -name Instance name for Xrdb and WM_CLASS
: -rv Reverse video
: -saveLines Lines of scrollback history (default: 500)
: -shell Shell program to run
: -showWraps Show wrap marks at right margin
: -title Window title (default: Zutty)
: -quiet Silence logging output
: -verbose Output info messages
: -e Command line to run
All options can be abbreviated as long as they are non-ambiguous, so
it's fine to write =-di= short for =-display=, =-gl= for =-glinfo=,
=-fontp= for =-fontpath=, =-t= for =-title=, =-q= for =-quiet=, etc.
Boolean options (=-altScroll=, =-autoCopy=, =-boldColors=, =-glinfo=,
=-login=, =-rv=, =-showWraps=, =-quiet=, =-verbose=) do not expect an
argument; the mere presence of these options amounts to a setting of
"true". To set them to "false", change the leading dash to a plus
sign. For example, =+boldColors= will /disable/ the "boldColors"
option (which is enabled by default). This might also be useful to
override an option that is by default false, but has been set to true
in the X resource database (see [[Persistent configuration]]).
All other options expect exactly one argument, with the exception of
=-e=, which must be the last option, to be followed by the command
line to run.
The options are further documented below, grouped into sections by
topic. To set up a persistent configuration (altered defaults), see
the next section [[Persistent configuration]].
** Basic configuration and mode switches
: -altScroll Alternate scroll mode [boolean]
If enabled, mouse scroll up and down events while on the alternate
screen buffer are translated into synthetic up- and down-arrow key
events. This might prove to be a convenient way of moving up/down
one-by-one in programs usually navigated with the keyboard arrows.
Another, similar effect (also on the alternate screen) is that the
keys normally used to page through the screen buffer (Shift+PageUp,
Shift+PageDown) will generate the same synthetic up- and down-arrow
key events as above, but in multiples, to scroll half the amount of
scrollable lines. This might be convenient in the same situations,
only for larger jumps.
: -autoCopy Sync primary to clipboard [boolean]
By enabling this option, Zutty will automatically propagate the
primary selection to the clipboard each time a selection is completed,
acting as if you pressed Control+Shift+C immediately after each
selection. This might be convenient if you do not wish to use the dual
selection capability (primary plus clipboard), and expect to be able
to paste into other programs that source the data from the clipboard.
: -display Display to connect to
The X display to connect to. By default, the value of the environment
variable DISPLAY is used. This option is exceptional in that (for
obvious reasons) it cannot be configured via the X resource database,
only the command line.
: -glinfo Print OpenGL information
If enabled, Zutty will query and log some GL variables on program
startup. These include EGL_VERSION, EGL_VENDOR, EGL_EXTENSIONS, as
well as GL_RENDERER, GL_VERSION, GL_VENDOR, GL_EXTENSIONS, and numeric
limits on the Compute Shader implementation. This is mostly a
debugging aid. The output is not affected by any verbosity changes
made via =-v= or =-q=.
: -help Print usage listing and quit
Print the help message containing the list of options documented here,
and quit.
: -listres Print resource listing and quit
Print a listing of configurable [[Extra resources]] and quit.
: -name Instance name for Xrdb and WM_CLASS
This option specifies the application instance name, which will be
used to look up resources in the X resource database, and reported to
the window manager as part of the =WM_CLASS= property (the other part
being the application class name, hardcoded as =Zutty=). The
specified name should not contain "." (dot) or "*" (asterisk), as
those characters have special meanings within Xrdb entries.
If this option is not present, but the environment variable
=RESOURCE_NAME= is set, that will be used instead. If none of these
are available, the hard default value of =Zutty= will be used.
This option is exceptional in that (for obvious reasons) it cannot be
configured via the X resource database, only the command line.
: -saveLines Lines of scrollback history (default: 500)
Set the number of lines to keep in off-screen page history, viewable
via paging the terminal up/down by Shift+PageUp and Shift+PageDown
(jumping half a page-height at once), or the mouse scrollwheel (moving
in units of 5 lines). The set amount of saved lines is in addition to
the lines visible in the terminal window.
The default value is 500 lines, which should be enough for everyday
use (the occasional peek at the output of a command that rolled off
the screen). The minimum setting is 0 (no scrollback), the maximum
allowed value is 50,000. Note that while the performance of scrolling
itself (and Zutty in general) will /not/ degrade with a larger
setting, the screen buffer /will/ consume proportional amounts of
memory. With very large settings, this will dominate the total memory
usage of Zutty! For example, 1024 buffered lines (24 lines on-screen
and 1000 lines of scrollback) with 80 columns will consume 960 KiB;
this will balloon to 10 MiB with 10,000 lines of scrollback.
Adjusting the column width will have a similar (proportional) effect;
50,000 lines at a width of 120 columns will consume a whopping 70 MiB!
Note that the alternate screen buffer does not have scrollback; this
is by design and in conformance with the relevant specs (but see
=-altScroll= for enabling synthetic up- and down-arrow key events).
: -quiet Silence logging output [boolean]
: -verbose Output info messages [boolean]
These options control the verbosity of log output emitted by
Zutty. You will only observe the effects of these if you run Zutty
itself from another terminal (as opposed to some launcher that
discards the program's output). In that case, you will notice output
that looks like this:
: I [font.cc: 54] Loading /usr/share/fonts/X11/misc/9x18.pcf.gz as primary
: I [font.cc:198] Glyph size 9x18
: ...
: I [main.cc:118] Window ID: 48234498 / 0x2e00002
: I [charvdev.cc:377] Resize to 935 x 771 pixels, 103 x 42 chars
The first letter is an indication of the log level or "severity"; =E=
means Error, =W= stands for Warning, =I= is Info and =T= is Trace.
Trace will only be output if you compile Zutty into a debug build; see
the [[./HACKING.org][Developer guide]] for details. Next, the origin of the log message
is shown in square brackets, indicating the source code location
(filename and line number) where the message was printed. Then comes
the actual message.
By default (if neither =-quiet= nor =-verbose= is given), Zutty will
print errors and warnings, but not info messages. If =-verbose= is
given, info messages are also printed. On the other hand, if =-quiet=
is given, nothing is printed. If both options are given, =-quiet=
wins.
** General appearance
: -geometry Terminal size in chars (default: 80x24)
This option defines the desired initial size of the terminal as
measured in characters. (The pixel size of the window will be a
function of this plus the font geometry, and cannot be specified
directly.)
This is just a request to the window manager; Zutty will accept and
work with whatever final window size it gets. Setting this will in no
way interfere with your ability to resize Zutty once it is up and
running.
: -bg Background color (default: #000)
: -fg Foreground color (default: #fff)
: -cr Cursor color
These options accept a hexadecimal RGB or RRGGBB color specification,
similar to how you can define a color in many other places, e.g., CSS.
The leading =#= is optional (supported mainly to provide compatibility
with established conventions); take care to protect it from the shell
when passing it on the command line. Both lower- and uppercase
hexadecimal digits (a-f, A-F) are accepted, but note that names (e.g.,
=red= instead of =#f00=) are /not/ supported.
If not explicitly set, the cursor color defaults to the foreground
color. In case the cursor is placed on a cell with a background color
set to the cursor color, the cursor color is automatically inverted to
ensure it stays visible.
: -rv Reverse video [boolean]
Using this option will swap the effective foreground and background
color, regardless of whether their values originate from =-fg= and
=-bg=, or the corresponding resources, or the defaults. It will /not/
swap the meaning of color codes and such; if a program explicitly
specifies the color green, it will be rendered green with and without
=-rv=.
: -boldColors Enable bright for bold [boolean]
This option enables combining the bold attribute with a brightening of
base colors. That is, when printing bold text, colors 0 through 7 will
be mapped to colors 8 through 15 by adding 8 to the color number.
These normally correspond to the brighter variants of the same colors.
This is enabled by default; supply =+boldColors= on the command line
to turn it off.
: -border Border width in pixels (default: 2)
Specify the border width; specifically, the border that is part of the
client area of the Zutty window and not part of any window decoration
outside of the program's direct control. (This is equivalent to what
Xterm calls internal border width.)
: -showWraps Show wrap marks at right margin [boolean]
Specify whether to draw a vertical mark on the right edge of cells
having the =wrap= bit set. This bit is set in case an auto-wrap occurs
just after the given position, so it only gets set on the right
margin. However, following an increase of the window size, cells with
a set =wrap= bit might reside inside the right margin.
When selecting text, line breaks are suppressed depending on the
=wrap= bit (wrapped text is copied without the breaks introduced by
the wraps), so a visual indicator of this status bit might be useful
to better understand (or predict) behaviour. It might also be useful
to see this when debugging Zutty or an application writing text at the
right margin.
: -title Window title (default: Zutty)
Set the title of the Zutty window. A title configured in the X
resource database will be overridden by usage of the =-e= option,
which sets the title to the basename of the program to be run. Passing
the title on the command line takes precedence over the title implied
by =-e=. In any case, the title can be overridden at runtime by
escape sequences output by the shell (or any program executed by it).
** Shell/command specification
: -login Start shell as a login shell [boolean]
When this option is enabled, the shell started by Zutty will be a
login shell. This will be signalled to the shell process by setting
its =argv [0]= to begin with a dash (=-=). Shells evaluate different
sets of startup files depending on this (e.g., =bash= sources
=/etc/profile= and =~/.bash_profile= if started as a login shell, but
sources =~/.bashrc= otherwise). Please consult the documentation of
your shell for accurate details.
When using the =-e= option, this option will be ignored, because =-e=
is supposed to be used to launch non-shell text-mode programs in a
terminal window, and manipulating the =argv [0]= of such programs
might interfere with their operation.
: -shell Shell program to run
Specify the shell program to run in the terminal. As a bit of special
syntax, this option can be passed both as a regular option (=-shell
bash= anywhere among a list of other options), or just the shell
itself (=bash=) as the last item on the command line. Either way, this
option is mutually exclusive with using the =-e= option. If both forms
are present, the last item on the command line will take precedence
over the value supplied after =-shell=.
The algorithm to resolve the executable to spawn resembles the
behaviour of =xterm=, and follows these steps:
0. Start with the value of =shell= (the last argument given after all
valid options, if present, or the value supplied after =-shell=).
In case no =shell= argument is given, the =Zutty.shell= resource is
consulted; if that is not set, the value of the =SHELL= environment
variable is used; if that is not set, the built-in default of
=bash= is assumed.
1. If not already an absolute path, resolve this to an absolute path
taking =PATH= into account, trying elements of the list of =PATH=
entries until the given shell resolves to an existing file at that
path.
2. Fall back on the =SHELL= environment variable, then the user's
=/etc/passwd= shell entry, if the above did not result in any
candidate.
3. Use =/bin/sh= as a last resort.
4. Validate the outcome of the above steps against the permitted shell
entries found in =/etc/shells=. Proceed, but clear =SHELL= from the
environment if the program is not listed as a valid shell. Else,
set =SHELL= to the resolved full program path.
: -e Command line to run
This option specifies the command line (program and arguments) to be
run in the Zutty terminal window. It also sets the window title to the
basename of the program to be executed, unless the title is explicitly
set by passing =-title= on the command line.
Note that this must be the last option on the command line, as
everything after it will be passed verbatim to the spawned child
process.
Using this option is mutually exclusive with the =-shell= option, and
will silently override it, as well as discarding the =-login= option,
if any of those are also present.
** Font selection
Zutty employs a simple but powerful model of font selection. Font
files are located under a search path and loaded by Zutty itself
(bypassing any infrastructure such as a font server, etc). In
principle, any font that is supported by the Freetype font library can
be used; in practice, only monospace fonts make sense. Both fixed size
(bitmap) fonts and scaled (vectorized) fonts are supported.
You specify the font to use by its name, which will be part of the
actual filename(s) that store the font. Multiple variants of the font
will be sought after: Zutty will try to find a Regular, a Bold, an
Italic and a Bold Italic variant of the font you specify. It is not an
error if these do not exist, as long as the primary variant (Regular)
is found.
: -font Font to use (default: 9x18)
This option specifies the font name to use. The name supplied will
form the basis of a case-insensitive search under the font search
path. The search will try to locate a set of files under the same
subdirectory, starting with the supplied name and ending with the same
extension that is one of the recognized font file extensions. If such
a set of files is found, the full filenames (the parts after the
specified font name) will be used to assign the files to each variant
sought after.
For example, the default font is =9x18=. This is one of the "misc
fixed" fonts. After seeing that the font name is =9x18=, Zutty will
search under the font path =/usr/share/fonts= for files starting with
=9x18=. It will find =9x18.pcf.gz= and =9x18B.pcf.gz=, both under
=/usr/share/fonts/X11/misc=. Based on the filenames, Zutty will
recognize the first file as the regular variant, and the second file
as the bold variant. Other variants are absent; use of text attributes
that depend on them will result in sensible fallbacks.
As a second example, we will load a scaled font called Liberation Mono
by supplying =-font LiberationMono= (or =-font liberationmono=) to
Zutty. This will result in several files found, all under
=/usr/share/fonts/truetype/liberation=: =LiberationMono-Regular.ttf=,
=LiberationMono-Bold.ttf=, =LiberationMono-Italic.ttf= and
=LiberationMono-BoldItalic.ttf=. These files will be loaded as the
respective variants of the chosen font.
: -dwfont Double-width font to use (default: 18x18ja)
This option specifies the font name to use for rendering double-width
characters (CJK ideographs). Everything written above for =-font=
applies here as well. The double-width font is located in a separate
search, so it may reside in a different location (the set of search
paths is the same; see =-fontpath=). It may also be of a different
type (e.g., it is possible to use a scaled font for CJK characters
even if the main font is of a fixed type). No variants (bold, italic)
are considered.
The default setting is a fixed width bitmap font chosen to work well
with the default main font (see =-font=). See [[Recommended fonts]] below
for tips on using a scalable CJK font.
The font size to use will be defined by the main font (governed by the
=-fontsize= option). For the double-width font to load, its geometry
must match this predetermined cell size (times two horizontally). It
is not an error if no suitable font is found. A warning will be logged
on startup, and the program will draw empty boxes in place of any
double-width characters. In such case, as only the ability to render
these characters is missing, it is still possible to select them in
Zutty and paste into a different program that is able to display them.
: -fontsize Font size (default: 16)
For scaled fonts, such as Liberation Mono above, this setting controls
the height, measured in integer pixels, to rasterize the glyphs to.
The actual character grid size will almost always be more, due to the
fact that typefaces have some spacing around the glyphs themselves.
The specified size, if within one pixel of the size of a bitmap
strike, will result in picking that strike (pre-rasterized version)
from a scaled font with strikes. If there are no strikes, or the
specified size is too far from any pre-rasterized sizes, Zutty falls
back to rendering the outline at the requested size.
In case of a fixed size font with multiple bitmap sizes, the size
closest to the configured size will be selected.
: -fontpath Font search path (default: /usr/share/fonts)
This option specifies the root of the directory structure where font
files will be searched. It is seldom necessary to change this, but
might be useful to try some new font you downloaded from the Internet
(and have not yet installed to a system-wide location).
Hint: you can specify more than one root, separated by colons. These
will be searched in order (left to right) until the specified font is
found.
*** Recommended fonts
The author of Zutty prefers the so-called [[https://www.cl.cam.ac.uk/~mgk25/ucs-fonts.html][misc-fixed]] fonts. These are
upgraded, extended versions of the bitmap fonts originally designed
for the X Window System, created in the '80s in an era of much
inferior computer displays. Their availability is universal; you
probably have them installed already. These fonts are highly optimized
for readability at low resolutions. There is a convenient range of
sizes, several fonts have bold variants and support thousands of
international characters and symbols outside ASCII. Zutty will work
best with any of misc-fixed 6x13, 7x13, 7x14, 8x13, 9x15 and 9x18
(there are more, but the ones listed have a bold-face variant as
well).
If you prefer scalable fonts (e.g., because you have a high-resolution
HiDPI display or prefer LARGE glyphs with a more modern look), Zutty
works well with freely available scaled terminal fonts such as
Anonymous Pro, Deja Vu Sans Mono, Free Mono, Hack, Inconsolata,
Liberation Mono, and possibly many more (see below for a list).
The rest of this section gives Debian-specific recommendations; use it
as a source of inspiration if you use a different distribution. The
following list of package names might serve as a useful starting point
to obtain some usable fonts. For each package, install it and pass the
specified name(s) to =-font= to check them out:
- =xfonts-base=: 6x13, 7x13, 7x14, 8x13, 9x15, 9x18
- =fonts-dejavu-core=: DejaVuSansMono
- =fonts-liberation=: LiberationMono
- =fonts-freefont-ttf=: FreeMono
- =fonts-hack-otf=: Hack
- =fonts-inconsolata=: Inconsolata
- =ttf-anonymous-pro=: "Anonymous Pro"
Note that the quotation marks are required when passing an argument
value with a space, e.g.: =zutty -font "Anonymous Pro"=
The default CJK font =18x18ja= belongs to the =xfonts-base= package,
along with all other misc-fixed fonts recommended above. There is a
similar font =18x18ko= with the same fixed geometry providing more,
and slightly differently drawn, glyphs (try with =-dwfont 18x18ko=).
For scaled CJK fonts, the following packages are recommended:
- =fonts-wqy-microhei=: wqy-microhei
- =fonts-wqy-zenhei=: wqy-zenhei
For example, after installing the package =fonts-wqy-zenhei=, try
something like this to get a fully scalable font system:
=zutty -font dejavusansmono -dwfont wqy-zenhei -fontsize 32=\\
Experiment with the size; do not expect good results at small font
sizes.
In the above setup, the =-fontsize= setting guides the rasterized cell
size of the main font, the result of which guides the rasterized cell
size of the double-width font. The order is interesting mainly because
the rasterized size might be subtly different than the requested size.
A discussion of the subtle (language-specific) differences of CJK
glyphs provided by different fonts for the same code point is beyond
the scope of this document. [[https://en.wikipedia.org/wiki/Han_unification#Examples_of_language-dependent_glyphs][This table]] might be useful to identify
variants; copy-paste any glyph in a given row into Zutty and see which
variant the current font gives you!
Finally: a couple of freely downloadable, modern scalable fonts known
to work well with Zutty (in no particular order):
- Fira Code
- Hasklig
- JetBrains Mono
- Source Code Pro
These (and possibly many more) are suitable for relatively high font
sizes (for high resolution displays) as compared to fixed-size bitmap
fonts (usually designed for 72 dpi). Pro tip: check the Zutty font
rasterization tests (a part of the automated testing suite) [[https://git.hq.sig7.se/zutty.git/blob/HEAD:/test/fonts.sh][here]] or at
=test/fonts.sh= in your checked out Zutty source tree. It contains
human-readable instructions on how to set up most fonts mentioned
above for use with Zutty.
*** Making fonts discoverable
Zutty has a simple heuristic to identify the font files to load for
each variant of a given size of a requested font face. This will work
for lots of fonts (see above), but inevitably, certain fonts will have
naming schemes that evade this mechanism. In such a case, manually
renaming the files on your system will help. An even better method is
to create symlinks (symbolic links) to the font files with alternative
names that Zutty will be able to correctly identify. This has the
advantage of preserving the original files.
For example, [[https://people.mpi-inf.mpg.de/~uwe/misc/uw-ttyp0/][UW ttyp0]] is a family of freely available monospace bitmap
fonts that works well with Zutty. You might want to consider it as an
alternative to the "misc fixed" family. However, installing these
fonts will yield names such as (for the 18-point, Unicode encoded
variant): =t0-18-uni.pcf.gz= (regular), =t0-18b-uni.pcf.gz= (bold),
=t0-18i-uni.pcf.gz= (italic). The solution is to add symlinks such as:
- =t0-18.pcf.gz -> t0-18-uni.pcf.gz=
- =t0-18b.pcf.gz -> t0-18b-uni.pcf.gz=
- =t0-18i.pcf.gz -> t0-18i-uni.pcf.gz=
These symlinks will allow you to use this font in Zutty by starting it
via =-font t0-18=. Add a similar set of symlinks for each point size
you want to be able to use.
* Persistent configuration
The configuration options documented in the previous chapter
[[Configuration]] can be assigned altered defaults by adding entries to
the X resource database. Refer to the previous chapter for the list
and semantics of all options; here we show how to add entries for them
to your X resource database (Xrdb).
Open the file =.Xresources= in your home directory, or create it if
you do not have one. Use the following snippet merely as a starting
point; its purpose is to help you with enough examples to get what you
want, with the right syntax. Hint: you will /not/ want to set exactly
these options.
: Zutty.title: The Big Zutty
: Zutty.geometry: 120x45
: Zutty.altScroll: true
: Zutty.boldColors: false
: Zutty.font: Inconsolata
: Zutty.fontsize: 18
: Zutty.fontpath: /home/tom/root/share/fonts:/usr/share/fonts
: Zutty.fg: #00ff80
: Zutty.bg: #234
: Zutty.cr: #0f0
As you can see, the general pattern is simple: one setting per line,
starting with a key that looks like =Zutty.