<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&ark;">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">

<bookinfo>
<title>The &ark; Handbook</title>

<authorgroup>
<author>
<firstname>Matt</firstname>
<surname>Johnston</surname>
<affiliation>
<address><email>mattj@flashmail.com</email></address>
</affiliation>
</author>

<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation><address><email>vampyr@atconnex.net</email></address></affiliation>
<contrib>Reviewer</contrib>
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2000</year>
<holder>Matt Johnston</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2000-12-14</date>
<releaseinfo>1.90.00</releaseinfo>

<abstract><para>This Handbook describes &ark; Version 1.9 </para> 
<para>&ark; is an archive manager for &kde;.</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>gzip</keyword>
<keyword>gunzip</keyword>
<keyword>tar</keyword>
<keyword>archive</keyword>
<keyword>zip</keyword>
<keyword>compression</keyword>
<keyword>lha</keyword>
<keyword>kdeutils</keyword>
<keyword>ark</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&ark; is a program for managing various archive formats within the
&kde; environment. Archives can be viewed, extracted, created and
modified from within &ark;. The program can handle various formats such
as <command>tar</command>, <command>gzip</command>,
<command>bzip2</command>, <command>zip</command> and
<command>lha</command> (if appropriate command-line programs are
installed). &ark; works closely with &konqueror; in the &kde;
environment to handle archives.</para>

</chapter>

<chapter id="using-ark">
<title>Using ark</title>

<sect1 id="ark-open">
<title>Opening Archives</title>

<para>To open an archive in &ark;, choose
<guimenuitem>Open</guimenuitem> from the <guimenu>File</guimenu>
menu. You can also open archive files by dragging and dropping from
<application>Konqueror</application>. Archive files should be associated
with &ark;, so you can also <mousebutton>right</mousebutton> click a
file in <application>Konqueror</application> and select
<guimenuitem>Archiver</guimenuitem> to open it.</para>

</sect1>

<sect1 id="ark-work-files">
<title>Working with Files</title>

<para>Once an archive has been opened, you can perform various
operations on the files inside the archive.  By
<mousebutton>right</mousebutton> clicking on a file within the archive,
or selecting a file and using the <guimenu>Action</guimenu> menu, you
can choose what you want to do:</para>

<itemizedlist>
<listitem>
<para><guimenuitem>View</guimenuitem> will open the file in the default
viewer program.</para>
</listitem>
<listitem>
<para><guimenuitem>Open With...</guimenuitem> allows you to open the
file in a program you choose.</para>
</listitem>
<listitem>
<para><guimenuitem>Edit With...</guimenuitem> will open the file a
program you choose. The difference between this and <guimenuitem>Open
With...</guimenuitem> is that any changes you make will be saved to the
file in the archive.</para>
</listitem>
<listitem>
<para><guimenuitem>Delete</guimenuitem> will remove the currently
selected file(s) from the archive.</para>
</listitem> 
</itemizedlist>

</sect1>

<sect1 id="ark-extract">
<title>Extracting Archives</title>

<para>Once an archive has been opened in &ark;, it can be extracted. To
extract files from an archive, you can either select
<guimenuitem>Extract...</guimenuitem> from the <guimenu>Action</guimenu>
or by <mousebutton>right</mousebutton> clicking on any file. The Extract
dialog allows you to select where you will extract files to. You can
also select which files to extract:</para>

<itemizedlist>
<listitem>
<para><guimenuitem>Current</guimenuitem> extracts the most recently
selected file. If multiple files are selected, only the most recently
selected one will be extracted.</para>
</listitem>
<listitem>
<para><guimenuitem>All</guimenuitem> extracts the entire contents of the
archive.</para>
</listitem> 
<listitem>
<para><guimenuitem>Selected Files</guimenuitem> extracts all the files
which have been selected.</para>
</listitem>
<listitem>
<para><guimenuitem>Pattern</guimenuitem> allows you to specify which
files will be extracted, corresponding to certain patterns, &eg;
<literal role="extension">*.txt</literal> or <literal
role="extension">*.jpg</literal>.  Note that you can only use one
pattern at a time.</para> 
</listitem>
</itemizedlist>

<para>You can specify the directory to extract files to in the
<guilabel>Extract to:</guilabel> textbox. If you want to change the
default directory, in the main program window, choose
<guimenuitem>Directories...</guimenuitem> on the
<guimenu>Settings</guimenu> menu. Under the
<guilabel>Advanced</guilabel> tab, you can choose some specific options
depending on the archive format.</para>

</sect1>

<sect1 id="ark-create">
<title>Creating Archives and Adding Files</title>

<para>To create a new archive in &ark;, choose
<guimenuitem>New</guimenuitem> from the <guimenu>File</guimenu>
menu.</para>

<para>You can then type the name of the archive, with the appropriate
extension (<literal role="extension">tar.gz</literal>, <literal
role="extension">zip</literal>, <literal role="extension">bz2</literal>
&etc;). To add files to the archive, choose <guimenuitem>Add
File...</guimenuitem> from the <guimenu>Action</guimenu> menu. If you
want to add an entire directory to an archive, choose <guimenuitem>Add
Dir...</guimenuitem> from the <guimenu>Action</guimenu> menu.</para>

<para>An alternative way to add files to the archive is to drag a file
from &konqueror; or the desktop into the main &ark; window, and it will
be added to the current archive.</para>

</sect1>

</chapter>

<chapter id="commands">
<title>Command Reference</title>

<sect1 id="filemenu">
<title>The <guimenu>File</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice> <shortcut> <keycombo
action="simul">&Ctrl;<keycap>n</keycap></keycombo> </shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>N</accel>ew</guimenuitem> </menuchoice></term>
<listitem>
<para><action>Creates a new archive</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice> <shortcut> <keycombo
action="simul">&Ctrl;<keycap>o</keycap></keycombo> </shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>O</accel>pen</guimenuitem> </menuchoice></term>
<listitem>
<para><action>Opens an archive</action></para>
</listitem>
</varlistentry>
        
<varlistentry>
<term><menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guisubmenu>Open <accel>R</accel>ecent</guisubmenu>
</menuchoice></term>
<listitem>
<para><action>Shows a list of recent archives to choose
from</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Save <accel>A</accel>s</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Allows you to save the current archive under a new file
name</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>New <accel>W</accel>indow</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Opens a new &ark; window</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Re<accel>l</accel>oad</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Loads the current archive again from disk. This will
refresh &ark;'s view if another program has made changes to the
archive.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>C</accel>lose Archive</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Closes the current archive</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>Q</accel>uit</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Closes &ark;</action></para>
</listitem>
</varlistentry>
</variablelist>

</sect1>
<sect1 id="editmenu">
<title>The <guimenu>Edit</guimenu> Menu</title>

<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem><accel>S</accel>elect...</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Lets you select files according to their
filename</action>. For example, you could use <literal
role="extension">*.txt</literal> to select all txt files. Note that you
can't use more than one filter at a time.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Select <accel>A</accel>ll</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Selects all the files in the archive</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem><accel>D</accel>eselect All</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Unselects all the files in the archive</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem><accel>I</accel>nvert Selection</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Reverses which files are selected. Selected files become
unselected, and unselected files are selected.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem><accel>V</accel>iew shell output</guimenuitem>
</menuchoice></term>
<listitem>
<para>Displays the <guilabel>Shell Output</guilabel> box, which
<action>shows you the output of the most recent command(s)</action> run
by &ark;. This is sometimes useful if you are having problems and want
to troubleshoot.</para>
</listitem> 
</varlistentry>

</variablelist>

</sect1>

<sect1 id="actionmenu">
<title>The <guimenu>Action</guimenu> Menu</title>

<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu><accel>A</accel>ction</guimenu>
<guimenuitem><accel>A</accel>dd File...</guimenuitem>
</menuchoice></term>
<listitem>
<para>Shows the <guilabel>Add Files</guilabel> dialog box, where you can
select files. Hold down &Ctrl; and click to select multiple files.  To
go up a directory, <mousebutton>right</mousebutton> click the directory
box, and you can choose <guimenuitem>Up</guimenuitem> (this will
probably be improved soon). The <guilabel>Advanced</guilabel> tab has
options which are specific to the type or archive you are working
with.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>A</accel>ction</guimenu>
<guimenuitem>Add Di<accel>r</accel>...</guimenuitem>
</menuchoice></term>
<listitem>
<para>Shows the <guilabel>Add Directory</guilabel> dialog box, where you
can choose a <action>directory to add</action>. Just choose a directory
and choose <guibutton>Open</guibutton>.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>A</accel>ction</guimenu>
<guimenuitem><accel>D</accel>elete</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Removes the currently selected files from the
archive.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>A</accel>ction</guimenu>
<guimenuitem><accel>E</accel>xtract</guimenuitem>
</menuchoice></term>
<listitem>
<para>Shows the <guilabel>Extract</guilabel> dialog box, which allows
you to <action>select where you will extract files</action> to. You can
also select which files to extract:</para>

<itemizedlist>
<listitem>
<para><guilabel>Current</guilabel> extracts the most recently selected
file. If multiple files are selected, only the most recently selected
one will be extracted.</para>
</listitem> 
<listitem>
<para><guilabel>All</guilabel> extracts the entire contents of the
archive.</para>
</listitem>
<listitem>
<para><guilabel>Selected Files</guilabel> extracts all the files which
have been selected.</para>
</listitem> 
<listitem>
<para><guilabel>Pattern</guilabel> allows you to specify which files
will be extracted, corresponding to certain patterns, &eg;
<literal role="extension">*.txt</literal> or <literal
role="extension">*.jpg</literal>   Note that you can only use one
pattern at a time.</para>
</listitem>
</itemizedlist>

<para>You can specify the directory to extract files to in the
<guilabel>Extract to:</guilabel> textbox. If you want to change the
default directory, in the main program window, choose
<guimenuitem>Directories...</guimenuitem> on the
<guimenu>Settings</guimenu> menu. Under the
<guilabel>Advanced</guilabel> tab, you can choose some specific options
depending on the archive format.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>A</accel>ction</guimenu>
<guimenuitem><accel>V</accel>iew</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Opens the currently selected file in the associated viewer
program.</action></para>
</listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>A</accel>ction</guimenu>
<guimenuitem><accel>O</accel>pen with...</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Opens the currently selected file in a program you
choose.</action> The <guilabel>Open With...</guilabel> dialog box lets
you choose which program to use. </para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>A</accel>ction</guimenu>
<guimenuitem>Edit <accel>w</accel>ith..</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Opens the currently selected file in a program you
choose.</action> Any changes you make in the editor program will be
reflected in the archive, as it will be updated. </para>
</listitem> 
</varlistentry>

</variablelist>

</sect1>

<sect1 id="settingsmenu">
<title>The <guimenu>Settings</guimenu> Menu</title>

<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Show <accel>T</accel>oolbar</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Toggles whether the toolbar is displayed. </action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Show St<accel>a</accel>tusbar</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Toggles whether the statusbar is
displayed. </action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem><accel>S</accel>ave Settings</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Saves the current configuration options to
disk</action>. This means that they will be remembered next time you
use &ark;.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Configure <accel>K</accel>ey Bindings...</guimenuitem>
</menuchoice></term>
<listitem>
<para>Displays the <guilabel>Key Bindings</guilabel> dialog
box. This <action>lets you choose shortcut keys for various menu
items.</action> To change a shortcut, select an action from the list,
and then choose which keystroke to use. Clicking on the bottom right
hand <guibutton>key</guibutton> button lets you choose which specific
key to use. Just press the new key. </para>
</listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem><accel>D</accel>irectories...</guimenuitem>
</menuchoice></term>
<listitem>
<para>This shows the <guilabel>Directories</guilabel> dialog box, so you
can <action>choose the default directories</action>. The <guilabel>last
startup directory</guilabel> is the last directory you used for that
particular option. </para> 
</listitem>
</varlistentry>

</variablelist>

</sect1>

</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>&ark; is Copyright 1997-2000, Various &ark; Developers</para>

<itemizedlist>
<title>Authors:</title>
<listitem><para>Robert Palmbos
<email>palm9744@kettering.edu</email></para></listitem>
<listitem><para>Francois-Xavier Duranceau
<email>duranceau@kde.org</email></para></listitem>
<listitem><para>Corel Corporation (author: Emily Ezust)
<email>emilye@corel.com</email></para></listitem>
</itemizedlist>

<para>Documentation copyright 2000 Matt Johnston
<email>mattj@flashmail.com</email></para>

&underFDL;
&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-ark">
<title>How to obtain &ark;</title>

<para>&ark; is part of the &kde; project <ulink
url="http://www.kde.org">http://www.kde.org</ulink>.  &ark; can be found
in the kdeutils package on <ulink
url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the
main &FTP; site of the &kde; project. </para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>In order to successfully use &ark;, you need &kde;
2.0. <acronym>GNU</acronym> <command>Tar</command> v1.12 and a recent
<command>gzip</command> are also needed to use &ark;. To handle other
file formats, you need the appropriate command line programs, such as
<command>zip</command>, <command>unzip</command>, <command>ar</command>
and <command>lha</command>.  </para>

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<para>In order to compile and install &ark; on your system, type the
following in the base directory of the kdeutils distribution:</para>

<screen width="40"><prompt>%</prompt> <userinput><command>./configure</command></userinput>
<prompt>%</prompt> <userinput><command>make</command></userinput>
<prompt>%</prompt> <userinput><command>make</command> <option>install</option></userinput>
</screen>

<para>Since &ark; uses <command>autoconf</command> and
<command>automake</command> you should have not trouble compiling it.
Should you run into problems please report them to the &kde; mailing
lists.</para>

</sect1>

</appendix>

&documentation.index; 
</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
End:
-->

