<!DOCTYPE book PUBLIC  "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
  <!ENTITY appname "&ark;" -- this only *seems* redundant -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
  <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
  %ents;
]>

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

</authorgroup>

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

<legalnotice>&FDLNotice;</legalnotice>

<date>14/12/2000</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 tar, gzip, bzip2, zip and
lha (if appropriate command-line programs are installed). &ark; works closely
with <application>Konqueror</application> in the KDE environment to handle
archives.</para>

<sect1 id="ark-revhistory">
<title>&ark; Documentation Revision History</title>

<itemizedlist>
<listitem><para>0.05.00 - Original &ark; documentation - Robert
Palmbos</para></listitem>
<listitem><para>0.05.00 - Documentation for KDE2 - Matt
Johnston</para></listitem>
</itemizedlist>

</sect1>
</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 right-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, <abbrev>ie</abbrev>
<filename>*.txt</filename> or <filename>*.jpg</filename>.  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 "Advanced" 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
(<filename>tar.gz</filename>, <filename>zip</filename>, <filename>bz2</filename>
<abbrev>etc</abbrev>). 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
<application>Konqueror</application> 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 File Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><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><keycap>Ctrl</keycap><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 Edit 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 <filename>*.txt</filename> 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 Action 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 <keycap>Ctrl</keycap> 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, <abbrev>i.e.</abbrev>
<filename>*.txt</filename> or <filename>*.jpg</filename>   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>
<para>Authors:</para>
<itemizedlist>
<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. <abbrev>GNU</abbrev>
<application>Tar</application> v1.12 and a recent
<application>gzip</application> are also needed to use &ark;. To handle other
file formats, you need the appropriate command line programs, such as
<application>zip</application>, <application>unzip</application>,
<application>ar</application> and <application>lha</application>.
</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>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>

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

</sect1>

</appendix>



<![ %addindex; [ &kdedocindex; ]]>
</book>
<!--
Local Variables:
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
End:
-->
