Avalanche.guide

@database "Avalanche.guide"
@wordwrap

@node Main "Avalanche"
@{b}Avalanche@{ub}

@{"Introduction " link intro}
@{"Installation " link install}
@{"Configuration" link config}
@{"Usage        " link usage}
@{"ARexx port   " link arexx}
@{"Translations " link locale}
@{"Changelog    " link history}
@{"Contact      " link contact}
@endnode

@node intro "Introduction"
This is a simple ReAction based GUI for xadmaster.library.

It was written as everything similar on Aminet appears to require MUI, and the ones included with the OS over the years are not freely distributable.  AmigaOS 3.2 does not include such a tool, so Avalanche was born out of boredom of opening a shell and typing "lha x archive.lha".

It has since been extended to also support decrunching with xfdmaster.library, scanning extracted files with xvs.library, and basic editing/creation of LhA and Zip archives.

@endnode

@node install "Installation"
Please use the included Installer script.

If you must install manually, you can copy the program anywhere on your hard drive.
The install script additionally modifies the default tool for "archive" type files to be Avalanche.  In a standard install of OS3.2 this is used for all subtypes.

@endnode

@node config "Configuration"
Configuration is done via ToolTypes or through the equivalent options in the GUI.  Currently the following ToolTypes are recognised:

@{b}SOURCEDIR@{ub} Initial drawer to show in ASL requester (default = RAM:)
@{b}DEST@{ub} Destination to extract the archive to (default = RAM:)
@{b}TMPDIR@{ub} Path for temporary directory (default = T:)
@{b}VIEWMODE@{ub} LIST or BROWSER (default = BROWSER)
@{b}IGNOREFS@{ub} Enables the "Ignore filesystems" option
@{b}WINX@{ub}/@{b}WINY@{ub}/@{b}WINW@{ub}/@{b}WINH@{ub} Window position/width/height
@{b}PROGRESSSIZE@{ub} Size of progress bar (0-100) at window open
@{b}VIRUSSCAN@{ub} Use xvs.library to @{"scan files" link vscan} after extraction
@{b}CLOSE@{ub} Action to take when last window closed ASK|HIDE|QUIT (default = ASK)
@{b}NOASLHOOK@{ub} Disables the ASL filter so it shows all files
@{b}DRAGLOCK@{ub} Prevent adding files with drag'n'drop
@{b}AISS@{ub} Use AISS images (intended for OS4, probably won't work correctly on OS3.2)
@{b}MODULES@{ub} Select which modules to enable (XAD|XFD|DEARK) (default = XAD|XFD)
@{b}CX_POPUP@{ub} Whether to open the window on startup
@{b}CX_PRIORITY@{ub} Commodities priority
@{b}CX_POPKEY@{ub} Hotkey to show the window if hidden (default = ctrl alt a)
@endnode

@node usage "Usage"
Avalanche can be started as a default tool for an archive, or manually.  If started manually an archive can be selected using the button next to Archive, or by dragging it into the window.  Do not drop the file into a highlighted file list area, as this will add the archive to the one currently being viewed (see @{"editing" link editing}), rather than opening it.

It is possible to "quick extract" archives into their current directory by highlighting
and selecting "Extract here" from the Tools menu.

When a valid archive or crunched file is loaded, the contents will be displayed.  Unchecked items will not be extracted.

The state of checkboxes can be toggled by clicking on them, or by choosing "Select all" or "Clear selection" from the Edit menu.  Note that this will act on everything in the current and subdirectories when in the browser mode.

Clicking Extract will extract the archive to the chosen destination.  If @{"scan for viruses" link config} is enabled then Avalanche will scan each file using xvs.library after extraction.  Any infected files will be deleted.  See @{"virus scanning" link vscan} for more details.

The option to "Ignore filesystems" is only useful for DMS and similar disk archives.  Normally Avalanche will check for a valid filesystem, and list the individual files.  With this option set, the raw disk image will be listed instead.

If an Lha or Zip archive is loaded, basic editing is enabled, see @{"editing" link editing} for details.  These can also be created by selecting "New archive" from the Project menu.

@{b}Limitations@{ub}:
* Mixed file/disk archives are not supported.
* Disk images containing multiple filesystems are not currently supported.
* Encrypted archives are not fully supported.
* xadmaster.library v12 has some bugs relating to certain LhA archives.
  The fix is to use v13 - there is an experimental build for 68k at https://github.com/Hagbard-Celin/xadmaster_Amiga_68k

@endnode

@node editing "Editing"
If an LhA or Zip archive is loaded, it is possible to do basic editing.  Note that currently Zip editing needs zip.library and therefore is only available on OS4.  LhA requires the LhA command line tool.

In the Edit menu the following new items are available:

@{u}Add files@{uu}
This opens an ASL requester to select files to add to the archive.  They will be added to the root directory (or the currently displayed directory for Zip archives if in browser mode).  Directories are currently ignored - any tree structure will be flattened.

It is also possible to add files by dragging into the file list - the area will be highlighted to indicate that files will be added.

@{u}Delete selected items@{uu}
This deletes the currently selected items from the archive.  Note that this does not cascade into subdirectories, it only deletes the displayed files.

In the Project menu it is possible to create a new archive.  This displays another window to select a filename and type.  When the archive is created it is displayed.  A default file is added as empty archives are not supported.
@endnode

@node vscan "Virus scanning"
Avalanche can use xvs.library to scan files for viruses on extraction and addition.
xvs.library can be downloaded from https://www.vht-dk.dk/

Limitations:
Due to the way xvs.library works, files which do not completely fit into memory cannot be scanned.
Only Amiga viruses will be detected.
On OS4 the file xvs.l.main (included with Avalanche) needs to be copied to libs: alongside the main library (the install script will do this if xvs.library is installed already).
Infected files will be deleted without warning.
Files will not be further extracted in order to be scanned, so infected files that are individually compressed inside the archive will not be picked up.  It is recommended to run a scan with a full featured virus checker over any archives of concern.  
@endnode

@node deark "Deark"
Deark is a program which can extract all sorts of data from files, and convert obscure file formats to more modern ones.

Download from Aminet, source is at https://github.com/jsummers/deark

To use in Avalanche it needs to be present in the path, and enabled in the MODULES @{"tooltype" link config}.

There is a bug which prevents extraction to root directories on the Amiga, so currently extraction needs to be to a subdirectory.

The 68k version appears to be very unstable.

@endnode

@node arexx "ARexx port"
Avalanche has an ARexx port called "AVALANCHE".
This is mostly for internal use, but has the following commands:

@{b}OPEN@{ub} FILE/A
 - Open FILE in a new window
@{b}SHOW@{ub}
 - Show Avalanche or bring window to front
@{b}VERSION@{ub}
 - returns the current version number in RESULT

@endnode

@node history "Changelog"
@rem keep this to <80 chars for readme
@{u}2.4 (22.09.2023)@{uu}
* Support @{"Deark" link deark} (needs enabling by tooltype - see below)
  This is a "beta" feature, it may be unstable and due to a bug in
  Deark, it is not possible to extract to the root of any device.
* Add option to select modules (MODULES @{"tooltype" link config})
* Fix password caching
* Also use T: as temp by default from CLI

@{u}2.3 (16.06.2023)@{uu}
* Fix setting of list mode
* Remove tree in list mode view

@{u}2.2 (09.05.2023)@{uu}
* Visual improvements
* Added ability to use AISS images (on OS4)
* Added option to check for updates
* Fix the display of current settings in the prefs window
* Fix snapshot position and add a warning
* Fixed some Enforcer hits

@{u}2.1 (29.03.2023)@{uu}
* New browser mode, removed old hierarchical browser.
* Select/Clear/Invert selection now act on the current directory and
  all subdirectories when in the new browser mode.
* Basic editing of (LhA, Zip) archives (Zip needs zip.library - OS4 only)
* Create new (LhA, Zip) archives

@{u}1.11 (11.02.2023)@{uu}
* Improve window handling
  - Can now open new window from the GUI
  - Can select to ask/hide/quit when last window closed
    (NB: CONFIRMQUIT tooltype no longer used)
* Can now specify an archive on the command line

@{u}1.10 (12.01.2023)@{uu}
* Dragging a drawer into the window now sets the source directory, if
  an archive hasn't already been opened.
* Fixed some problems opening archives in certain circumstances.
* OS4 build now uses newlib.

@{u}1.9 (21.12.2022)@{uu}
* Add "snapshot window" option
   - note that the position is not saved unless save is clicked in prefs
* Add ToolType to disable the ASL hook (filters ASL req to only show archives)
* Add ToolType to set the initial drawer visible in ASL requester
* Fix iconify
* Rebuilt with optimisations

@{u}1.8 (07.12.2022)@{uu}
* Multiple windows supported internally. Limitations:
   - Commodities events only operate on the main (first) window
   - Does not spawn new process, so cannot use other windows whilst one is busy
* Simple @{"ARexx port" link arexx} added.
* Config options moved to separate prefs window
   - Note the options to snapshot the current window and change the default
     destination are currently not available. They can still be manually set
     through @{"tooltypes" link config}.

@{u}1.7 (03.08.2022)@{uu}
* Avalanche now registers as a commodity
* Added Tools menu item "Extract here" for quick extraction
* Fix initial state of "confirm quit" and "ignore fs" menu items.

@{u}1.6 (31.05.2022)@{uu}
* Add ability to extract disk archives to images
* Add ability to extract files from disk images/archives
* Double-clicking now extracts the clicked file to a temporary location and opens it.
  NB: This has required the previous "single click to select/deselect" to be disabled,
      as the functionality was incompatible.
  * Add option to enable/disable the quit confirmation requester
* Localisaton support
* Improved progress display - now shows current file progress and total
* Fix loading/saving of virusscan pref on OS4
* Fix unchecking of files in archive

@{u}1.5 (25.03.2022)@{uu}
* Add option to use xvs.library to scan the extracted files for viruses
* Fallback to xfdmaster.library if file not recognised
* Support encrypted archive entries
* Installer no longer overwrites existing icon on update
* Add Archive Info menu option - currently shows the filetype only

@{u}1.4 (16.03.2022)@{uu}
* Now includes OS4 native build
* Allow abort during extraction (button or ESC)
* Now asks whether to overwrite files
* ESC can now be used to quit, and Enter to start extraction
* List of files can now be sorted by clicking on the column header
* Clicking anywhere on the line now toggles the checkbox
* Now confirms quit
* Added option to invert selection to menu
* Striped listbrowser

@{u}1.3 (21.01.2022)@{uu}
* Due to a last minute error handling change, v1.2 won't extract many archives, oops.
* Added ability to drag or extended select more than one file

@{u}1.2 (20.01.2022)@{uu}
* Added options to select/clear all items
* Added option to save window size/position
* Added experimental hierarchical browser mode
* Added Date column to the archive view
* Added progress bar
* Window now accepts icons dropped on it
* Now correctly sets file protection bits, date and comments
* Fixed some layout issues

@{u}1.1 (11.01.2022)@{uu}
* First release
@endnode

@node locale "Translations"
Avalanche supports localisation using AmigaOS catalog files.
The built-in language is English.  This is the only official translation.
Catalogs for other languages may be created by using the translation files in "catalogs", and can be distributed separately.
@endnode

@node contact "Contact"
The best way to report bugs and request features is to submit them to the issue tracker at https://github.com/chris-y/avalanche

@endnode