system/franny: Added (Atari 8-bit disk image utility).

Signed-off-by: David Spencer <idlemoor@slackbuilds.org>

1 files changed, 286 insertions, 0 deletions

diff --git a/system/franny/franny.rst b/system/franny/franny.rst
new file mode 100644
index 0000000000..65a5a3c798
--- /dev/null
+++ b/system/franny/franny.rst
@@ -0,0 +1,286 @@
+.. RST source for franny(1) man page. Convert with:
+..   rst2man.py franny.rst > franny.1
+.. rst2man.py comes from the SBo development/docutils package.
+
+.. |version| replace:: 1.1.3
+.. |date| date::
+
+======
+franny
+======
+
+-----------------------------
+Atari 8-bit disk image editor
+-----------------------------
+
+:Manual section: 1
+:Manual group: SlackBuilds.org
+:Date: |date|
+:Version: |version|
+
+SYNOPSIS
+========
+
+franny [*-options*] [*file.atr*]
+
+franny-extract.sh [*file.atr*] [*target_directory*]
+
+franny-insert.sh [*file.atr*] [*source_directory*]
+
+DESCRIPTION
+===========
+
+Franny is an ATR and XFD disk image editor. It supports AtariDOS II and
+SpartaDOS 2 and 3 disk formats. Single, enhanced, double, and custom
+formats are supported, though writing to AtariDOS images is limited to
+the first 720 sectors.
+
+There are also two scripts:
+
+franny-extract.sh
+  dump all files from ATR or XFD to specified directory (works like atr2unix)
+
+franny-insert.sh
+  insert all files from specified directory to ATR (works like unix2atr)
+
+OPTIONS
+=======
+
+All options that take an argument require a space between the option
+and its argument, *except* the -L option, which doesn't allow a space.
+
+Generally, uppercase options can be thought of as commands, which edit
+the given disk image, and lowercase options can be thought of as options
+to the uppercase commands.
+
+-A
+  Add file to image. Paths must be given by using -i and -o. Writing past
+  sector 720 on an AtariDOS image is not supported.
+
+-C
+  Create new image. Will not be bootable. Use -d, -f, -m, -s, -t, -T options
+  to control the image type. Default is 256 bytes per sector, 720 sectors,
+  SpartaDOS filesystem, ATR image, normal (non-sio2ide) image type.
+
+-d [s|d]
+  Sector size for -C [single|double]; default: double. Single is 128 bytes/sector, double
+  is 256.
+
+-f [a|s]
+  File system type for -C [AtariDOS II|Sparta 2.0]; default: Sparta 2.0.
+
+-F
+  Format image. Ignores any -d, -f, -m, -s, -t, -T options.
+
+-h
+  Show help and exit.
+
+-i filename
+  Input filename (source file for -A and -S). When using the -S option,
+  the filename is treated case-insensitively, unless it contains a
+  directory path.
+
+-I
+  Image summary. Shows disk label, filesystem type, density, total
+  sectors, free sectors, image type (standard or sio2ide) and image
+  media (ATR for ATR images, RAW for XFD images).
+
+-l format
+  List format used by -L. Default is **"A F.E S B D T"**. The format specifiers
+  are:
+
+  **A**: Attributes (R for locked files, D for directories, H for hidden files)
+
+  **B**: Size in bytes
+
+  **D**: Date. For AtariDOS images, this is always "00-00-2000".
+
+  **E**: Filename extension
+
+  **F**: Filename (minus the extension)
+
+  **S**: Size in sectors
+
+  **T**: Time. For AtariDOS images, this is always "00:00:00".
+
+  Any other character represents itself. The list above is case-insensitive.
+
+  For example, this gives a more AtariDOS-like display:
+
+    franny -L -l "fe s" file.atr
+
+-Lmask
+  List directory. Mask is optional; default: \*.\* (all files). NOTE
+  that NO SPACE is allowed before the mask, unlike all the other franny
+  options! Also, the mask is case-sensitive (e.g. -L*.SYS, not -L*.sys).
+  Files using the DOS 2.5 extra sectors on enhanced density disks will
+  display, but without the < > around them like DOS 2.5 does.
+
+-m [a|r]
+  Media type for -C (atr|raw); default: atr. Raw images are also known as XFD images.
+
+-M dirname
+  Create directory. Only works for SpartaDOS images.
+
+-N name
+  Set volume name. Only works for SpartaDOS images.
+
+-o filename
+  Output filename (destination file for -A and -S). When using the -A option,
+  the filename is treated case-insensitively, unless it contains a directory path.
+
+-O [a|r]
+  New media type (BROKEN). This option is apparently supposed to convert
+  between ATR and XFD, but it doesn't appear to actually do anything.
+
+-R dirname
+  Remove dir. Only works for SpartaDOS images.
+
+-s sectors
+  Total sectors for -C. For standard single or double density, use 720. For 1050 enhanced
+  density (aka 'medium'), use 1040.
+
+-S
+  Save (extract) filename from image. Paths must be given with -i and -o.
+
+-t [s|m|d|f|F]
+  Image templates for -C [single|medium|double|full/Full(65535 sectors, 128/256 bytes each)].
+  Used for -C option. 's' is equivalent to "-s 720 -d s", etc.
+
+-T [d|s]
+  change image type (default|sio2ide). Only applies to ATR images, not RAW/XFD.
+
+-U Filename
+  Unlink (remove) file. filename is case-sensitive.
+
+-v
+  Show version and exit.
+
+-V sector
+  view (dump) sector in hex and ASCII. Output is OK for ATR images but
+  badly formatted for raw/XFD.
+
+EXIT STATUS
+===========
+
+franny returns 0 for success and non-zero for failure. On failure,
+a diagnostic message is printed to standard error.
+
+DIAGNOSTICS
+===========
+
+franny: You can specify only one command.
+
+  Only one of the -A -C -I -L -M -N -O -R -S -T -U -V options may be given.
+
+franny: Cannot open image '[*image*]'
+
+  This means the image is invalid. Either it's not actually an Atari
+  disk image, or it's a boot disk that doesn't contain a filesystem,
+  or it's a truncated image (see NOTES), or you don't have permission
+  to read the file.
+
+franny: Specified file is not regular file.
+
+  Means the image file or the file given to the -i / -o options doesn't
+  exist, or is something other than a regular file or a symlink to a
+  regular file (e.g. a directory or a device node).
+
+franny: Command failed.
+
+  Catch-all error message. Can be caused by:
+
+    - attempting to access a nonexistant file in the image
+
+    - a 'disk full' condition (trying to copy too much data into the image)
+
+    - trying to create/delete a subdirectory on an AtariDOS image (currently not supported)
+
+    - trying to delete or overwrite a locked file in the image (unfortunately franny has no way to unlock files)
+
+franny: Cannot change directory.
+
+  For SpartaDOS images, the given subdirectory doesn't exist within the image. Remember to use >
+  as a path separator, and quote any arguments containing > to avoid the shell
+  interpreting it as a redirection. Also, directory names are case-sensitive.
+
+  For AtariDOS images, any attempt to copy files to/from a subdirectory
+  will give this error, as subdirs aren't supported in AtariDOS images.
+
+NOTES
+=====
+
+franny is intended for use only with disk images containing
+AtariDOS/MyDOS-compatible or SpartaDOS 2/3 filesystems. Attempting to
+edit non-filesystem-bearing images (such as boot disks) will fail and/or
+have unpredictable results.
+
+Most emulators support truncated or 'short' disk images, where only the
+sectors actually used are stored in the file. franny is unable to operate
+properly with truncated images, even if the missing part of the image
+contains no filesystem data (sectors containing all zeroes). This type
+of image can be turned back into a full image with a dd command such as
+
+  dd if=truncated.atr of=fixed.atr bs=92176 count=1 conv=sync
+
+92176 is for a single-density image. Replace with 184336 for double density
+or 133120 for 1050 enhanced density. For ATR images, this is **(number_of_sectors * bytes_per_sector) + 16**. For XFD (raw) images, don't add the 16.
+
+The -I option will mis-identify most non-filesystem boot or data disks as
+containing a Sparta 2 filesystem. The other options will (usually?) fail
+with 'Cannot open image' for non-fs disks (see DIAGNOSTICS).
+
+Filenames within the image can be entered in lowercase with the -i or -o
+options, but they're always converted to uppercase (and truncated to 8.3
+format, if they're not already). If the filename contains a directory
+path, only the base filename gets converted, NOT the directory name(s).
+Also, this ONLY applies to -i and -o. The other options that take Atari
+filenames require them to match exactly (e.g. -U autorun.sys will fail,
+use -U AUTORUN.SYS instead).
+
+There is no way to delete or overwrite a locked file within the image, as
+franny has no Unlock option. There's also no Lock option.
+
+Also missing is a Rename option. To rename a file, do something like this:
+
+  franny -S -i sxhand.sys -o sxhand.sys image.atr
+
+  franny -U SXHAND.SYS image.atr
+
+  franny -A -i sxhand.sys -o autorun.sys image.atr
+
+The above renames SXHAND.SYS to AUTORUN.SYS. Note that the -U option
+required the filename in uppercase.
+
+The -O option doesn't work. You can convert an ATR image to a raw one
+with dd:
+
+  dd if=disk.atr of=disk.xfd bs=16 skip=1
+
+BUGS
+=====
+
+Some things are not implemented yet. Main disability is write support for
+enhanced density in AtariDOS II disk format. Second problem is mydos's
+subdirectories. An extra tool to develop is a gui.
+
+The -O (new media type) option doesn't work.
+
+The franny-insert.sh script will fail, if any of the files/directories
+contain spaces or other shell metacharacters such as > or \|.
+
+Report bugs to ten.egrofecruos.stsil@leved-8irata.
+
+COPYRIGHT
+=========
+
+See the file /usr/doc/franny-|version|/copying for license information.
+
+AUTHORS
+=======
+
+Rafael 'Bob_er' Ciepiela <ten.egrofecruos.sresu@re_bob> - Coder and designer of the franny program itself.
+
+This man page written for the SlackBuilds.org project
+by B. Watson, and is licensed under the WTFPL.
+