diff options
Diffstat (limited to 'a8cat.rst')
-rw-r--r-- | a8cat.rst | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/a8cat.rst b/a8cat.rst new file mode 100644 index 0000000..3909391 --- /dev/null +++ b/a8cat.rst @@ -0,0 +1,102 @@ +===== +a8cat +===== + +------------------------------------------------------------- +Convert Atari 8-bit text to UTF-8 encoded Unicode (and back). +------------------------------------------------------------- + +.. include:: manhdr.rst + +SYNOPSIS +======== + +*a8cat* [**-r**] [**-i**] [**-u**] [**-t**] [*infile*] [*infile ...*] + +DESCRIPTION +=========== + +Convert Atari 8-bit ATASCII or XL ICS (International Character +Set) text to UTF-8 encoded Unicode. Control graphics characters are +replaced with their nearest Unicode equivalents (mostly from the Box +Drawing block, or from the Basic Latin block with **-i** option). + +If no *infile*\s are given, input is read from standard input. Output always +goes to standard output; to write to a file, use a command like:: + + a8cat atari.txt > converted.txt + +The output is UTF-8 Unicode, without BOM, but possibly with +ANSI/VT-100 control sequences. It will display correctly in modern +terminals that support Unicode and UTF-8. If you get lots of "empty +rectangle" characters, it means your font lacks the glyphs for the +codepoints; try using the Deja Vu Sans and/or Symbola fonts. + +If you want to pipe the output to a pager, **less -MR** is +recommended. It will display the inverse characters correctly. + +It's even possible to edit the converted text and turn it back into +ATASCII, if you're very careful. See the **-r** option, below. + +Inverse video (characters codes above **$80**) are translated using +the ANSI/VT-100 reverse video escape sequences. Exception: **$9B** +(Atari EOL) is translated to **\\n** (newline). + +OPTIONS +======= + +-i + Input uses Atari XL/XE International Character Set encoding, rather than + ATASCII graphics. + +-u + Use "underlining" for inverse video. Each inverse character is followed by + a backspace, then a *_* character. When viewed in a pager such as **less**\(1), + this causes the characters to appear underlined. Output created with this + option cannot be converted back to ATASCII with the **-r** option. + +-t + Text mode. Normally, everything but EOL (**$9B**) is converted to a + Unicode graphics character. In text mode, ATASCII tabs, backspace, + and bells are translated to the ASCII versions. + +-r + Reverse conversion: Input is plain text, or UTF-8 created by a previous + run of **a8cat**; output is ATASCII (or XL ICS, with **-i**). ASCII + tabs, backspaces, and newlines will be coverted to the ATASCII + equivalent. ASCII carriage returns will be silently ignored. + + Only the UTF-8 codepoints that correspond to ATASCII characters will + be converted. If the **-i** option was used to create the input, it + must be used with **-r** also. + + **a8cat** will refuse to print ATASCII to a terminal. You must + redirect or pipe the output. + +-m + Magazine listing mode. Rather than Unicode graphics characters, + ATASCII characters are printed in symbolic form, e.g. *{clear}* or + *{ctrl-A}*. The result is similar to type-in listings in magazines + like Antic, Analog, or Compute! Output created with this option + cannot be converted back to ATASCII with the **-r** option. + +-s + Strip the inverse video bit (bit 7) from all characters except the + EOL (**$9B**). Output created with this option can be converted + back to ATASCII with the **-r** option, but of course there won't + be any inverse-video characters in the result. + +-v + Verbose operation. + +**--** + End of options; the rest of the arguments are filenames. Use this if you're + trying to work with files whose names begin with *-*. + +**-h**, **--help** + Show built-in help and exit. + +**--version** + Show version number and exit. + +.. include:: manftr.rst |