Giuseppe Torelli

    colossus73@gmail.com

2005–2008

This document is distributed under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license can be found in the file COPYING included with the source code of this program.

Caution!

This documentation is a bit outdated. It may still be useful, though.

# &app; &appversion;

## Introduction

### About &app;

&app; is a small and lightweight archive manager. I developed it to manage archives without depending from a special Desktop Environment like KDE or GNOME, so &app; requires only the GTK+ toolkit to work. The package xdg-utils is optional.

&app; presents the following characteristic:

- Archive directories can be browsed just like a file manager

- Mime icon for each of the archive entries

- The most used archiver's command-line options are supported in the Add and Extract dialogs

- Tabs Firefox style support

- Multi-extract facility

- Dump of the whole archive content as HTML or text file

- Context menu on each of the archive entries with cut/copy/paste/rename abilities

- All archives are detected by their magic header and not by their extension

- Drag and drop from and to &app; window

- Progress window when using &app; from the command line or from a file-manager

- ARJ, RAR and ZIP archive comment are supported

- Ability to convert the archive to self-extracting for those archive types which support it

- Smart detection of 7zip, arj, lrzip, rar and zip password encrypted archives

- All the the output of the command-line archiver is displayed in the &app; window

- All common formats are supported: 7z, a (libraries), apk, AppImage, arj, bzip, bzip2, bzip3, cab, cb7, cbr, cbt, cbz, chm, compress, cpio, docx, epub, exe (self-extracting Windows archives), fbz, gzip, iso, jar, jsonlz4, lha, lrzip, lz4, lzip, lzma, lzop, mozlz4, odt, oxt, rar, rzip, snap, squashfs, tar, xpi, xz, zip, zpaq, zstd, tar.bz, tar.bz2, tar.bz3, tar.gz, tar.lrz, tar.lz, tar.lz4, tar.lzma, tar.lzo, tar.rz, tar.xz, tar.Z, tar.zst, deb and rpm packages

- Debian and RPM packages are handled internally, their package managers are NOT required

- Password encrypted 7zip, arj, lrzip, rar and zip archives are fully supported

### Where to get it

You can obtain &app; from &appurl; or perhaps from your distributor.

### License

&app; is distributed under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license can be found in the file COPYING included with the source code of this program.

## Installation

### Requirements

For compiling &app; yourself, you will need the GTK+ (>= 2.10.0) libraries and header files. (You will also need the GLib, Pango and ATK libraries and header files as well as libraries and header files needed by these). All these files are available at http://www.gtk.org.

### Source compilation

Compiling &app; is quite easy. The following should do it:

    					$ ./configure [--prefix=/usr]
    					$ make
    					# make install

The configure script supports several common options, for a detailed list, type:

    					./configure --help

## Usage

### Getting started

You can start &app; in the following ways:

- From the Desktop Environment menu

  Choose in your application menu of your used Desktop Environment: Accessories &app; .

- From the command line

  To start &app; from a command line, type the following and press Enter/Return:

      								&applower;

### Command-line options

Command-line options

Short option | Long option | Function
--- | --- | ---
-x destination archive | --extract-to=destination archive | Extract archive to the destination directory and quit.
-e archive | --extract archive | Extract archive by asking the destination directory and quit.
-d archive | --ensure-directory archive | Extract archive to a containing directory and quit.
-m [archive1 ... archiveN] | --multi-extract [archive1 ... archiveN] | Open the Multi-Extract dialog to extract the given archives. Shell wildcards such as * are allowed.
-c file1 ... fileN | --compress=file1 ... fileN | Add the given files by asking the name of the archive and quit. If the archive doesn't exist it will be created. The filenames must be separated by spaces.
-a archive | --add archive | Add to archive by asking which files and quit.
-i | --info | Show found command-line programs to be used and exit.
-v | --version | Show version and exit.
-? | --help | Show help information and quit.

&app; supports also all generic GTK+ options, a list is available on the help screen.

### General

#### Startup

At startup, &app; detects the available installed archivers (tar,rar,zip etc) and the script xdg-open for handling different file types. Since &app; is a front end (a graphic user interface to the command-line executables) it can't create archives whose archiver is not available. For instance if you have the free edition of rar, unrar, &app; can't create rar archives since unrar allows rar archives to be opened, tested and extracted but not to be created.

#### How it works

&app; will run in the background the command-line executable of the archiver with the archiver's proper switches to perform the selected operation. If something goes wrong &app; reports the full output of the archiver executable in the command-line output window. Starting with release 0.5 the files in the archive can be opened within &app;. The script xdg-open will detect the file type and run the proper application to handle it. If you don't have such script installed in your system (it's found in the xdg-utils package) &app; will recognize HTML, txt and images files only. The Preferences dialog will notify this to you when you click the Advanced section inside it.

#### Drag and Drop

&app; supports drag and drop through the XDS protocol. As far as I know only Thunar and Nautilus file managers supports it. Files and directories can be dragged from such file manager's windows to &app; and vice versa. If its window is empty (no archives open) &app; will prompt the user with the asking for the filename and the archive type to be created; after which the dragged files will be added. If the dragged file is a supported archive, &app; will open it instead of prompting the new dialog.

### &app; menu

#### File menu

##### New

Creates a new archive. The new archive dialog is opened. The archive is not effectively created until some content is added to it. Please note if the archive already exists and you choose to overwrite it, the existing archive will be deleted.

New dialog

##### Open

Opens a new archive. If you force &app; to open an unsupported archive type an error message will be emitted. The archive type is detected by its magic header and not by the extension. Password protected 7zip, arj, lrzip, rar and zip archives are also supported.

##### List as

This facility allow you to dump the content of the whole archive as .txt or .html format.

##### Save as

Save the current archive in a different location. This is useful when you open an archive from the Web browser and you want to save it to a different location from /tmp.

##### Test

Tests the current archive. This option is disabled when the current archive was produced by an archiver which doesn't support testing.

##### Properties

Shows an archive dialog with useful info about the archive.

Archive properties dialog

##### Close

Close the current archive and frees all the memory in use by it.

##### Quit

Frees all the memory in use and quit &app;.

#### Action menu

##### Add

Shows the add dialog featuring the most used archiver command-line options. The password entry is disabled when the archive doesn't support encryption.

Add dialog

##### Extract

Shows the extract dialog featuring the most used archiver command-line options. The password entry is disabled when the current archive is not encrypted; instead if the archive is encrypted and you don't fill this field, &app; will request you the password to extract the archive.

Extract dialog

##### Delete

Delete the selected files from the archive. A warning dialog will be shown.

##### Rename

Allows to rename the current selected file. Renaming directories is not allowed.

##### Make SFX

Convert the current archive to self-extracting. This option is disabled when the current archive doesn't support this feature (e.g. tar archives). After converting an archive to self-extracting this option will be disabled.

##### Multi-Extract

Open the Multi-Extract dialog allowing you to extract archives in one shot by loading them in the window. You can choose to extract them in a specific directory or to extract each of them in a directory named with the archive name itself.

Multi-Extract dialog

##### Archive comment

Opens the Archive comment dialog. Here you can modify, load from a file or delete the archive comment.

Archive comment dialog

##### Select all

Select all the entries in the window.

##### Deselect all

Deselect all the entries in the window.

##### Select by pattern

Pops up the Select by Pattern dialog. Shell wildcards like * and ? are supported.

##### Command-line output

Opens a window containing the last archiver output.

##### Enter password

Pops up the Password dialog. This facility was introduced because of 7zip archives. If you notice that &app; freezes while extracting from such archives you can try to enter the password by means of this dialog before extracting them.

Password dialog

##### Preferences

Open the preferences dialog where you can set several options. All the options are saved to ~/.config/&applower;/&applower;rc when pressing the Ok button.

Preferences dialog

#### Help Menu

##### Help

Show this documentation in system installed Web browser.

##### About

Shows the credit dialog with the contributors to &app;

## FAQ

### Why are ace archives not supported?

Because on some strange reasons there is no support on Linux for creating archives, only extraction with unace. When they will develop full support for ace archives I will add it to &app;.

### How can I create an archive with some files password protected and others not?

First of all choose 'New' and select one of the 7zip, arj, lrzip, rar or zip archive formats and choose 'Add' from the Action menu. Do NOT check "Password" in the Add dialog. Add your files and then reopen the Add dialog again but this time check "Password" and enter your password. From now on all the files you add to the archive will be password protected.

### Why does &app; emit this error message when handling tar archives?

&app; is only a front end which runs the archiver and reports ITS error messages. Most probably you are opening an archive produced with older versions of tar than the one you are currently using or the archive is corrupted.

### Why is the option "Extract with full path" disabled when using the -e switch with tar archives?

Because GNU tar does not provide a full way to extract files without the directories in which they are contained as the other archivers do. Extraction without path when using the GUI is perfomed with a trick which is not available when using the -e switch from the command line.

### Why does &app; sometimes report errors but the Error messages window is empty?

Please remember, that &app; is only a front end. It correctly reads any output from STDOUT or STDERR. Most probably the archiver didn't write anything to those channels even though it exists with an error code.

### Why &app; doesn't allow me to choose the archive self-extracting path as it happens with zip and 7z?

Because rar and arj executable do not allow to do so. Zip and 7z convertion to self-extracting is made by appending an sfx module to the archive so it's possible to choose a different path.