NAME

dos2ansi — convert old MS-DOS/ANSI.SYS text files

SYNOPSIS

DESCRIPTION

dos2ansi converts MS-DOS text files using ANSI.SYS escape sequences to a format a modern terminal can display. The output will use a Unicode encoding of characters and only ANSI SGR escape sequences to set basic foreground and background colors, intensity and blinking attribute. The input is expected to use CP-437 or one of the other supported DOS codepages.

The builtin translation tables attempt to match the appearance on VGA as close as possible by mapping to Unicode characters looking similar to the original IBM PC glyphs in most fonts. This behavior can be disabled with the -X flag, which is helpful when dos2ansi is used to convert some text or when using original IBM PC fonts for display.

The options are as follows:

-A

Assume full support for ANSI SGR sequences including clearing individual attributes. This gives the shortest possible output in most cases, but might not work correctly with some terminals. Implies forcing generic ANSI output (-a).

-B

Disable writing a BOM.

default:

BOM enabled for UTF-16 and UTF-16LE.

-C

Disable colors in output.

-E

Ignore the DOS EOF character (0x1a) and just continue reading.

-H scrheight

Set a default screen height. This is relevant when ANSI.SYS sequences for cursor positioning or erasing are used.

Ignored if the height can be deduced from SAUCE metadata or mode-setting ANSI.SYS sequences.

-I

When using generic ANSI output, don't attempt to explicitly select intense colors but rely on the bold attribute for the foreground color instead. For background colors, see -k and -v.

-P

Force using a normal pipe bar symbol.

default:

Replace with a broken bar for codepages not having an explicit broken bar.

-R

Use line endings without CR (Unix format).

default:

Disabled on Windows, enabled otherwise.

-S

Don't attempt to read SAUCE metadata. This enables setting options that are otherwise ignored when values are found in SAUCE, like the width, whether to use blink or bright colors, and the codepage.

-T

Test mode, instead of reading an input file, use some builtin test input that will render a codepage table and a display of all foreground and background colors.

-V

Print version information along with some build-time and OS-dependent configuration settings and exit.

-W

When showing SAUCE (-s), don't attempt to re-wrap the comment but show it as is instead.

-X

Disable the mapping to Unicode codepoints that look more similar to the original VGA font in most fonts used nowadays, instead map to codepoints identifying the same character. Use this when using some actual IBM-PC font for display.

-a

Force using the generic ANSI color writer, which defaults to use 16 explicit colors, but can be configured for just 8 colors as well as 256 colors.

When dos2ansi is built with curses support (non-Windows), it uses a terminfo-based writer by default, even when output goes to a file, possibly creating terminal-specific output.

On Windows 10 and later, the terminal supports 256 colors which is used by default for output to the console, but can be disabled using this flag. On older Windows versions, only the legacy Windows Console API can be used for display, so this flag does nothing.

-b

Force writing a BOM.

default:

BOM enabled for UTF-16 and UTF-16LE.

-c codepage

The MS-DOS codepage used by the input file. May be prefixed with CP (any casing) and an optional space or dash. When the codepage can be found in SAUCE metadata, this flag is ignored.

supported:

437, 708, 720, 737, 775, 819, 850, 852, 855, 857, 860, 861, 862, 863, 864, 865, 869, kam, maz, mik

aliases:

858	=> 850 with Euro (-e)
872	=> 855 with Euro (-e)
867, 895	=> kam
667, 790, 991	=> maz
866	=> mik

default:

437

-d

Use default terminal colors for VGA's gray on black.

default:

Explicitly select these colors.

-e

Use codepage variations with an Euro currency symbol if applicable. For codepages 850, 857, 864 and 869, there are specific known places for the Euro symbols. For other codepages that have a generic currency symbol, replace this with the Euro currency symbol.

-h

Print a help text and exit.

-k

Use blink attribute for intense background colors. This flag is ignored if SAUCE metadata is available.

Note that blink only works in some terminals. In any case, bright background colors will be disabled.

-l

Attempt to enforce left-to-right writing direction by wrapping the output in a Unicode LTR override region.

-m

Write some metadata to stderr while rendering. The output format is key=value, this can be used from scripts or for debugging purposes.

-o outfile

Write output to outfile. If not given, output is written to the standard output.

-p

Force replacing the pipe bar with a broken bar better matching the appearance of most VGA fonts.

default:

Only replace when the codepage does not have an explicit broken bar.

-q saucequery

Query individual SAUCE metadata fields in a machine-readable format. Each field is requested by a single character in saucequery and printed on a single line to the standard output, converted from CP-437 to UTF-8.

The following characters are supported in saucequery:

:

toggle quoting all subsequent fields in single quotes, with literal single quotes translated to '\'' (POSIX shell style)

T

title

A

author

G

group

D

date (format: YYYYMMDD)

C

comment, output will be multiple lines, the first line is the number of lines to follow

t

file and data type

w

width (in characters)

h

height (in characters)

b

background mode (0: blink, 1: bright)

s

spacing (0: 8px, 1: 9px)

a

aspect ratio (0: rectangular pixels, 1: square pixels)

f

font name

c

codepage

-r

Use line endings with CR (DOS/Windows format).

default:

Enabled on Windows, disabled otherwise.

-s

Show SAUCE metadata instead of actual contents. If the input file does not have SAUCE, dos2ansi will fail.

-t tabwidth

Distance of tabstop positions.

min:

2

max:

screen width or 255

default:

8

-u format

Unicode output format, one of UTF-8, UTF-16 or UTF-16LE.

default:

UTF-8, on Windows UTF-16LE when output goes to a file or pipe.

-v

Use reverse attribute for intense background colors. With most terminals, this will actually result in reversed colors. It's only included for exotic terminals abusing this attribute to enable bright background colors.

Implies disabling explicit intense colors (-I) and conflicts with blink (-k).

-w width

Width of the virtual screen. If the width is available from SAUCE metadata, this flag is ignored.

min:

16

max:

1024

default:

80

-x

Attempt to use exact CGA/VGA colors. This requires a terminal capable of 256 colors and is used automatically when dos2ansi is built with curses and an appropriate terminal is found, or on Windows 10 and later.

-y

Use exact colors (see -x), but with a "dark yellow" color instead of adjusting it to brown, resulting in a palette you would see on some CGA machine when using a cheap monitor or a TV set.

infile

Read input from infile. If not given, input is read from the standard input.

ENVIRONMENT

TERM

When dos2ansi is built with curses support (non-Windows only), the output by default depends on the current value of TERM, even when writing to a file. This can be used to create files suitable for a specific terminal. To produce generic ANSI output instead, see the flags -a and -A.

AUTHORS

Felix Palmen <felix@palmen-it.de>