<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&ark;">
  <!ENTITY package "kdeutils">
  <!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>lauri@kde.org</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>2002-02-04</date>
<releaseinfo>2.10.90</releaseinfo>

<abstract>
<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
&konqueror;. Archive files should be associated with &ark;, so you can
also <mousebutton>right</mousebutton> click a file in &konqueror; and
select <guimenuitem>Ark</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
Directory...</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="configuration">
<title>Configuring &ark;</title>


<variablelist>

<varlistentry>
<term><guilabel>Directories</guilabel></term>
<listitem>
<para>This shows the <guilabel>Directories</guilabel> dialog box, so you
can <action>choose the default directories</action>. The <guilabel>Last
start-up directory</guilabel> is the last directory you used for that
particular option. </para> 
</listitem>
</varlistentry>

</variablelist>


</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>File</guimenu>
<guimenuitem>New</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>File</guimenu>
<guimenuitem>Open</guimenuitem> </menuchoice></term>
<listitem>
<para><action>Opens an archive</action></para>
</listitem>
</varlistentry>
        
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guisubmenu>Open Recent</guisubmenu>
</menuchoice></term>
<listitem>
<para><action>Shows a list of recent archives to choose
from</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save As</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>File</guimenu>
<guimenuitem>New Window</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Opens a new &ark; window</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Reload</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>File</guimenu>
<guimenuitem>Close Archive</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Closes the current archive</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>Q</keycap></keycombo></shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</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>Edit</guimenu>
<guimenuitem>Select...</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>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>A</keycap></keycombo></shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Select All</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Selects all the files in the archive</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Deselect All</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Unselects all the files in the archive</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Invert 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>Edit</guimenu>
<guimenuitem>View 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>Action</guimenu>
<guimenuitem>Add File...</guimenuitem>
</menuchoice></term>
<listitem>
<para>Shows the <guilabel>Select Files to Add</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>Action</guimenu>
<guimenuitem>Add Directory...</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>Action</guimenu>
<guimenuitem>Delete</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Removes the currently selected files from the
archive.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Action</guimenu>
<guimenuitem>Extract</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>Action</guimenu>
<guimenuitem>View</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Opens the currently selected file in the associated viewer
program.</action></para>
</listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Action</guimenu>
<guimenuitem>Open 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>Action</guimenu>
<guimenuitem>Edit With...</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>Settings</guimenu>
<guimenuitem>Show Toolbar</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Toggles whether the toolbar is displayed. </action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show Statusbar</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Toggles whether the statusbar is
displayed. </action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Save 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>Settings</guimenu>
<guimenuitem>Configure Shortcuts...</guimenuitem>
</menuchoice></term>
<listitem>
<para>Displays the <guilabel>Configure Shortcuts</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 <interface>Key</interface> button lets you choose which specific
key to use. Just press the new key. </para>
</listitem> 
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Toolbars...</guimenuitem>
</menuchoice></term>
<listitem>
<para>Displays a &kde; standard dialog where you can configure the
toolbar icons.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Ark...</guimenuitem>
</menuchoice></term>
<listitem>
<para>
This opens the &ark; configuration dialog.  The dialog contains three
tabs.  Configuring &ark; is covered in the section <link
linkend="configuration">Configuration</link></para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="help-menu">
<title>The <guimenu>Help</guimenu> Menu</title>

&help.menu.documentation;

</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>

&install.intro.documentation;

</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>

&install.compile.documentation;

</sect1>

</appendix>

&documentation.index; 
</book>

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

