showansi combines dos2ansi(1) with a terminal emulator (by default xterm(1)) and a pager (by default less(1)) to form an ANSI-art viewer. It uses SAUCE metadata obtained from dos2ansi(1) to select an appropriate font, set the terminal window size and the window title.
Even if SAUCE metadata is absent, it tries to guess the appropriate font from rendering metadata. If the final display size is exactly 80x50 or 80x43, the file is assumed to target the respective VGA or EGA mode, so a wide font is selected. If the input uses ANSI.SYS sequences for setting a textmode, the font selection takes into account whether an 80- or 40-column mode is selected.
showansi always prefers the number of columns and rows given on the commandline for the terminal window size. For everything else, to override it from the commandline, the -S flag must be given if contradicting SAUCE metadata is available.
The options are as follows:
Ignore SAUCE and other metadata and use all defaults or values passed on the commandline.
Also passes ignoring SAUCE to dos2ansi(1).
Print version information and exit.
The number of columns for display, IOW, the width of the terminal window.
Also passed to dos2ansi(1) as the default canvas width (flag -w).
Run dos2ansi to render the input file for the configured pager to display.
Use an EGA font. This is ignored if the font type can be deduced from SAUCE metadata unless -S is given.
Print a help text and exit.
No letter spacing, which means to pick an 8px wide font. This is ignored if spacing information is available from SAUCE unless -S is given.
The number of rows for display, IOW, the height of the terminal window.
Assume square pixels, so, pick a font without aspect correction. This is ignored if aspect information is available from SAUCE unless -S is given.
Use a wide font (for 40-columns or VGA50 or EGA43 modes), which means a 9x8/8x8 or 18x16/16x16 font. This is ignored if the font type can be deduced from SAUCE metadata unless -S is given.
Arguments for dos2ansi(1), including the file to display. Must be preceded by -- if it contains flags (starting with -). If it doesn't contain a file to display, the standard input will be read and fed to dos2ansi(1).
When this is set to 1, showansi prints some debugging information to the standard output, including the full command line it will execute to display the input file.
showansi needs to process an input file multiple times with dos2ansi(1) to get metadata and then render it in a terminal configured appropriately, so when input comes from standard input, it must be stored in a temporary file. A private directory will be created for that purpose, using mktemp(1) if available, otherwise using plain mkdir(1) below TMPDIR. Note that mktemp(1) typically also uses TMPDIR. If unset, it defaults to /tmp.
The main configuration file. This is used to configure the terminal emulator, including necessary command line arguments, the pager, and the fontset.
Paths to per-user configuration files can be set here as well.
A commented example configuration file, demonstrating all the available options.
A fontset for xterm(1) using bitmap fonts from https://github.com/farsil/ibmfonts
A fontset for xterm(1) using scalable fonts from https://int10h.org/oldschool-pc-fonts
A fontset combining both sets above, using scalable fonts when aspect correction for non-square pixels is wanted, bitmap fonts otherwise. This is the default fontset in the example configuration.
dos2ansi(1), less(1), xterm(1)