Appendix - File Format Converters
Author: Copyright (C) 2014 by CiderPress authors

File Format Converters

CiderPress can convert a variety of Apple II files into formats more easily accessible on a PC. BASIC programs can be converted into text program listings, AppleWorks word-processing documents become RTF (Rich Text Format) documents, and graphics become Windows BMPs.

The end-of-line (EOL) marker on text files changes from system to system. Macintosh and the Apple II use carriage returns (CR), UNIX systems use linefeeds (LF), and MS-DOS uses one of each (CRLF). Windows programs vary in their ability to handle text files with different EOL formats, but they all handle CRLF. CiderPress can convert all text files to Windows format if you desire.

DOS High ASCII (TXT)

Apple DOS stores text files with the high bit of every 8-bit byte set. This causes most other operating systems to display characters from an "extended" character set (accents, tildes, etc.) instead of the intended characters. This is usually undesirable, so all files from DOS disks with file type 'T' should be run through this converter to strip the high bit off. This will also convert the end-of-line character to CRLF.

CP/M Text (NON)

CP/M text files use CRLF line terminators, but also follow a convention that has fallen out of use under Windows: a Ctrl-Z marks the end of the file. This converter identifies text files on CP/M disks, and drops everything after the first Ctrl-Z. Files with unusual control characters embedded in them may not be identified as text.

UCSD Pascal Text (PTX)

UCSD Pascal disks have text files with an unusual format (done so for the benefit of the editor). These can be converted to text in a format that mimics the on-screen and printed output of the original.

UCSD Pascal Code (PCD)

The executable code files can be broken into segments, each of which is named and has a data type. The converter breaks the file into segments, and displays the segment header along with a hex dump of the contents.

Applesoft BASIC (BAS)

Applesoft programs are stored in a "tokenized" format, meaning that BASIC keywords like "FOR" and "NEXT" are stored as a single byte rather than a text string. This reduces program size and improves execution speed, but makes them hard to read on a PC. The Applesoft converter produces output identical to what you would see if you loaded the program and typed "LIST". If the appropriate preference is enabled, BASIC keywords, comments, and quoted text will be highlighted in color by default.

Integer BASIC (INT)

This is similar to the Applesoft converter, but for the older Integer BASIC format. Again, the output is identical to the "LIST" command.

It was not uncommon to stash machine-language code snippets at the start or end of an Integer BASIC program, resulting in a collection of junk. Usually some "LOMEM:" and "HIMEM:" commands were used to rearrange things so that the code gets hidden and only the BASIC program remains ("APPLEVISION", from the DOS 3.3 system master disk, is a classic example). The converted output of the machine-language parts may not match what "LIST" does, which is a good thing -- in some cases LIST would loop forever.

Asm source (TXT, INT, and $F4)

The S-C Assembler used the DOS 'I' file type, but doesn't use the Integer BASIC file format (it's a line-oriented compressed text file). Fortunately it's easy to tell the difference between S-C files and Integer programs. This converts the file to plain text.

The DOS versions of LISA (Lazerware's Interactive Symbolic Assembler), v2.5 and earlier, used a mildly tokenized format stored in DOS 'B' files. (This is the alternate type 'B', not the standard binary format; it shows up as type $F4 in CiderPress.) The ProDOS and GS/OS versions used the ProDOS INT type reserved for Integer BASIC, with the source written in a compressed format. The output is plain text, and matches the converted output of the original when written to a text file with the "write" command.

The file formats for LISA versions 2, 3, and 4 are different. All three are handled. Version 5 is equivalent to version 4, and the format for version 1 is unknown.

Merlin and Merlin-16 used a text format that crunched out excess spaces. The Merlin converter puts the spaces back in, so the output resembles what you'd see in the Merlin-16 full-screen editor. Merlin source files usually have filenames ending in ".S".

Disassembly (various)

Two modes of disassembly are currently supported:

- Apple //e monitor listing. This produces output identical to the monitor 'L' command on an Apple ][+ or //e, with two changes: 65C02 operands are supported, and NiftyList-style annotations are added.
- Apple IIgs monitor listing. Output is identical to the monitor 'L' command on an Apple IIgs, with the addition of NiftyList-style annotations. You may choose "short" (8-bit) or "long" (16-bit) registers.

See the Disassembly Notes section for more information.

8-bit Word Processor (various)

Currently supports Magic Window / Magic Window II "formatted" documents. These have file type BIN and end in ".MW".

AppleWorks Word Processor (AWP)

CiderPress does a fairly good job of converting AWP documents to Rich Text Format (RTF) files that can be edited with WordPad or Microsoft Word (the former is a Windows "accessory", and should be available on all systems). Most text styles are supported (bold, italic, underline, subscript, superscript), as well as paragraph formatting (left/right justified, centering) and some page layout features (left/right margins, page breaks).

AppleWorks Database (ADB)

Database files in AppleWorks are two-dimensional, with a fixed set of columns and one row for each entry. This converts easily to CSV (Comma-Separated Value) format, which can be imported into Microsoft Excel or other applications. The file viewer will show the data in CSV form, which isn't ideal but is much easier to read than the raw unconverted format. The first row of data holds the column titles.

AppleWorks Spreadsheet (ASP)

Spreadsheets tend to be tied to a specific application, and AppleWorks ASP files are no exception. Microsoft Excel does a pretty good job of converting formulas over, but you can expect to do some amount of hand-tweaking after conversion. Most formulas will transfer, but some (like @AVG) don't, and multi-cell labels will be chopped up. As with database files, these are converted to CSV format, which should be accepted by just about any modern spreadsheet application.

Apple IIgs Word Processor (GWP)

There are actually three formats here. All of them convert common symbols and accented characters from the IIgs fonts to Windows fonts. Not all of the symbols have equivalents, but many of them do. Text written in languages other than English should convert correctly.

The supported formats are:

- Teach document (GWP $5445). The "Teach" application on the Apple IIgs created these, which have text in the data fork and formatting information in the resource fork. Font size and style changes are supported, accented characters are converted, and an attempt is made to convert the typeface to something similar to the original. The results are ususally pretty good.
- AppleWorks GS Word Processor (GWP $8010). Same basic features as "Teach", plus some basic formatting features like centered and justified paragraphs. The "header" and "footer" sections are displayed at the top of the converted document.
- Generic (GWP, any aux type except the two above). Does a IIgs text conversion without any other reformatting. If you have a text file that uses symbols or accented characters from the IIgs font values, you can change its file type to GWP to enable this converter.

ProDOS Folders (DIR)

If you select a folder from a ProDOS disk for viewing, this converter will display it in a format similar to the 80-column output produced by the ProDOS "catalog" command. The active set of files are shown, followed by any deleted files that can be identified.

Enabling or disabling this converter has no effect on file extraction, because CiderPress doesn't explicitly extract folders. (It simply creates them when needed.)

Resources (resource fork of any file)

Resource forks have a well-defined structure. Each fork is a series of resources whose formats are defined by the user or by the system. This converter separates the fork into individual resources and displays their contents as hex dumps. Any recognized system-defined resources will have a type description displayed next to the resource type.

Hi-Res Graphics (FOT or 8K BIN, 280x192, six colors)

The classic Apple II graphics mode is "hi-res", featuring a resolution of 280x192. In some respects it's 140x192 (because two pixels are combined to form one color), in others it's 560x192 (because the Apple II display hardware used a half-pixel shift to get colors on a television).

The Hi-Res converter produces a 16-color, 560x384 bitmap file (BMP) that takes into account half-pixel shifting and other oddities. The results are usually identical to what you would see on an Apple IIgs RGB monitor. (If you set just the right pixels you can get yellow and brown on the hi-res screen of a real Apple II; in practice, this never really came up, so it isn't emulated here.)

If you select the black & white output mode, you will get a 16-color 560x384 image using only black and white. The image matches the Apple IIgs RGB monitor output except that the half-pixel shifting is left enabled. This was done to match the display of the IIgs composite output and other members of the Apple II line, which don't disable half-pixel shifting in monochrome mode by default.

Double Hi-Res Graphics (FOT or 16K BIN, 560x192, sixteen colors)

This graphics mode, first introduced on the enhanced Apple //e, can also be treated as 140x192, because four pixels are combined to form each color. In monochrome mode, the output is fully 560x192.

The Double Hi-Res converter produces a 16-color, 560x384 bitmap file (BMP) that attempts to recreate the output from an Apple IIgs RGB or composite output. Because of various weirdnesses in the Apple II display hardware, this is harder than you might think. As a result, there are actually four different ways to process the file. You can choose between them in the file viewer, or pick a default from the "Double Hi-Res mode" setting in the File Viewer tab of Preferences.

Black & White: output is in black and white only, full 560 pixels across. Output matches Apple IIgs RGB monitor display exactly.

Simple 140: produces 560x384 output as if the input were 140x384. The simplest and most "obvious" approach, it produces inferior results because the Apple II video hardware doesn't work this way.

Sliding window: converts the picture the way Apple IIe Tech Note #3 describes, using a 4-bit sliding window. The result closely matches the composite output on an NTSC device (monitor or television), but is much more blurry than the output of an RGB monitor because most transitions have a lot of color "fringes".

Latched color: a variation on "sliding window", this tries to reduce the fringes around transitions to and from black and white. The result renders the colors fairly well while sharpening up text.

Super Hi-Res Graphics (PIC/PNT or 32K BIN, 320/640x200)

First introduced on the Apple IIgs, Super-Res was the first mode largely devoid of video idiosyncracies. When you set pixels to certain colors, the output on an RGB monitor was exactly what you expected. The resolution, which could be changed on every line, was 200 lines of either 320 pixels across with 4 bits of color per pixel, or 640 pixels across with 2 bits of color per pixel. The way colors in the file were translated to colors on screen involves some minor color palette gymnastics. The output of the converter is a 256-color 640x400 BMP.

Super-Res images were also the first to be regularly compressed, which isn't surprising since they're 4x as large as standard hi-res. CiderPress can convert images in the following formats:

Unpacked ("PIC" $c1/0000)

Activision Paintworks ("PNT" $c0/0000)

Packed with PackBytes ("PNT" $c0/0001)

Packed Apple Preferred Format ("PNT" $c0/0002)

The Apple Preferred Format allows for images of arbitrary dimensions. CiderPress supports up to 1280x1024. Paintworks images are 320x396, and convert to a 640x792 BMP.

3200-Color Super Hi-Res Graphics

A clever fellow named John Brooks figured out that, if you changed palettes at just the right time, you could get more colors on the screen than would be otherwise possible. The results were sufficiently compelling to cause a number of GIF and JPEG converters to spring up, as well as one full-fledged 3200-color paint program. The files are always 320x200, and the output from the file converter is a 24-bit 640x400 BMP.

Most 3200-color pictures were stored in BIN files and given names like ".3200". Later on, official filetypes were specified, and some additional formats were developed. CiderPress can convert the following:

Unpacked ($c1/0002 or BIN ".3200")

Packed with PackBytes (BIN ".3201")

Packed Apple Preferred Format ($c0/0002 with "MULTIPAL" block)

For Apple Preferred Format, only 320x200 images are handled.

Print Shop Clip Art

Clip art from Print Shop "classic" usually comes on DOS 3.3 disks as a 576-byte 'B' file with a load address (aux type) of $4800, $5800, $6800, or $7800. The images unpack to 88x52 black & white BMP files.

Clip art files for Print Shop GS are 1716 bytes long, and use ProDOS file type $F8 with aux type $C323. The images unpack to 4-bit 88x52 BMP files.

The Print Shop GS editor doubles the width and triples the height, displaying a nearly-square 176x156 image. CiderPress does not magnify the image because that would make it awkward to manipulate the original pixels in an image editor.

MacPaint Graphics (*.mac)

The original Macintosh Paint program created monochrome 576x720 images. These represented a full printed page on a 72dpi ImageWriter printer. While not really an Apple II format, these were commonly found on BBS systems in the years when Apple IIs were popular.

CiderPress will attempt to identify MacPaint files that don't end in ".mac" by looking for a 128-byte MacBinary header with a 'PNTG' file type. MacPaint files transferred to other systems usually had this header.