showansi
— display
ANSI art in a terminal window
showansi |
[-Sensw ] [-c
columns] [-d
dos2ansi] [-r
rows] [-- ]
[args] |
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:
-S
- Ignore SAUCE and other metadata and use all defaults or values passed on
the commandline.
Also passes ignoring SAUCE to
dos2ansi(1).
-V
- Print version information and exit.
-c
columns
- 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
).
-d
dos2ansi
- Run dos2ansi to render the input file for the
configured pager to display.
- default:
- /usr/local/bin/dos2ansi
-e
- Use an EGA font. This is ignored if the font type can be deduced from
SAUCE metadata unless
-S
is given.
- default:
- from metadata or VGA
-h
- Print a help text and exit.
-n
- 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.
- default:
- from metadata or spaced (9px)
-r
rows
- The number of rows for display, IOW, the height of the terminal
window.
-s
- Assume square pixels, so, pick a font without aspect correction. This is
ignored if aspect information is available from SAUCE unless
-S
is given.
- default:
- from metadata or rectangular pixels
-w
- 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.
- default:
- from metadata or regular width
- args
- 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).
SHOWANSI_DEBUG
- 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.
TMPDIR
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.
- /usr/local/etc/dos2ansi/showansirc
- 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.
- /usr/local/etc/dos2ansi/showansirc.sample
- A commented example configuration file, demonstrating all the available
options.
- /usr/local/share/dos2ansi/showansi/fonts.bitmap
- A fontset for
xterm(1)
using bitmap fonts from
https://github.com/farsil/ibmfonts
- /usr/local/share/dos2ansi/showansi/fonts.scalable
- A fontset for
xterm(1)
using scalable fonts from
https://int10h.org/oldschool-pc-fonts
- /usr/local/share/dos2ansi/showansi/fonts.mixed
- 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.