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

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

1 files changed, 181 insertions, 0 deletions

diff --git a/system/dos33fsprogs/man/dos33.pod b/system/dos33fsprogs/man/dos33.pod
new file mode 100644
index 0000000000..b854fa66ba
--- /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.