<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY app "Xarchiver">
<!ENTITY app_small "xarchiver">
<!ENTITY appversion "0.5">
<!ENTITY appurl "http://xarchiver.xfce.org">
<!ENTITY author_mail "colossus73@gmail.com">
<!ENTITY date "September 29, 2006">
]>

<book lang="en">
	<bookinfo>
		<author>
			<firstname>Giuseppe</firstname>
			<surname>Torelli</surname>
			<address><email>&author_mail;</email></address>
		</author>
		<copyright>
			<year>2006</year>
		</copyright>
		<legalnotice>
			<para>
				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.
			</para>
		</legalnotice>
		<title>
			&app; &appversion;
		</title>
	</bookinfo>

	<chapter id="intro">
		<title>
			Introduction
		</title>
		<section>
			<title>About Xarchiver</title>
			<para>
				<application>&app;</application> 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 <application>&app;</application> requires only the GTK+2 toolkit
				to work.
			</para>
			<para>
				<application>&app;</application> has these features:
				<itemizedlist>
					<listitem><para>The most used archiver cmd-line options are supported in the Add and Extract dialog</para></listitem>
					<listitem><para>Archives are detected by their magic header and not by the extension except for .tar.bz2 and .tar.gz</para></listitem>
					<listitem><para>Drag and drop from and to Xarchiver window is supported with XDS protocol</para></listitem>
					<listitem><para>ZIP and ARJ archive comment are supported. RAR comment is not yet supported because it's compressed inside the archive itself</para></listitem>
					<listitem><para>Tabs Firefox style support</para></listitem>
					<listitem><para>Ability to convert the archive to self-extracting for those archive types which support it</para></listitem>
					<listitem><para>Smart detection of arj, zip and rar password encrypted archives</para></listitem>
					<listitem><para>All the the output of the cmd-line archiver is displayed in the Xarchiver window</para></listitem>
					<listitem><para>All common formats are supported: arj, bzip2, lha, gzip, 7z, rar, tar, tar.bz2, tar.gz, zip, DEB and RPM (only open,view and extract)</para></listitem>
					<listitem><para>Support of RPM files without RPM executable. This is useful on not RPM-based distributions like Slackware and Arch Linux</para></listitem>
					<listitem><para>Zip, rar, arj and 7z password encrypted archives are fully supported (7z automatic password detection is not supported)</para></listitem>
				</itemizedlist>
			</para>
		</section>
		<section>
			<title>Where to get it</title>
			<para>
				You can obtain <application>&app;</application> from <ulink url="&appurl;">&appurl;</ulink>
				or perhaps from your distributor.
			</para>
		</section>
		<section>
			<title>License</title>
			<para>
				<application>&app;</application> 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.
			</para>
		</section>
	</chapter>

	<chapter id="installation">
		<title>
			Installation
		</title>
		<section>
			<title>Requirements</title>
			<para>
				For compiling <application>&app;</application> yourself, you will need the GTK (>= 2.6.0)
				libraries and header files. You will also need the Pango, Glib and ATK libraries and header files.
				All these files are available at <ulink url="http://www.gtk.org">http://www.gtk.org</ulink>.
			</para>
		</section>
		<section id="source_compilation">
			<title>Source compilation</title>
			<para>
				Compiling <application>&app;</application> is quite easy. The following should do it:
				<screen>
					<prompt>%</prompt> <userinput><command>./configure --prefix=/usr</command></userinput>
					<prompt>%</prompt> <userinput><command>make</command></userinput>
					<prompt>%</prompt> <userinput><command>make</command> install</userinput></screen>
			</para>
			<para>
				The configure script supports several common options, for a detailed list, type
				<screen>
					<prompt>%</prompt> <userinput><command>./configure</command> --help</userinput></screen>
			</para>
			<para>
				If there are any errors during compilation, check your build environment and try to find the error,
				otherwise contact the author at <email>&author_mail;</email>.
			</para>
		</section>
	</chapter>
	<chapter id="usage">
		<title>Usage</title>
		<section id="getting_started">
			<title>Getting started</title>
			<para>
				You can start <application>&app;</application> in the following ways:
				<itemizedlist>
						<listitem>
						<para>
							From the Desktop Environment menu
						</para>
						<para>
							Choose in your application menu of your used Desktop Environment:
							<menuchoice>
							<guisubmenu>Accessories</guisubmenu>
							<guimenuitem>&app;</guimenuitem>
							</menuchoice>.
						</para>
					</listitem>
					<listitem>
						<para>
							From the command line
						</para>
						<para>
							To start <application>&app;</application> from a command line, type the following
							and press <keycap>Return</keycap>:
							<screen>
								<userinput><command>&app_small;</command></userinput>
							</screen>
						</para>
					</listitem>
				</itemizedlist>
			</para>
		</section>
		<section id="clo">
			<title>Command line options</title>
			<para>
				<table frame="all">
					<title>Command line Options</title>
					<tgroup cols="3">
						<?dbhtml cellpadding="4" ?>
						<?dbhtml cellspacing="0" ?>
						<colspec colnum="1" colname="col1"/>
						<colspec colnum="2" colname="col2"/>
						<colspec colnum="3" colname="col3"/>
						<thead>
							<row>
								<entry>Short option</entry>
								<entry>Long option</entry>
								<entry>Function</entry>
							</row>
						</thead>
						<tbody>
							<row>
								<entry>-x destination_path archive</entry>
								<entry>--extract-to=destination_path archive</entry>
								<entry>Extract archive to the directory specified by destination_path and quits.
								</entry>
							</row>
							<row>
								<entry>-e archive</entry>
								<entry>--extract=archive</entry>
								<entry>Extract archive by asking the destination directory and quits.
								</entry>
							</row>
							<row>
								<entry>-d file1 file2 file3 ... fileN</entry>
								<entry>--add-to=file1 file2 file3 ... fileN</entry>
								<entry>Add the given files by asking the name of the archive and quits. If archive doesn't exist it is created. The filenames must be separated by spaces.
								</entry>
							</row>
							<row>
								<entry>-a archive</entry>
								<entry>--add=archive</entry>
								<entry>Add files to archive by asking their filenames and quits.
								</entry>
							</row>
							<row>
								<entry>-?</entry>
								<entry>--help</entry>
								<entry>Show help information and quits.</entry>
							</row>
						</tbody>
					</tgroup>
				</table>
				&app; supports all generic GTK options, a list is available on the help screen.
			</para>
		</section>
		<section id="general">
			<title>General</title>
			<section id="general_startup">
				<title>Startup</title>
				<para>
					At startup, &app; detects the available installed archivers (tar,rar,zip etc). Since Xarchiver is a frontend (a graphic user interface to the cmd-line executables) it can't create archives whose archiver is not available. For instance if you have the free edition of rar, unrar, Xarchiver can't create rar archives since unrar allows rar archives to be opened, tested and extracted but not to be created.
				</para>
			</section>
			<section id="how_it_works">
				<title>How it works</title>
				<para>
					Xarchiver will run in the background the cmd-line executable of the archiver with the archiver's proper switches to perform the selected operation. If something goes wrong Xarchiver reports the full output of the archiver executable in the command line output window.
				</para>
			</section>
			<section id="dnd">
				<title>Drag and Drop</title>
				<para>
					Xarchiver supports drag and drop through the <ulink url="http://freedesktop.org/wiki/Standards_2fdirect_2dsave">
				<citetitle>XDS protocol</citetitle></ulink>. Currently only <ulink url="http://thunar.xfce.org/index.html">
				<citetitle>Thunar</citetitle></ulink> file manager supports it. Files and directories can dragged from Thunar window to Xarchiver and vice versa. If its window is empty (no archives open) Xarchiver will prompt the user with the <xref linkend="new_dialog"/> 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 Xarchiver will open it instead of prompting the new dialog.
				</para>
			</section>
		</section>
		<section id="menu">
			<title>Xarchiver menu</title>
			<section id="file_menu">
				<title>File menu</title>
				<section id="new">
					<title>New</title>
						<para>
							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.
						</para>
						<para>
							<figure id="new_dialog">
								<title>New dialog</title>
									<graphic fileref="images/new_dialog.png"></graphic>
							</figure>
						</para>
				</section>
				<section id="open">
					<title>Open</title>
						<para>
							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 archives are supported also. The password detection is done by looking for the password flag inside the archive structure except for rar ones since encrypted files in rar archives have an asterisk right before their filename. 7zip encrypted archives are not detected due to the complexity of 7zip format. Please see <ulink url="http://sourceforge.net/forum/forum.php?thread_id=1378003&amp;forum_id=383044">
				<citetitle>this thread on sf.net</citetitle>
				</ulink>for more information.
						</para>
				</section>
				<section id="test">
					<title>Test</title>
						<para>
							Tests the current archive. This option is disabled when
							the current archive was produced by an archiver which doesn't support testing.
						</para>
				</section>
				<section id="properties">
					<title>Properties</title>
						<para>
							Shows an archive dialog with useful info about the archive.
						</para>
						<para>
							<figure>
								<title>Archive properties dialog</title>
									<graphic fileref="images/archive_properties.png"></graphic>
							</figure>
						</para>
				</section>
				<section id="close">
					<title>Close</title>
						<para>
							Close the current archive and frees all the memory in use by it.
						</para>
				</section>
				<section id="quit">
					<title>Quit</title>
						<para>
							Frees all the memory in use and quit &app;.
						</para>
				</section>
			</section>
			<section id="action_menu">
				<title>Action menu</title>
				<section id="add">
					<title>Add</title>
						<para>
							Shows the add dialog featuring the most used archiver cmd-line options. The password entry is disabled when the archive doesn't support encryption. Files and directories can be also added by dragging and dropping them from any file managers.
						</para>
						<para>
							<figure>
								<title>Add dialog</title>
									<graphic fileref="images/add_dialog.png"></graphic>
							</figure>
						</para>
				</section>
				<section id="extract">
					<title>Extract</title>
						<para>
							Shows the extract dialog featuring the most used archiver cmd-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.
						</para>
						<para>
							<figure>
								<title>Extract dialog</title>
									<graphic fileref="images/extract_dialog.png"></graphic>
							</figure>
						</para>
				</section>
				<section id="delete">
					<title>Delete</title>
						<para>
							Delete the selected files from the archive. A warning dialog will be shown.
						</para>
				</section>
				<section id="view">
					<title>View</title>
						<para>
							Opens a window containing the ASCII dump of the selected ASCII file. If a file in the archive is encoded with a different enconding than in use by the system you will get an error message. See the <xref linkend="sixth"/> for a possible solution.
						</para>
				</section>
				<section id="sfx">
					<title>Make SFX</title>
						<para>
							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.

						</para>
				</section>
				<section id="comment">
					<title>Show Comment</title>
						<para>
							If the current archive contains a comment this menu entry opens a window showing it.
						</para>
				</section>
				<section id="select">
					<title>Select all</title>
						<para>
							Select all the files in the window.
						</para>
				</section>
				<section id="deselect">
					<title>Deselect all</title>
						<para>
							Deselect all the files in the window.
						</para>
				</section>
				<section id="output_window">
					<title>Command line output</title>
						<para>
							Opens a window containing the last archiver output.
						</para>
				</section>
				<section id="reset_password">
						<title>Reset password</title>
							<para>
							Clears the current password. The result of the operation is shown in the status bar. This option is useful when extracting files using Drag and Drop, allowing the user to choose another password if he entered it incorrectly.
							</para>
				</section>
				<section id="prefs">
						<title>Preferences</title>
							<para>
							Open the preferences dialog where you can set several options. All the options are automatically saved to ~/.config/xarchiver/xarchiverrc when pressing the Ok button.
							</para>
							<para>
							<figure id="pref_dialog">
								<title>Preferences dialog</title>
									<graphic fileref="images/pref_dialog.png"></graphic>
							</figure>
						</para>
				</section>
			</section>
			<section id="help_menu">
				<title>Help Menu</title>
					<section id="help">
						<title>Help</title>
							<para>
								Show this documentation in system installed browser.
								Currently firefox, opera and mozilla are supported.
							</para>
					</section>
					<section id="about">
						<title>About</title>
							<para>Shows the credit dialog with the contributors to &app;</para>
					</section>
			</section>
		</section>
	</chapter> <!-- It closes the opening one at line 117 -->
	<chapter id="faq">
		<title>FAQ</title>
		<section id="first">
			<title>Why are ace archives not supported?</title>
			<para>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 Xarchiver.
			</para>
		</section>
		<section id="second">
			<title>How can I create an archive with some files password protected and others not?</title>
			<para>First of all choose 'New' and select one of arj, 7zip, 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.
			</para>
		</section>
		<section id="third">
			<title>Why does Xarchiver emit this error message when handling tar archives?</title>
			<para>Xarchiver is only a frontend 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.
			</para>
		</section>
		<section id="fourth">
			<title>Why is the option "Extract with full path" disabled when using the -e switch with tar archives?</title>
			<para>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.
			</para>
		</section>
		<section id="fifth">
			<title>Why does Xarchiver sometimes report errors but the Error messages window is empty?</title>
			<para>Please remember, that Xarchiver is only a frontend. 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.
			</para>
		</section>
		<section id="sixth">
			<title>What is the meaning of this error message?</title>
			<para>
				<screen><userinput><command>Invalid byte sequence in conversion input</command></userinput></screen>
				The file you are trying to display is encoded with a different encoding than the locale one and the conversion to <ulink url="http://en.wikipedia.org/wiki/UTF8">
				<citetitle>UTF8</citetitle>
				</ulink>, the default encoding with GTK, fails.
				 I could set the encoding to <ulink url="http://en.wikipedia.org/wiki/ISO8859-1">
				<citetitle>ISO8859-1</citetitle>
				</ulink> because doing this fixes the problem, but it creates another one with german umlauts in ASCII files for example; they would be incorrectly showed. So if you get this error please extract the file and then see it with your favourite text editor.
			</para>
		</section>
		<section id="seventh">
			<title>Why Xarchiver doesn't allow me to choose the archive self-extracting path as it happens with zip and 7z?</title>
			<para>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.
			</para>
		</section>
	</chapter>
</book>
