][GIF Version 1.0       Copyright 1988 Jason Harper
Permission is granted to give away copies of this program, and to upload it to
other online services and BBSes.  Commercial redistribution is not allowed.

WHAT IS IT?
][GIF allows you to convert and display GIF- and RLE-format graphics files on
Apple II series computers, and to save the converted pictures in standard
Apple graphics formats for use with other programs.

WHAT IS NEEDED TO RUN IT?
][GIF will run on a ][ or ][+ with at least 64K of memory, and the IIe, IIc,
and IIgs (although there is a better program available for the IIgs: look for
SHRConvert whereever you got this program).  It should work on any Apple
compatible machine, although I cannot guarantee this.  It runs only under the
ProDOS operating system, and can only work with GIF/RLE files stored on ProDOS
disks.

WHAT GRAPHICS MODES DOES IT SUPPORT?
][GIF can use normal HiRes graphics on any machine that it will run on.  In
addition, it can use the better DoubleHiRes graphics on machines that support
it: namely the IIc, IIgs, and any IIe with at least 128K of memory (except for
the Revision A IIe, which can't use DoubleHiRes).  In either graphics mode,
you can select either Black & White or Color conversion, which will produce
pictures appropriate for viewing on that type of monitor.  It's up to you to
make this choice: the program has no way of knowing what sort of monitor you
have, and cannot force one type of monitor to show the other type of graphics.

WHAT IS RLE?
RLE (Run Length Encoding) is an old B&W-only computer-independant graphics
format.  It comes in two sizes: High Resolution, which is 256 pixels wide by
192 high, and Medium Resolution, which is 128 by 96.  ][GIF supports both, and
blows up Medium RLE pictures to the same size as High.  All RLE's are
converted into HiRes B&W mode regardless of the graphics mode preference you
have specified: using DoubleHiRes for them would be a waste of resolution.

HOW CAN RLE FILES BE DOWNLOADED?
There are basically two ways to download files: text capture (also known as
'capture buffer', 'DC2/DC4', and various other names), and protocol (Xmodem,
Christensen, CIS-B, and Kermit are common protocols).  Protocol transfers are
usually preferred, since they can detect and correct any transmission errors:
a single error in a text capture transmission usually makes the data useless.
RLE files can be received by either method, although in some applications
(online graphs, maps, etc.) you may not have the option of using a protocol
download.  If you do use text capture, your terminal program MUST be able to
capture all control characters intact: if it removes non-printable characters
from a RLE file, it will not be usable.

WHAT IS GIF?
GIF (Graphics Interchange Format) is a new standard developed by CompuServe to
supplement RLE.  It allows pictures of arbitrary dimensions and up to 256
colors (with techniques available to represent even more colors than that).
GIF also uses a much more efficient data compression scheme than RLE:
unfortunately, the complexity of de-compressing the data, plus the difficulty
of coming up with a close approximation of arbitrary colors on a machine that
can only display a few colors, makes the decoding of GIF files a lengthy
process.  All but the simplest files will take over a minute: the most complex
may take 15 minutes.  Of course, once the file is decoded you can save it in
normal Apple format, and re-display it in a matter of seconds.

HOW CAN GIF FILES BE DOWNLOADED?
You absolutely must use a protocol download to receive GIF files: text capture
simply won't work.  You should download them with a ProDOS-based terminal
program: they are unlikely to convert successfully if downloaded under DOS 3.3
and then moved to a ProDOS disk.  You can get them from DOS 3.3 to ProDOS
successfully if you use a sector editor to change the DOS 3.3 file's type to
"R" before converting, but this is a somewhat dangerous process and is to be
done only at your own risk.  Also, a warning: version 1.0 of the FreeTerm IIgs
terminal program can't download GIF files at all.  If your terminal program
gives you a choice of filetypes for downloaded files, pick TXT or BIN.

WHAT SORT OF GIF FILES CONVERT WELL?
Needless to say, a 256-color GIF picture that was generated on a computer with
many times the resolution of your Apple II simply isn't going to look as good
as the original when converted.  ][GIF does the best job of conversion that I
know how to make it do, and will never reject a file due to excessive colors
or resolution, but I simply cannot guarantee that it will perform well on any
particular picture: you download GIF files at your own risk.  Fortunately,
most GIF files available for download have their resolution and number of
colors given in their description and/or keywords, so that you can identify
pictures that are more likely to convert well.  Avoid large files: anything
longer than 30 kilobytes is probably useless.  Avoid files with more than 32
colors.  Avoid files with more resolution than 320 x 200, unless they are
2-color (monochrome) and you have DoubleHiRes capability.  You are welcome to
try files outside of these limits, just don't expect impressive results.

HOW IS ][GIF USED?
The file 'IIGIF' is a ProDOS SYStem program, and can be run from any
ProDOS-based program selector, or from ProDOS Basic by typing:   -IIGIF
from the ] prompt.  You can also make an auto-booting ][GIF disk by copying
the files IIGIF and PRODOS to it, then renaming IIGIF as 'IIGIF.SYSTEM'.  All
program operations are performed by using the arrow keys to move the hilited
selection up or down to the desired option, then pressing Return.  In many
places, you can also press Escape to return to the previous menu.  The first
thing you'll want to do is use 'Set preferences' to pick the graphics mode you
want to use: see the individual command descriptions below.

'SET PREFERENCES'
This allows you to specify which of 4 graphics modes are to be used for future
GIF conversions: HiRes B&W, HiRes color, DoubleHiRes B&W, or DoubleHiRes
color.  The DHR options are disabled on ][, ][+, and 64K IIe computers, since
they don't have the required hardware to support that mode.  You should
generally select DHR if your computer supports it, and Color if your monitor
supports it, unless you are converting pictures for later use on a different
system that doesn't have those features.  You will be given an option to save
the preference you have selected, to be used every time you run ][GIF: the
preference is stored in the IIGIF file itself, so the disk containing it must
be in a disk drive and not be write-protected at the time you do the save.

'CONVERT GIF PICTURE'
Starts the conversion process for a GIF file.  You should have no trouble
using the file selection routine, IF you are familiar with ProDOS terms such
as 'directory', 'volume', and 'prefix'.  If not, just play around with it:
there's no way to damage a disk with the file selector.  Upon selection of a
valid GIF file, you will be asked if you want to use default scaling and
positioning or not.  The defaults will result in a centered picture, scaled so
that most of the picture will be onscreen: use it for your first look at a
file.  If you decide not to use the defaults, you'll be presented with a
series of menus asking for conversion parameters: these should be
self-explanatory.  In each menu, the default selection will be marked with an
asterisk.  The actual conversion process will then begin: you will be able to
see the conversion on screen.  Don't worry if there are long pauses during
which nothing seems to happen, this is normal.  When the conversion is
finished, the computer will make a funny noise: press Return when you're done
looking at the final picture.

'RE-CONVERT LAST GIF'
Starts another conversion of the last GIF file you converted.  The disk
containing the file must still be in a disk drive.  Useful for looking at the
picture in a different graphic mode, or to use different conversion parameters
to zoom in on some part of the picture.  For example, if a picture appeared to
have an artist's signature in its lower right corner, but was unreadable with
the default parameters, you may be able to read it by reconverting with the
Horizontal and Vertical Scaling set to their topmost values, a Horizontal
Position of 'right', and a Vertical Position of 'bottom'.

'CONVERT RLE PICTURE'
Works just like 'Convert GIF picture', but there are no parameters to set.

'LOAD HIRES/DHR FILE'
Allows you to view a HiRes or DoubleHiRes picture saved in standard Apple
format, such as a previously converted GIF picture saved with 'Save picture'.
DoubleHiRes pictures will be rejected on machines without DHR capability.  If
you're using a IIgs, you'll have a couple of extra options here: see 'View
picture again' for details.

'VIEW PICTURE AGAIN'
Lets you look at the most recently converted or loaded picture again.
Produces garbage if no picture has been converted or loaded yet.  Press Return
to return to ][GIF's main menu.  If run on a IIgs, there will be two
additional keys that function here (or anywhere else in this program that a
picture is displayed): hitting 'B' will force the picture to be shown in black
& white, and 'C' will force it to be shown in color.  These do NOT have the
same effect as reconverting in the other graphic mode: they just show you what
the existing picture would look like on a computer with the specified type of
monitor.

'SAVE PICTURE'
Saves the current picture in standard Apple format, for quicker redisplay.
There's no question about the format of HiRes graphics files, however some
programs use a nonstandard two-file format for DoubleHiRes: ][GIF can neither
load nor save in this format.  You can convert between the two DHR formats by
typing the following commands from ProDOS Basic:

>Convert a standard file 'DHRPIC' into nonstandard files 'NSPIC' & 'NSPIC.AUX':
BLOAD DHRPIC,A$2000
BSAVE NSPIC.AUX,A$2000,L$2000
BSAVE NSPIC,A$4000,L$2000

>Convert nonstandard files 'NSPIC' & 'NSPIC.AUX' into a standard file 'DHRPIC':
BLOAD NSPIC.AUX,A$2000
BLOAD NSPIC,A$4000
BSAVE DHRPIC,A$2000,L$4000

Using the file selector for saving is slightly different from loading.
Assuming that you want to save as a new file rather than overwriting an
existing file, you should move to the desired disk or subdirectory just as you
would when loading, and then select the [enter filename] option.  Type in the
desired filename (remember the ProDOS limitations: maximum 15 characters, must
start with a letter and contain only letters, digits, and periods).  You'll be
given an option to enter a different name, create a subdirectory by that name,
or make a new file: the last one is what you want.  You can then use 'Load
HiRes/DHR file' to verify that the picture was properly saved to disk.

'PRODOS COMMANDS'
Allows you to lock, unlock, rename, or delete files on a ProDOS disk.  Works
just like the file selector: move the hilite to the desired file, hit Return,
and choose the desired action from the resulting menu.  To rename or delete a
subdirectory, follow the same steps: you'll get a listing of that directory
rather than the actions menu, but you can then select [select this dir.] to get
the menu.  You can rename a disk by selecting [select this dir.] when its
volume directory is on the screen.

'QUIT'
Exits ][GIF.  If you ran it from a program selector, you will be taken back to
the program selector.  Otherwise, you'll get the standard ProDOS QUIT routine,
allowing you to enter the prefix and then pathname of the next SYStem program
you want to run.  To get back to ProDOS Basic, you'd type 'BASIC.SYSTEM' as
the pathname for example.

ANY QUESTIONS, COMMENTS, GRIPES, OR SUGGESTIONS?
Send them to me at one of the following online addresses:
  CompuServe: 76703,4222 (preferred)
  GEnie:      JR.HARPER
I would prefer not to have any mail or phone correspondence about ][GIF.

Portions of ][GIF were based on copyrighted source code supplied by
CompuServe, Inc. to members of the GIF Developer's Team, based in the Pictures
Support Forum (GO PICS).  Which is also the best source of GIF files.

Thanks to Ken Paul for assistance in testing this program.

        Jason Harper