XARCHIVE(1)
===========
Lee Bigelow <ligelowbee@yahoo.com>
v0.2.8-6, 27 February 2006 

NAME
----
XArchive - a gtk2.0 front-end for various command line archivers.

SYNOPSIS
--------
*xarchive* [-a 'archive' | -c 'archive'] [files...]

DESCRIPTION
-----------
XArchive is graphical front-end that uses external wrappers to communicate
with the command line archiving tools.  XArchive handles creation, extraction
and manipulation of archives depending on whether or not the command line tools
(and the wrappers written for them) support those actions.  The types of
archives supported depends on what wrappers are available in XArchive's wrapper
directories (see WRAPPERS below), and what command line tools are installed.

Currently there are bash shell wrappers for: 

*tar*:: 
    using tar, bzip2, gzip, and compress

*rar*:: 
    using rar, or unrar(unrar only cannot modify rar's)

*zip*:: 
    using unzip, zipinfo(from unzip), and zip

*ace*:: 
    using unace (extraction only)

*7zip*::
    using 7za from p7zip

*arj*::
    using arj

*rpm*::
    using rpm and cpio (extract only, use appropriate packing tools to modify)

*deb*::
    using dpkg-deb from dpkg (extract only, use appropriate tools to modify)

OPTIONS
-------
*-a* 'archive'::
    Add passed 'files' to 'archive'.  
    * Normally the passed 'archive' file is opened, and a multi-file selector
      is presented with any passed 'files' already added to the
      selection list.
    * However, if the 'archive' filename passed is 'ask', or the
      passed 'archive' file cannot be found, then a dialog will be presented
      asking whether to create a new archive or use an existing
      one.  An appropriate chooser will then be presented for finding,
      or creating, an archive to add to.  Once an archive is found, or
      created, a multi-file selector will be presented with any passed
      'files' already added to the selection list.

*-c* 'archive':: 
     Create a new archive file named 'archive' with passed
     'files'.  
     * A dialog will be presented asking for an archive name.  If the
       'archive' name passed is 'ask' then a generic sample filename
       will be shown.  Otherwise the passed 'archive' name with be
       shown.  On accepting the name is checked to make sure the file
       doesn't already exist, and that a wrapper for that type of
       'archive' is present.  Thus the 'archive' name should contain
       the extension of the archive type that is desired
       (eg. test.zip).  Once a valid archive name is accepted a
       multi-file selector is presented with any passed 'files' already
       added to the selection list.  
 
USAGE
-----
When XArchive starts it consults each wrapper it finds in it's wrapper
directories (see WRAPPERS below) to see what file types it can support.

If XArchive is started without being passed any files to open, or any
options, an information page is shown detailing what wrappers were
found and what file types are (based on file extensions) supported by
those wrappers

If some 'files' to open are passed to XArchive without any options it
will treat them as archives and attempt to use the wrappers associated
with those archives (based on file extensions) to get, and show, the
contents of each.

The '-a' and '-c' options allow you to use XArchive with your
file-manager to add to an existing archive, or to create a new one.

Using 'xarchive -a ask' as your file-manager's "open with" command on
some selected files will allow you add those selected files to an
existing archive (xarchive will ask which archive to add them too).

Using just 'xarchive -a' as your file-manager's "open with" command on a
selected archive file will allow you open that archive and use
XArchive's multi-file selector to choose the files to add to it.

Using 'xarchive -c ask' as your file-manager's "open with" command on
some selected files allows you to create a new archive containing
those files (XArchive will ask you for the new archive's name).  This
option won't allow opening an existing archive and guarantees that a
unique one is created.

Once and archive is opened it's entries can be selected to delete,
extract, or open-with.  You can use the following selection methods: 

*Left-Click*::
    To select one file, and unselect all others.  If that one file is
    a directory it's contents will also be selected.

*CTRL + Left-Click*:: 
    To select/unselect multiple files.  Hold down the Control Key while
    Left-Clicking individual files to toggle their selection state.
    If the file clicked is a directory it's contents will also be
    selected or unselected.  

*SHIFT + Left-Click*:: 
    To select a block of files.  Select the first file in the block normally
    (just a Left-Click), then Shift + Left Click the last file
    in the block and all the files in between will also be selected.

*Right-Click* on an archive listing will bring up a context
menu with the actions from the toolbar on it.

*Double-Left-Click* on an entry will temporarily extract
that file from the archive and use the default handler to view it.  If
no default handler has been set the "open with.." dialog is opened so
that you can set one.

Just select an item in the archive and start typing to use the
type-ahead search feature (or you can press Ctrl-f).

About "Drag and Drop"
~~~~~~~~~~~~~~~~~~~~~

Once an archive is opened you can drag files from your filemanager (if
it supports drag and drop) on to the archive list and have the
add-to-archive file chooser open.  It's list of files to add will
contain the items dropped.  From there you can select more files to
add from the file chooser, or drop files onto this list from your
filemanager.

About "Open With"
~~~~~~~~~~~~~~~~~

'Open with' will temporarily extract selected files and view them with
the user selected application.  From this dialog you can also set an
application as the 'default double-click handler' by clicking that
option's checkbox.  Setting this allows you to double left click
entries in the listing and have them viewed with the set application.

Note:  When picking an 'open with' application you should make sure
that application doesn't fork to the background.  If it does then the
temporary file that was extracted will most likely be deleted before
the application can view it.  For example, 'gvim' will fork to the
background, so instead you should use 'gvim --nofork'.

About Creating Archives
~~~~~~~~~~~~~~~~~~~~~~~

When you select 'New' you will be asked for an archive name.  The
extension you use on your name will determine what kind of archive is
created.  For example using 'mywebstuff.zip' will create a zip, and
'mywebsutff.tar.bz2' will create a bzip2 compressed tar.

Then, in the same dialog, you'll select the folder you want to save
the archive in.  When that's done, and you press 'open' the multiple
file selector will be opened.

The multiple file selector allows you to browse around the file system
and pick off what files and directories you wish to add to your
archive.  Just select the files in the 'file chooser' list and press
the 'add to list' button.  To remove files from the 'add to archive'
list, select the files and press the 'remove from list' button.

Note that the the full path for the file or directory will be listed
in the 'add to archive' list for your reference, but when the archive
is made only the basename of the entry will be added.  For example, if
the '/home/me/html' directory is on the list to be added then the
archive will contain the directory 'html' (and it's contents), not
it's full path (the '/home/me' part is discarded).  This is a good
thing.  When you send someone your archive, and they extract it, you
probably don't want it trying to create a /home/me/html directory tree
on your buddies machine.

KEYBOARD SHORTCUTS
------------------
Main Archive Listing
~~~~~~~~~~~~~~~~~~~~
CTRL + Q:: 
     quit

CTRL + O:: 
     open an existing archive

CTRL + N:: 
     create a new archive

CTRL + W:: 
     close the current archive window

CTRL + S:: 
     select all files in archive

CTRL + U:: 
     unselect all files in archive

CTRL + E:: 
     extract selected files from archive

CTRL + P::
     temporarily extract selected files and view them 
     with a user specified application.
     (has command history, saved in ~/.xarchive/cmd_history)

CTRL + R:: 
     remove selected files from archive

CTRL + A:: 
     add files to archive

CTRL + H::
     read the help file

CTRL + I::
     show wrapper information

File and Directory Chooser
~~~~~~~~~~~~~~~~~~~~~~~~~~

ALT + UP::
    move up to parent directory

ALT + DOWN::
    move down a directory

ALT + HOME::
    move to home directory

CTRL + L::
     ask for a specific location to move to

ALT + A::
    if on a directory in the 'File Chooser', add a shortcut for it to the 'Folder Shortcuts List'

ALT + R::
    if on a shortcut in the 'Folder Shortcuts List', remove it from the list

ALT + O::
    OK 

ALT + C::
    Cancel

(Note: To select hidden directories right click on the file listing and select
"show hidden files" from the popup menu)

"Add to Archive" Selector
~~~~~~~~~~~~~~~~~~~~~~~~~
The same as the File and Directory Chooser with the following added:

ALT + T::
    add selected files in the 'File Chooser' to the 'Add To Archive List' below it

ALT + F:: 
    remove selected files from the 'Add to Archive List' (can also be activated by a right-click on the list)

WRAPPERS
--------
XArchive checks the following directories, in the following order, for 
it's wrappers:

- ~/.xarchive/wrappers/

- /usr/local/lib/xarchive/wrappers/

- (or, depending on installation /usr/lib/xarchive/wrappers/)

The first wrappers found are the first ones used.  Thus, if you copy a wrapper
from the system wide directory (/usr/local/lib/xarchive/wrappers/) to your own
private wrapper directory (~/.xarchive/wrappers/) and modify it, your modified
version will be used.

The wrappers are stand alone executables whose job is to:

- When asked what files it supports, check to see if the command line tools it
  needs are installed and tell XArchive what types of files it supports based
  on what's installed.

- When asked for the contents of an archive, take the output from the command
  line tools it uses and mangle it into the format XArchive likes

- When sent an action to perform, take the requested action from
  XArchive and send the command line tool the appropriate options to perform
  said action.  

Wrappers can be any type of executable file (python scripts, c programs, bash
scripts, etc...) that handle the following options in the following manner:

-i::  
    'Info:' Check to see if command line programs are installed and return a
    line containing a semicolon separated list of supported file extensions
    based on what's installed.  eg: 
        * tar;tar.gz;tar.bz2;tar.z;tgz;tbz;tbz2

-o archive::
    'Open:' Use command line tools to get contents of "archive" and return
    contents in the format XArchive accepts.  Each entry in the archive on a
    separate line like so:
        * file1;size;attributes;user;group;date;time;linkinfo
        * file2;size;attributes;user;group;date;time;linkinfo
        * file3;size;attributes;user;group;date;time;linkinfo
        * (note: all fields must be present, so if there's no data for a field
           fill it with a "-", or a space if you like.)

-a archive files::
    'Add:' Add to "archive" the "files" sent.  File names sent are escaped to
    be bash friendly by XArchive.

-n archive file::
    'New:' create a new archive "archive" with single file "file".  (other files
    selected to be put in new archive will be "added" after creation.)

-r archive files::
    'Remove:' remove from "archive" sent "files"

-e archive files::
    'Extract:' extract from "archive" sent "files" into the current dir.
    XArchive changes into a user selected directory before sending this
    command.

Wrapper Exit Codes
~~~~~~~~~~~~~~~~~~
- 0  success

- 65 unsupported action for this archive type

- Anything else for wrapper failure

See the wrappers included in /usr/local/lib/xarchive/wrappers (or /usr/lib/xarchive/wrappers) for examples.

BUGS 
---- 
Use bug tracker on the sourceforge project page:

http://sourceforge.net/projects/xarchive/[]

AUTHOR
------
Written by Lee Bigelow <ligelowbee@yahoo.com> 

RESOURCES
---------
SourceForge: 

http://sourceforge.net/projects/xarchive/[]

Main web site: 

http://xarchive.sourceforge.net[]

COPYING
-------
Copyright (C) 2005 Lee Bigelow <ligelowbee@yahoo.com>. Free use of this software is
granted under the terms of the GNU General Public License (GPL).

