system/dos33fsprogs: Added (Utilities for the Apple II DOS 3.3 FS).

Signed-off-by: Willy Sudiarto Raharjo <willysr@slackbuilds.org>

7 files changed, 601 insertions, 0 deletions

diff --git a/system/dos33fsprogs/man/dos33.pod b/system/dos33fsprogs/man/dos33.pod
new file mode 100644
index 000000000000..b854fa66ba04
--- /dev/null
+++ b/system/dos33fsprogs/man/dos33.pod
@@ -0,0 +1,181 @@
+=pod
+
+=head1 NAME
+
+B<dos33> - tool for accessing files inside an Apple DOS 3.3 disk image
+
+=head1 SYNOPSIS
+
+B<dos33> [-h] [-y] <disk_image> <command> [arguments]
+
+=head1 DESCRIPTION
+
+B<dos33> operates on Apple DOS 3.3 .dsk images, and allows copying files
+to/from the image as well as common DOS operations.
+
+=head1 OPTIONS
+
+=over
+
+=item -h
+
+Show built-in help message
+
+=item -y
+
+Answer "yes" to all confirmation prompts
+
+=back
+
+=head1 COMMANDS
+
+All commands are case-insensitive. Filenames within the image are
+case-sensitive. No globbing/wildcarding is done on files in the image.
+
+=over
+
+=item CATALOG
+
+Same as the DOS 3.3 CATALOG command. Lists the directory of the disk, with
+file name, type, lock status, and size in sectors.
+
+In case of duplicate filenames in the image, the first file listed in
+B<CATALOG> output will be the one operated on by the B<LOAD>, B<DELETE>,
+B<LOCK>, and B<UNLOCK> commands.
+
+=item LOAD B<apple_file> B<[local_file]>
+
+Copies a file out of the image, to the local filesystem. If B<local_file>
+is given, it will be used as the name of the output file, otherwise the
+file will be named the same as B<apple_file>.
+
+File contents are always copied verbatim. Text files will be in Apple
+II encoding, and can be converted to UNIX style text files with the
+B<dos33_text2ascii(1)> utility. BLOADable files (object code or binary
+data) will begin with a 4-byte header, giving the load address and length
+(minus the header) of the file in standard 6502 LSB/MSB format.
+
+=item SAVE B<type> B<local_file> B<[apple_file]>
+
+Copies a file into the image. If B<apple_file> is given, it will
+be used as the name, otherwise the file will be named the same as
+B<local_file>. No checking is done on the filename, so it's possible to
+create files with illegal names, as far as DOS 3.3 is concerned.
+
+If the file already exists in the image, you will be prompted whether
+to overwrite it. Use the B<-y> option to suppress the prompt and always
+overwrite.
+
+B<type> is one of the standard DOS 3.3 filetype characters:
+
+=over
+
+=item I
+
+Integer BASIC program
+
+=item A
+
+Applesoft BASIC program
+
+=item B
+
+Binary file (possibly BLOADable)
+
+=item T
+
+Text file (including EXEC batch files)
+
+=item S
+
+Source? Sequential? Rarely used.
+
+=item R
+
+Relocatable object module. Rarely used.
+
+=item N
+
+B<dos33> uses this character as a replacement for the "new A", aka
+0x20. In DOS 3.3's CATALOG command, these files show up as A. Rarely
+used.
+
+=item L
+
+B<dos33> uses this character as a replacement for the "new B", aka
+0x40. In DOS 3.3's CATALOG command, these files show up as B. Rarely
+used.
+
+=back
+
+Filetype characters are case-insensitive in B<dos33>.
+
+File contents are always copied verbatim, so e.g. text files need to
+already be in Apple II encoding (bit 7 set on each character, and 0x8d
+used for end-of-line). A UNIX style text file can be converted with
+B<tr(1)>, with a command like:
+
+tr '\n\040-\177' '\215\240-\377' < unix.txt > apple.txt
+
+To make an Apple BLOAD/BRUN object file from a raw binary, use the
+B<make_b(1)> utility.
+
+No checking is done on the file contents to see whether they make sense
+for the filetype given, so it's possible to e.g. store a text file with
+type A, or an Applesoft file with type B (binary). This isn't really a
+very useful thing to do, so try to avoid it.
+
+=item DELETE B<apple_file>
+
+Deletes a file inside the image. The file must exist and not be locked.
+=item LOCK B<apple_file>
+
+Locks (write-protects) a file inside the image. Locked files have a B<*>
+in the first column of B<CATALOG> output. Locked files may not be written
+to, deleted, or renamed.
+
+=item UNLOCK B<apple_file>
+
+Unlocks a file inside the image.
+
+=item RENAME B<apple_file_old> B<apple_file_new>
+
+Renames a file inside the image. No checking is done whether the new
+name already exists, so it's possible to create multiple files with the
+same name.
+
+=item UNDELETE B<apple_file>
+
+Undoes a B<DELETE>. This is only possible if the file's data sectors haven't
+already been overwritten with data from newer files. You will need to know
+the filename of the deleted file, which can be found in B<DUMP>'s output.
+
+=item DUMP
+
+Shows detailed information on the filesystem and files on the
+disk. Displays the VTOC, free sector bitmap, directory entries (including
+the ones for deleted files), and a hex dump of each sector marked "used"
+in the bitmap.
+
+=back
+
+=head1 SEE ALSO
+
+=over
+
+=item dos33fsprogs(1)
+
+=item a2tools(1)
+
+=back
+
+=head1 WEBSITE
+
+http://www.deater.net/weave/vmwprod/apple/
+
+=head1 AUTHORS
+
+B<dos33fstools> written by Vince Weaver <vince _at_ deater.net>.
+
+This manual page written by B. Watson for the SlackBuilds.org project,
+but it may be used by anyone.
diff --git a/system/dos33fsprogs/man/dos33fsprogs.pod b/system/dos33fsprogs/man/dos33fsprogs.pod
new file mode 100644
index 000000000000..09fb0f1dc918
--- /dev/null
+++ b/system/dos33fsprogs/man/dos33fsprogs.pod
@@ -0,0 +1,44 @@
+=pod
+
+=head1 NAME
+
+B<dos33fsprogs> - collection of tools for Apple II files and disk images
+
+=head1 DESCRIPTION
+
+B<dos33(1)> - tool for accessing files inside an Apple DOS 3.3 disk image
+
+B<make_b(1)> - add an Apple II BLOAD header to a binary file
+
+B<mkdos33fs(1)> - create Apple II DOS 3.3 filesystems in a .dsk image
+
+B<tokenize_asoft(1)> - convert ASCII into tokenized Applesoft
+
+B<asoft_detoken(1)> - convert tokenized Applesoft into ASCII
+
+B<integer_detoken(1)> - convert tokenized Apple Integer BASIC to ASCII
+
+B<dos33_text2ascii(1)> - convert Apple II text files to UNIX
+
+See the man page for each individual program for details.
+
+=head1 SEE ALSO
+
+=over
+
+=item a2tools(1)
+
+=item kegs(1)
+
+=back
+
+=head1 WEBSITE
+
+http://www.deater.net/weave/vmwprod/apple/
+
+=head1 AUTHORS
+
+B<dos33fstools> written by Vince Weaver <vince _at_ deater.net>.
+
+This manual page written by B. Watson for the SlackBuilds.org project,
+but it may be used by anyone.
diff --git a/system/dos33fsprogs/man/make_b.pod b/system/dos33fsprogs/man/make_b.pod
new file mode 100644
index 000000000000..58970f847c1a
--- /dev/null
+++ b/system/dos33fsprogs/man/make_b.pod
@@ -0,0 +1,80 @@
+=pod
+
+=head1 NAME
+
+B<make_b> - add an Apple II BLOAD header to a binary file
+
+=head1 SYNOPSIS
+
+B<make_b> <in_file> <out_file> <offset>
+
+=head1 DESCRIPTION
+
+B<make_b> prepends an Apple II BLOAD header to in_file and writes
+the result to out_file.
+
+The header is 4 bytes in size, and consists of the 16-bit offset (AKA
+the load address) followed by the 16-bit file length (of the rest of
+the file, not including the header). Both values are little-endian,
+which is standard on the 6502.
+
+=head1 ARGUMENTS
+
+All arguments are required. If any are missing or invalid, a built-in
+help message is displayed.
+
+=over
+
+=item in_file
+
+The input file. Must be small enough to fit in the Apple II's memory. The
+absolute maximum size is 65535 bytes, but a file that large can't be
+loaded into an Apple II because there are less than 48Kbytes of RAM
+available.
+
+=item out_file
+
+The output file. DO NOT use the same filename as in_file (see B<BUGS>). After out_file
+is created, it can be written to an Apple disk image with B<dos33(1)>.
+
+The output file will be exactly 4 bytes larger than the input file.
+
+=item offset
+
+The offset into the Apple's memory where the file will be loaded by the
+DOS 3.3 / Applesoft BLOAD command. Other names for this are the load
+address or start address. This is also the run address for files loaded
+with the BRUN command.
+
+B<offset> can be either decimal (no prefix) or hex (with 0x
+prefix). Beware that no error checking is done: in particular, don't
+forget the 0x prefix for hex addresses.
+
+=back
+
+=head1 BUGS
+
+Attempting to use the same file for input and ouput causes make_b to
+enter an infinite loop, writing garbage to the file until it fill up
+the partition.
+
+=head1 SEE ALSO
+
+=over
+
+=item dos33fsprogs(1)
+
+=item a2tools(1)
+
+=back
+
+=head1 WEBSITE
+
+http://www.deater.net/weave/vmwprod/apple/
+
+=head1 AUTHORS
+
+B<dos33fstools> written by Vince Weaver <vince _at_ deater.net>.
+
+This manual page written by B. Watson for the SlackBuilds.org project,
+but it may be used by anyone.
diff --git a/system/dos33fsprogs/man/mkdos33fs.pod b/system/dos33fsprogs/man/mkdos33fs.pod
new file mode 100644
index 000000000000..d45c1777f24d
--- /dev/null
+++ b/system/dos33fsprogs/man/mkdos33fs.pod
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+B<mkdos33fs> - create Apple II DOS 3.3 filesystems in a .dsk image
+
+=head1 SYNOPSIS
+
+B<mkdos33fs> [-h] [-t tracks] [-s sectors] [-b blocksize] [-d filename] <image.dsk>
+
+=head1 DESCRIPTION
+
+B<mkdos33fs> creates an Apple II DOS 3.3 formatted disk image, and optionally
+copies the boot record from an external file to make a bootable disk.
+
+By default, a standard 5 1/4" DOS 3.3 image is created, with 35 tracks, 16
+sectors/track, and 256 bytes per sector.
+
+=head1 OPTIONS
+
+=over
+
+=item -h
+
+Shows help message.
+
+=item -t <B<tracks>>
+
+Create image with this many tracks (default 35). Must be at least
+18. Maximum number is determined by the formula B<(block_size-0x38)/2)>.
+
+=item -s <B<sectors>>
+
+Create image with this many sectors per track (default 16). Must be
+between 2 and 32.
+
+=item -s <B<block_size>>
+
+Create image with this many bytes per sector (default 256, which is also
+the minimum size). Non-standard block sizes are allowed (up to 65536),
+but generally aren't supported by actual Apple hardware or DOS.
+
+=item -d <B<file>>
+
+Copy 3 sectors' worth of data from B<file>. This can be used to create
+bootable images, which will slightly reduce the amount of free space in
+the image's filesystem.
+
+=back
+
+=head1 SEE ALSO
+
+=over
+
+=item dos33fsprogs(1)
+
+=item a2tools(1)
+
+=back
+
+=head1 WEBSITE
+
+http://www.deater.net/weave/vmwprod/apple/
+
+=head1 AUTHORS
+
+B<dos33fstools> written by Vince Weaver <vince _at_ deater.net>.
+
+This manual page written by B. Watson for the SlackBuilds.org project,
+but it may be used by anyone.
diff --git a/system/dos33fsprogs/man/pcx2hgr.pod b/system/dos33fsprogs/man/pcx2hgr.pod
new file mode 100644
index 000000000000..a0ceed257776
--- /dev/null
+++ b/system/dos33fsprogs/man/pcx2hgr.pod
@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+B<pcx2hgr> - convert PCX files to Apple II HGR format
+
+=head1 SYNOPSIS
+
+B<pcx2hgr> file.pcx > file.hgr
+
+=head1 DESCRIPTION
+
+B<pcx2hgr> converts a PCX file to a BLOADable Apple II HGR or HGR2
+image, including palette conversion. Input is from the given filename,
+and output is to standard output.
+
+No scaling is done. The input file's X resolution must be either 140 or
+280 pixels, and the Y resolution should be either 160 or 192 pixels for
+proper display on the Apple II.
+
+The output is prefixed with a standard Apple II 4-byte BLOAD header. To
+display the image, use BASIC code like:
+
+
+=head1 SEE ALSO
+
+=over
+
+=item dos33fsprogs(1)
+
+=item a2tools(1)
+
+=back
+
+=head1 WEBSITE
+
+http://www.deater.net/weave/vmwprod/apple/
+
+=head1 AUTHORS
+
+B<dos33fstools> written by Vince Weaver <vince _at_ deater.net>.
+
+This manual page written by B. Watson for the SlackBuilds.org project,
+but it may be used by anyone.
+
diff --git a/system/dos33fsprogs/man/shape_table.pod b/system/dos33fsprogs/man/shape_table.pod
new file mode 100644
index 000000000000..e181e9118966
--- /dev/null
+++ b/system/dos33fsprogs/man/shape_table.pod
@@ -0,0 +1,116 @@
+=pod
+
+=head1 NAME
+
+B<shape_table> - generate shape table data from a text description
+
+=head1 SYNOPSIS
+
+B<shape_table> [-h] [-a] [-b] < input > output
+
+=head1 DESCRIPTION
+
+B<shape_table> reads a text description of a vector graphic from standard
+input and writes Apple II shape table data to standard output (as either
+binary data or BASIC DATA statements).
+
+=head1 OPTIONS
+
+=over
+
+=item -h
+
+Print the built-in help message and exit.
+
+=item -a
+
+Output BASIC DATA statements (also the default behaviour, so this option
+is redundant).
+
+=item -b
+
+Output BLOADable binary data.
+
+=back
+
+=head1 INPUT FORMAT
+
+The input consists of a series of lines. Each line is either a command,
+a blank line, or a comment.
+
+Blank lines are ignored. They must contain no extra whitespace characters,
+and must consist of only the \n character.
+
+Comments are ignored. They are marked with a B<#> in the first column
+(no leading whitespace), and continue to the end of the line.
+
+Commands consist of any text containing one of the draw instructions
+listed below. The instruction must be in upper case, and may be preceded
+and/or followed by anything at all (but only one instruction per line
+is read).
+
+=head2 Instructions
+
+Each instruction moves one pixel, in either plotting or non-plotting
+mode. The binary output of each command is shown here, prefixed with %.
+
+=over
+
+=item NUP
+
+Move up (non-plotting), %000
+
+=item NRT
+
+Move right (non-plotting), %001
+
+=item NDN
+
+Move down (non-plotting), %010
+
+=item NLT
+
+Move left (non-plotting), %011
+
+=item UP
+
+Move up (plotting), %100
+
+=item RT
+
+Move right (plotting), %101
+
+=item DN
+
+Move down (plotting), %110
+
+=item LT
+
+Move left (plotting), %111
+
+=back
+
+=head1 SEE ALSO
+
+=over
+
+=item Applesoft II BASIC Programming Reference Manual
+
+Shape tables are documented on page 96 of the author's copy.
+
+=item dos33fsprogs(1)
+
+=item a2tools(1)
+
+=back
+
+=head1 WEBSITE
+
+http://www.deater.net/weave/vmwprod/apple/
+
+=head1 AUTHORS
+
+B<dos33fstools> written by Vince Weaver <vince _at_ deater.net>.
+
+This manual page written by B. Watson for the SlackBuilds.org project,
+but it may be used by anyone.
diff --git a/system/dos33fsprogs/man/tokenize_asoft.pod b/system/dos33fsprogs/man/tokenize_asoft.pod
new file mode 100644
index 000000000000..5aaac1c9f20a
--- /dev/null
+++ b/system/dos33fsprogs/man/tokenize_asoft.pod
@@ -0,0 +1,65 @@
+=pod
+
+=head1 NAME
+
+B<tokenize_asoft> - convert ASCII into tokenized Applesoft
+
+B<asoft_detoken> - convert tokenized Applesoft into ASCII
+
+B<integer_detoken> - convert tokenized Apple Integer BASIC to ASCII
+
+B<dos33_text2ascii> - convert Apple II text files to UNIX
+
+=head1 SYNOPSIS
+
+B<command> < input > output
+
+=head1 DESCRIPTION
+
+These programs act as filters, reading from standard input and writing
+to standard output. None of them take any arguments or options.
+
+B<tokenize_asoft> acts like the Applesoft interpreter, in that it does
+no syntax checking while tokenizing (in Applesoft, syntax checking is
+done at runtime only). Each line requires a line number (no direct mode
+statements). The output file can be written to an Apple disk image with
+B<dos33>. Remember that BASIC programs use filetype A.
+
+B<asoft_detoken> and B<integer_detoken> act like the LIST commands
+from Applesoft and Apple Integer BASIC, respectively. They expect
+well-formed tokenized code, and may segfault or enter an infinite loop
+if fed invalid input. The output of these commands is a UNIX (not Apple II)
+text file.
+
+B<dos33_text2ascii> converts Apple II text files into standard UNIX
+text. The conversion is very simple: \r is converted to \n, and the
+high bit of each character is cleared. A side effect of this is that,
+if the input is already 7-bit ASCII with UNIX line endings, it will be
+passed through unmodified.
+
+There is no tokenize_integer command. There's also no dos33_ascii2text,
+but 7-bit ASCII UNIX text files can be converted with B<tr(1)>, something
+like:
+
+tr '\n\040-\177' '\215\240-\377'
+
+=head1 SEE ALSO
+
+=over
+
+=item dos33fsprogs(1)
+
+=item a2tools(1)
+
+=back
+
+=head1 WEBSITE
+
+http://www.deater.net/weave/vmwprod/apple/
+
+=head1 AUTHORS
+
+B<dos33fstools> written by Vince Weaver <vince _at_ deater.net>.
+
+This manual page written by B. Watson for the SlackBuilds.org project,
+but it may be used by anyone.