#+TITLE: Zutty user guide#+OPTIONS: author:nil timestamp:nil num:nil val:nil html-style:nil H:3 ^:{}#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="org.css"/> * Installation Nowadays Zutty comes packaged by most major Linux distributions aswell as BSDs, so you might want to install Zutty from a packageprovided by your Linux distro or BSD port. It is recommended that youcheck whether it is up-to-date. Refuse anything older than the latestpublished release (and ask your package provider to update it). Pleaserefer 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 toinstall Zutty from source. You will also have to do this if you wantto make your own modifications and debug the program. This is not asscary as it might seem, because Zutty has very few dependencies and isa relatively small program. Below are all the steps you need to gothrough. ** 1. Install build dependencies On a current (stable or testing) Debian, or a Debian-derivative suchas Ubuntu, the following command will make sure everything you need tobuild Zutty is in place. It also gives you an idea of what you need toinstall 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 yourfavourite 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 workingdirectory. Issue this command: : ./waf configure You should see some output with a confirmation of the Zutty versionyou are going to build, and whether you are creating a Debug build (itshould say "no" at this point; read the [[./HACKING.org][Developer guide]] if you areinterested in debugging Zutty). By default, g++ (the gcc compiler for C++) will be used to compileZutty. To use clang instead, pass =--check-cxx-compiler=clang++= tothe above script. In the configure output, you will see checks for the presence of thebuild dependencies. If anything is missing, the configure script willterminate with an error. Otherwise, the configure output will finishwith a line like this: : 'configure' finished successfully (0.373s) In case you will want to install the =zutty= executable to somewhereother than =/usr/local/bin=, use the =--prefix= option to specify theinstallation prefix (the default is =/usr/local=). For example, Ioften install stuff for my user account only, in which case I wouldissue =./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 ofevery option you can use. ** 4. Compile the source Just type: : ./waf Alternatively, if you want to specify the number of jobs to run inparallel, issue =./waf -j 4= (substitute your number of CPU cores inplace of 4). The compilation messages should be self-explanatory (assuming you donot run into C++ error messages -- decoding those is an art form in itsown 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 runat =build/src/zutty= and you might want to launch it just to see if itworks. 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 asystem-wide directory for binaries where it will be found as part ofthe default executable search path. This makes it easier to launch andalso decouples it from any local changes. You can manually copy theexecutable built in the previous step, but it might be easier to usethe built-in install step in the =waf= script. Running it with =sudo=will ensure that it is able to write to protected system-widelocations: : sudo ./waf install Note that your ability to run the above command (with =sudo=) iscontingent on the presence of =sudo=, the setup of your user accountwith respect to sudo, etc. If it does not work, please search the webor ask your friendly local guru. Also, if you have specified aninstall 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 yourterminal! * Usage reference ** User interface actions The following list summarizes user-triggered actions. Note that theseare hooks handled by the terminal itself, and will not reach theprogram running in the terminal. For the specification of how theterminal 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 processspawned to run the shell. All other environment variables accessibleto 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.  Thatis, the command line can be used to define or override a setting in atransient way; Xrdb entries may be used to persistently alter thedefault value for an option; and lastly, without any option orconfiguration, Zutty will still have a workable default. There is also a set of [[Extra resources]] available for persistentconfiguration, 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, soit'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 anargument; the mere presence of these options amounts to a setting of"true". To set them to "false", change the leading dash to a plussign. For example, =+boldColors= will /disable/ the "boldColors"option (which is enabled by default). This might also be useful tooverride an option that is by default false, but has been set to truein 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 commandline to run. The options are further documented below, grouped into sections bytopic. To set up a persistent configuration (altered defaults), seethe 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 alternatescreen buffer are translated into synthetic up- and down-arrow keyevents. This might prove to be a convenient way of moving up/downone-by-one in programs usually navigated with the keyboard arrows. Another, similar effect (also on the alternate screen) is that thekeys normally used to page through the screen buffer (Shift+PageUp,Shift+PageDown) will generate the same synthetic up- and down-arrowkey events as above, but in multiples, to scroll half the amount ofscrollable 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 theprimary selection to the clipboard each time a selection is completed,acting as if you pressed Control+Shift+C immediately after eachselection. This might be convenient if you do not wish to use the dualselection capability (primary plus clipboard), and expect to be ableto 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 environmentvariable DISPLAY is used. This option is exceptional in that (forobvious 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 programstartup. These include EGL_VERSION, EGL_VENDOR, EGL_EXTENSIONS, aswell as GL_RENDERER, GL_VERSION, GL_VENDOR, GL_EXTENSIONS, and numericlimits on the Compute Shader implementation. This is mostly adebugging aid. The output is not affected by any verbosity changesmade 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 beused to look up resources in the X resource database, and reported tothe window manager as part of the =WM_CLASS= property (the other partbeing the application class name, hardcoded as =Zutty=).  Thespecified name should not contain "." (dot) or "*" (asterisk), asthose 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 theseare available, the hard default value of =Zutty= will be used. This option is exceptional in that (for obvious reasons) it cannot beconfigured 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, viewablevia paging the terminal up/down by Shift+PageUp and Shift+PageDown(jumping half a page-height at once), or the mouse scrollwheel (movingin units of 5 lines). The set amount of saved lines is in addition tothe lines visible in the terminal window. The default value is 500 lines, which should be enough for everydayuse (the occasional peek at the output of a command that rolled offthe screen). The minimum setting is 0 (no scrollback), the maximumallowed value is 50,000. Note that while the performance of scrollingitself (and Zutty in general) will /not/ degrade with a largersetting, the screen buffer /will/ consume proportional amounts ofmemory.  With very large settings, this will dominate the total memoryusage of Zutty! For example, 1024 buffered lines (24 lines on-screenand 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; thisis 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 byZutty. You will only observe the effects of these if you run Zuttyitself from another terminal (as opposed to some launcher thatdiscards the program's output). In that case, you will notice outputthat 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; seethe [[./HACKING.org][Developer guide]] for details. Next, the origin of the log messageis shown in square brackets, indicating the source code location(filename and line number) where the message was printed. Then comesthe actual message. By default (if neither =-quiet= nor =-verbose= is given), Zutty willprint errors and warnings, but not info messages. If =-verbose= isgiven, 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 asmeasured in characters. (The pixel size of the window will be afunction of this plus the font geometry, and cannot be specifieddirectly.) This is just a request to the window manager; Zutty will accept andwork with whatever final window size it gets. Setting this will in noway interfere with your ability to resize Zutty once it is up andrunning. :   -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 compatibilitywith established conventions); take care to protect it from the shellwhen passing it on the command line. Both lower- and uppercasehexadecimal 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 foregroundcolor. In case the cursor is placed on a cell with a background colorset to the cursor color, the cursor color is automatically inverted toensure it stays visible. :   -rv           Reverse video [boolean] Using this option will swap the effective foreground and backgroundcolor, 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 explicitlyspecifies 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 ofbase colors. That is, when printing bold text, colors 0 through 7 willbe 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 lineto turn it off. :   -border       Border width in pixels (default: 2) Specify the border width; specifically, the border that is part of theclient area of the Zutty window and not part of any window decorationoutside of the program's direct control. (This is equivalent to whatXterm calls internal border width.) :   -showWraps    Show wrap marks at right margin [boolean] Specify whether to draw a vertical mark on the right edge of cellshaving the =wrap= bit set. This bit is set in case an auto-wrap occursjust after the given position, so it only gets set on the rightmargin.  However, following an increase of the window size, cells witha 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 bythe wraps), so a visual indicator of this status bit might be usefulto better understand (or predict) behaviour. It might also be usefulto see this when debugging Zutty or an application writing text at theright margin. :   -title        Window title (default: Zutty) Set the title of the Zutty window. A title configured in the Xresource database will be overridden by usage of the =-e= option,which sets the title to the basename of the program to be run. Passingthe title on the command line takes precedence over the title impliedby =-e=.  In any case, the title can be overridden at runtime byescape 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 alogin shell. This will be signalled to the shell process by settingits =argv [0]= to begin with a dash (=-=). Shells evaluate differentsets of startup files depending on this (e.g., =bash= sources=/etc/profile= and =~/.bash_profile= if started as a login shell, butsources =~/.bashrc= otherwise). Please consult the documentation ofyour 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 aterminal window, and manipulating the =argv [0]= of such programsmight interfere with their operation. :   -shell        Shell program to run Specify the shell program to run in the terminal. As a bit of specialsyntax, this option can be passed both as a regular option (=-shellbash= anywhere among a list of other options), or just the shellitself (=bash=) as the last item on the command line. Either way, thisoption is mutually exclusive with using the =-e= option. If both formsare present, the last item on the command line will take precedenceover the value supplied after =-shell=. The algorithm to resolve the executable to spawn resembles thebehaviour 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 berun in the Zutty terminal window. It also sets the window title to thebasename of the program to be executed, unless the title is explicitlyset by passing =-title= on the command line. Note that this must be the last option on the command line, aseverything after it will be passed verbatim to the spawned childprocess. Using this option is mutually exclusive with the =-shell= option, andwill 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. Fontfiles are located under a search path and loaded by Zutty itself(bypassing any infrastructure such as a font server, etc). In

Lines 1–500 of 922. Load more