r948: Added a new root window property (_ROX_FILER_EUID_HOST) which points to

[rox-filer.git] / ROX-Filer / src / Docs / Manual.xml

<?xml version="1.0" standalone="no"?>
<?xml-stylesheet href="to_html.xsl" type="text/xml"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                      "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd">

<book>
<bookinfo>
  <title>
    ROX-Filer User Manual
    <ulink url="http://rox.sourceforge.net"/>
  </title>
  <author>
    <firstname>Thomas</firstname><surname>Leonard</surname>
    <affiliation>
      <address><email>tal197@users.sourceforge.net</email></address>
    </affiliation>
  </author>
  <copyright><year>2001</year><holder>Thomas Leonard</holder></copyright>
  <legalnotice>
    <title>Conditions</title>
    <para>
This program is free software; you can redistribute it and/or modify
it 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.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA.
    </para>
  </legalnotice>

  <abstract>
    <para>
<application>ROX-Filer</application> is a graphical file manger for the X Window System. Its user
interface is based on the RISC OS filer and it supports similar features such
as application directories and drag-and-drop loading and saving of files. The
filer can also act as a pinboard, allowing you to pin frequently used files
onto the desktop background.
    </para>
  </abstract>
</bookinfo>

<chapter id="intro">
  <title>Introduction</title>
  <para>
<application>ROX-Filer</application> is a simple and easy to use graphical file manager for X11 &mdash; the
windowing system used on Unix and Unix-like operating systems.  It is also the
core component of the ROX Desktop <citation>ROX</citation>. Many of the filer's
features were inspired by RISC OS <citation>RISC OS</citation>. `ROX' stands for
`RISC OS&ndash;On&ndash;X'.
  </para>

<sect1>
  <title>Features</title>
    <para>

<variablelist>

<varlistentry><term>XDND</term>
<listitem><para>
A common drag-and-drop protocol used, for example, by the GNOME
desktop<citation>GNOME</citation>. This allows data to be loaded into an
application by dragging it from a filer window to a program. The full
specification is given in <citation>DND</citation>.
</para></listitem></varlistentry>

<varlistentry><term>XDS</term>
<listitem><para>
An extension to XDND that allows applications to save data by
dragging an icon back to a filer window. The full specification is given in
<citation>XDS</citation>.
</para></listitem></varlistentry>

<varlistentry><term>Choices</term>
<listitem><para>
A simple, but flexible, system for managing user choices.  See
<citation>Choices</citation> for details.
</para></listitem></varlistentry>

<varlistentry><term>Application directories</term>
<listitem><para>
Self contained relocatable applications, where installation is as simple as
copying it to where you want it and uninstalling it is just a matter of
deleting a directory. Described later in this documentation.
</para></listitem></varlistentry>

<varlistentry><term>Thumbnails</term>
<listitem><para>
The filer can be made to display image files by using the image itself for the
icon, instead of a generic `this-is-an-image' icon. Very useful for organising
a directory full of photos!
</para></listitem></varlistentry>

</variablelist>

  </para>
</sect1>

</chapter>

<chapter id="compiling">
  <title>Compiling</title>
  <para>

If you've just got hold of the filer by downloading the source archive
then you'll need to compile it before you can use it. If you downloaded
and installed a binary package, or if <application>ROX-Filer</application> was included with
your system, then you can skip this section. If you got here by clicking
on the `i' symbol in a filer window, or if typing <command>rox</command> at a
shell prompt works, then you don't need to compile.

  <itemizedlist><title>To compile, you will need the following:</title>

    <listitem><para>
Unix or Linux (root access is not required),
    </para></listitem>

    <listitem><para>
The X Window system (supplied as standard on all modern systems),
    </para></listitem>

    <listitem><para>
GTK+ 1.2.0 or later (libraries and headers) &mdash; get the latest version
from <citation>GTK+</citation>,
    </para></listitem>

    <listitem><para>
A C compiler, such as `gcc' (standard on most systems).
    </para></listitem>

  </itemizedlist>

All of the above are standard on most modern Linux distributions.
To check which version of GTK+ you have installed, run the
<command>gtk-config</command> command, like this 
(<prompt>$</prompt> is the shell prompt):

  <screen>$ gtk-config --version
1.2.8</screen>
Due to bugs in earlier versions, GTK+ 1.2.8 is strongly
recommended.
  </para>

  <procedure><title>To compile:</title>

    <step><para>
The filer needs some shared files to work &mdash; icons for the various
file types, rules for determining file types and default run actions.
These are installed by the `rox-base' package. Install rox-base (from
<ulink url="http://rox.sourceforge.net"/> now if you haven't done so already.
    </para></step>

    <step><para>
Change to the directory containing the ROX-Filer subdirectory.
    </para></step>

    <step><para>
Run the <command>install.sh</command> script, like this:

      <screen>$ ./install.sh</screen>

    </para></step>

    <step><para>
<application>ROX-Filer</application> will perform various checks to find out what kind of system
it is being run on and will then compile. If it doesn't work then
please e-mail me and complain! Tell me what kind of system you have
and what errors were reported. If you manage to fix the problem yourself
then please e-mail me the fix.

The executable file is stored inside the ROX-Filer directory in a
different subdirectory for each platform. Therefore, you can compile
the same application on several different types of machine and then
run it from any of them using the AppRun script. This is particularly
useful in a network environment.
    </para></step>

    <step><para>
Once the filer has compiled you will be asked where you want to install
it. If you want to do a system-wide installation as root, you may
want to stop here, <command>su</command> to root and rerun the install script.

If you don't have the root password then don't worry &mdash; just follow
the instructions for installing into your home directory. 
    </para></step>
  </procedure>

  <para>

You can now run the filer by running the <command>rox</command> script without
any options, like this:

  <screen>$ rox</screen>

A window should appear and display the contents of the current directory.

If you installed the script into your home directory then you may
need to set your <envar>PATH</envar> environment variable so that the shell can
find it. For example, if you installed it into a directory called
<filename>bin</filename> in your home directory, use this:

  <screen>$ PATH=$HOME/bin:$PATH; export PATH</screen>

or (if you are using the <citerefentry><refentrytitle>csh</refentrytitle>
<manvolnum>1</manvolnum></citerefentry> shell):

  <screen>$ setenv PATH $HOME/bin:$PATH
$ rehash</screen>

  </para>
</chapter>

<chapter id="invoking">
  <title>Invoking</title>
  <para>

By default, <application>ROX-Filer</application> will start by displaying the current directory.
You can get it to display other directories instead by listing them
after the command:

<screen>$ rox /home /usr /usr/local</screen>

You can also use it to open files, like this:

<screen>$ rox README</screen>

The filer supports various options; use <option>-h</option> for a list.
All options have long and short forms (eg <option>-h</option> and
<option>--help</option>) &mdash; although on some systems you can only use the
short versions.
</para><para>
Note that if the same version of the filer is already running on this
machine then, by default, it will be used to open the directories.
You can override this (perhaps because the old copy has stopped responding for
some reason) using the <option>--new</option> option.
</para><para>
For a complete list of command-line options, see <xref linkend="manpage"/>
  </para>

<sect1>
  <title><anchor id="run_pin" xreflabel="Pinboard support"/>Pinboard support</title>
  <para>

If you want the filer to manage your desktop background then you use
the <option>--pinboard</option> option and supply a name for the pinboard,
eg:

<screen>$ rox --pinboard=MyPinboard</screen>

The pinboard configuration is saved in
<filename>&lt;Choices&gt;/ROX-Filer/pb_MyPinboard</filename>
as soon as you change it in some way (for example, by dropping a file
onto the background). You can have as many pinboards as you like and
switch between them by running rox again, eg:

<screen>$ rox --pinboard=MyOtherPinboard</screen>

To turn off the pinboard again, set the name to an empty string:

<screen>$ rox --pinboard=</screen>

See the <xref linkend="winman"/> if you have trouble getting the icons to
display correctly. The pinboard may also be turned on and off by locating
<filename>ROX-Filer</filename> in a filer window and choosing `Enable pinboard' or `Disable pinboard' from the menu.

  </para>
</sect1>

<sect1>
  <title><anchor id="run_pan" xreflabel="Panel support"/>Panels</title>
  <para>

Panels work just like the pinboard. You can create a panel on any
side of the screen by using the options <option>--left</option>, <option>--right,</option>
<option>--top</option> and <option>--bottom</option>, depending on which side
of the screen the panel should appear on. On some systems, the short
(one letter) form of the options must be used. For example, to create
a panel along the bottom edge of the screen:

<screen>$ rox -b=MyPanel</screen>

The panel should be displayed in a window without a title bar. If
this does not work then see the <xref linkend="winman"/> for some ideas.
You can drag files onto either side of the panel to add them. Icons
can be repositioned by dragging them with the middle mouse button.
Changes to the panel are automatically saved to
<filename>&lt;Choices&gt;/ROX-Filer/pan_MyPanel</filename>.
As with the pinboard, you can switch between panel configurations
simply by running rox again with a different panel name. Specify a
blank name to remove the panel.

<screen>$ rox --bottom=MyOtherPanel
$ rox --bottom=</screen>

  </para>
</sect1>

<sect1>
  <title id="winman" xreflabel="window manager notes">Window manager notes</title>
  <para>

You may have to play around with your window manager a bit to get
the pinboard icons and panels to display correctly (eg, without borders
and underneath all other windows). In particular, try setting the
stacking level / depth to low (or a negative value). Make sure any
'Keep transients above other windows' type options are turned off!

In order for the filer to receive mouse clicks on the background (used
for the pinboard support) you need a GNOME-compliant window manager.
To see if your window manager supports this, try clicking the right
mouse button on an unused area of the background. If you get the pinboard
menu, all is well.
  </para>

<sect2><title>Sawfish / sawmill</title>
  <para>
Older versions of Sawfish tried to guess whether you were using GNOME at
start-up and only provided support if so. You may need to add the line
<programlisting>(require 'gnome)</programlisting>
to your <filename>.sawfishrc</filename> file (see the sawfish manual
for more details).
  </para>
</sect2>

<sect2><title>IceWM</title>
  <para>

Paste these configuration settings into
<filename>~/.icewm/preferences</filename>:

<programlisting>
# Manage root window (EXPERIMENTAL - normally enabled!)
GrabRootWindow=1 # 0/1
# Bitmask of root window button click to use in window manager
UseRootButtons=3 # [0-255]
# Desktop mouse-button click to show the menu
DesktopWinMenuButton=1 # [0-20]
# Desktop mouse-button click to show the window list
DesktopWinListButton=2 # [0-5]
# Desktop mouse-button click to show the window list menu
DesktopMenuButton=0 # [0-20] 
</programlisting>
Paste these into <filename>~/.icewm/winoptions</filename>:

<programlisting>
# ROX-Filer pinboard and panel
ROX-Filer.icon: folder
ROX-Panel.layer: Dock
ROX-Panel.doNotCover: 1
ROX-Panel.ignoreWinList: 1
ROX-Panel.ignoreTaskBar: 1
ROX-Panel.ignoreQuickSwitch: 1
ROX-Pinboard.layer: Below
ROX-Pinboard.ignoreWinList: 1
ROX-Pinboard.ignoreTaskBar: 1
ROX-Pinboard.ignoreQuickSwitch: 1
ROX-Filer.layer: Normal
</programlisting>
Restart IceWM and the filer for the new settings to take effect.

  </para>
</sect2>

<sect2><title>Others</title>
  <para>

If all else fails, try running rox with the <option>-n</option> and <option>-o</option>
options; this overrides window manager control of the icons altogether
(<option>-n</option> forces the filer to start a new copy).

  </para>
</sect2>
</sect1>

<sect1>
  <title>Running as root</title>
  <para>

If you run the filer as the `root' user then the filer will display
a message at the top of each window to remind you. The root user has
permission to access or change any file in the system, so be very
careful when using the filer like this.

Normally, you should log in as an ordinary user and only change to
root when you need to. You can create a simple script which runs the
filer as root &mdash; something like this:

<programlisting>
#!/bin/sh

su -m -c "rox $*"</programlisting>

Then, you can get a root filer window by simply running the script
and entering the root password. Remember, any file operations you
perform and any programs you run from these windows will run as root
too! Be careful!

You may find that the X server won't allow root (or other users) to
connect. Reading the manual pages for <command>xauth</command> and
<command>xhost</command> may give you some hints, but it varies
between systems (which is why this isn't built in to the filer!).

  </para>
</sect1>

</chapter>

<chapter id="keys">
  <title>Mouse button and key bindings</title>

<itemizedlist><title>Quick start:</title>

  <listitem><para>Click the left
  <footnote><para>This documentation assumes that button&ndash;1 is the left button, button&ndash;2
is the middle button and button&ndash;3 is the right button. This is not
always the case &mdash; for example, in a left-handed setup.</para></footnote>
mouse button to open files and directories.</para></listitem>

  <listitem><para>
Click the right button to get a menu. Click over a file to perform an action on that file.
  </para></listitem>

  <listitem><para>
Drag files between windows to copy (left button) or move (middle button) them.
  </para></listitem>

</itemizedlist>

  <para>
By default, the mouse button bindings are designed to fit in with X
conventions. However, the behaviour is highly configurable &mdash; have a play in
the Options window if you don't like the normal settings. The normal settings
behave as follows:
  </para>

<informaltable>
<tgroup cols="2">
<thead><row><entry>Key or mouse button</entry><entry>Action</entry></row></thead>

<tbody>

<row><entry>Left button click</entry><entry>
Open the file or directory clicked on. Hold down <keycap>Ctrl</keycap>
to select things instead of opening them. Hold down <keycap>Shift</keycap>
to look inside applications, treat files as text, follow symlinks or
mount devices.
</entry></row>

<row><entry>Middle button click</entry><entry>
Same as left click, but open a directory in a new window or close the viewer
when opening a file.
</entry></row>

<row><entry>Right button click</entry><entry>
Open the main menu. Hold down <keycap>Ctrl</keycap> while clicking to go
directly to the Selection submenu. Hold down <keycap>Shift</keycap> to get the
<guimenu>Send To</guimenu> menu. See the <xref linkend="SendTo"/> section.
</entry></row>

<row><entry>Drag an item  (left mouse button)</entry><entry>
Copy the file(s) to the destination (an application or another filer
window). Hold down <keycap>Shift</keycap> to move the file,
<keycap>Ctrl</keycap>+<keycap>Shift</keycap> to create
a symbolic link, or <keycap>Alt</keycap> to get a menu of possible actions.
</entry></row>

<row><entry>Drag an item (middle mouse button)</entry><entry>
When you let go, display a menu of possible actions.
There is an option to make this move the files rather than open the menu.
</entry></row>

<row><entry>Drag (not over an item)</entry><entry>
Select a group of items by dragging a box around them. With the left
mouse button, only the files in the box will be selected. If you hold
down <keycap>Ctrl</keycap> then the boxed items are added to the selection.
If you use the middle button then the boxed items switch between being selected
and unselected.
</entry></row>

<row><entry>Double-click background</entry><entry>
Resize the window to a sensible size.
</entry></row>

<row><entry><keycap>Backspace</keycap></entry><entry>
Change to viewing the parent directory.
</entry></row>

<row><entry>Cursor keys</entry><entry>
Move the cursor around.
</entry></row>

<row><entry>
<keycap>Page Up</keycap>, <keycap>Page Down</keycap></entry><entry>
Move the cursor up and down a page at a time.
</entry></row>

<row><entry><keycap>Home</keycap>, <keycap>End</keycap></entry><entry>
Move to the first/last entry in the directory.
</entry></row>

<row><entry><keycap>Return</keycap></entry><entry>
Acts like clicking on the file. You may hold down Shift for other
effects, as with clicking.
</entry></row>

<row><entry><keycap>Spacebar</keycap></entry><entry>
Toggles the item under the cursor between being selected and unselected,
and moves to the next item.
</entry></row>

<row><entry><keycap>Tab</keycap>, <keycap>Shift+Tab</keycap></entry><entry>
Moves the cursor to the next/previous selected item.
</entry></row>

</tbody></tgroup></informaltable>

  <para>
Other keys can easily be defined by opening the
menu, moving the pointer over the item you want to use and pressing
a key. The key will appear in the menu and can be used from then on.
Key bindings are automatically saved when the filer quits.

  </para>
</chapter>

<chapter id="selection">
  <title>The selection</title>
  <para>
When you select items in a <application>ROX-Filer</application> window,
the filer takes the <emphasis>primary selection</emphasis>. You can then paste
into another window to get the pathnames of the selected files.
  </para>

<procedure>
  <title>Example: loading a file into an application that doesn't support drag-and-drop:</title>

  <step><para>Open the application's Open dialog box.</para></step>

  <step><para>
<keycap>Ctrl</keycap>-click on the file in <application>ROX-Filer</application> to select it.
  </para></step>

  <step><para>
Click the middle button in the filename box in the application to
paste the name in.
  </para></step>
</procedure>

  <para>
Note that clicking the middle mouse button in the main area of most web-browsers
will open the selected file.
  </para><para>
If you select something else (eg, some text in another program), the selected
items in the filer window will be shown shaded (the filer no longer has the primary selection).
Changing the selection (eg, by dragging a box around an item with the middle
button) will cause the filer to regain the primary selection.
  </para>
</chapter>

<chapter id="toolbar">
  <title><anchor id="Toolbar" xreflabel="Toolbar"/>The toolbar</title>
  <para>

By default, each window has a toolbar along the top. You can disable
this (or make it larger) from the Options window, as well as set which
tools appear on the toolbar. Normally, you should click with the left
mouse button (1). However, many tools can perform a related function
if clicked on with buttons 2 or 3 (middle or right).
  </para>

<informaltable><tgroup cols="3">

<thead>
<row><entry> 
Icon</entry><entry>
Mouse button 1</entry><entry>
Other button
</entry></row>

</thead>
<tbody>

<row><entry>
Cross</entry><entry>
Close the window</entry><entry>
Open a new window
</entry></row><row><entry> 
Up arrow</entry><entry>
Change to parent directory</entry><entry>
Show parent in a new window <xref linkend="newwin_fn"/>
</entry></row><row><entry>
House</entry><entry>
Change to home directory</entry><entry>
Show home in a new window <xref linkend="newwin_fn"/>
</entry></row><row><entry>
Looping arrows</entry><entry>
Reread the directory contents</entry><entry>
Open a new window
</entry></row><row><entry>
Magnifying glass</entry><entry>
Make icons bigger</entry><entry>
Make icons smaller
</entry></row><row><entry>
List</entry><entry>
Hide or show extra details</entry><entry>
Same
</entry></row><row><entry>
Dot files</entry><entry>
Toggle the display of hidden file (those with names starting with a dot)</entry><entry>
Same
</entry></row><row><entry>
Information</entry><entry>
Show <application>ROX-Filer</application>'s help files</entry><entry>
Same
</entry></row>
</tbody></tgroup></informaltable>

<para>
<anchor id="newwin_fn" xreflabel="[1]"/>[1]
If the 'New window on button 1' option is turned on
then the default is to open a new window &mdash; clicking with the other
button reuses the same window instead.
</para>

  <para>
Dragging files to the Up or Home icons acts just like dragging them
into the directory which the button leads to.

The toolbar can also show the number of files in the directory, and
information about the selection. This can be turned on or off in the
Options box.


  </para>
</chapter>

<chapter id="menus">
  <title>The menus</title>
  <para>
By default, you can open a menu by right clicking over a pinboard, panel or filer window.

In filer windows, you may also press <keycap>\</keycap> to open the menu. As a
shortcut, you can open the File submenu directly by holding down the
<keycap>Control</keycap> key when opening the menu. Here is a full description
of each menu item:

<informaltable><tgroup cols="2">

<thead><row><entry>Entry</entry><entry>Action</entry></row></thead>

<tbody>
<row><entry><guimenuitem>Display</guimenuitem></entry><entry>
Change the display settings.
</entry></row>

<row><entry><guimenuitem>File</guimenuitem></entry><entry>
Operations on the selected items.
</entry></row>

<row><entry><guimenuitem>Select</guimenuitem></entry><entry>
Control which items are selected.
</entry></row>

<row><entry><guimenuitem>Options...</guimenuitem></entry><entry>
Configure <application>ROX-Filer</application>.
</entry></row>

<row><entry><guimenuitem>New</guimenuitem></entry><entry>
Create a new file or subdirectory inside this directory.
</entry></row>

<row><entry><guimenuitem>Xterm Here</guimenuitem></entry><entry>
Open an xterm with its current directory set to this directory.
</entry></row>

<row><entry><guimenuitem>Window</guimenuitem></entry><entry>
Operations on the window as a whole.
</entry></row>

</tbody></tgroup></informaltable>

  </para>

<sect1>
  <title>The display menu</title>
  <para>

<informaltable><tgroup cols="2">

<thead><row><entry>Entry</entry><entry>Action</entry></row></thead>

<tbody>
<row><entry><guimenuitem>Huge Icons</guimenuitem></entry><entry>
Extra large icons (mainly useful with thumbnails, see below).
</entry></row><row><entry> 

<guimenuitem>Large Icons</guimenuitem></entry><entry>
Each object in the directory is shown as a large icon with its name
below.
</entry></row><row><entry>

<guimenuitem>Small Icons</guimenuitem></entry><entry>
Items are drawn smaller than usual, allowing you to see more files
at once.
</entry></row><row><entry>

<guimenuitem>Huge, With...</guimenuitem></entry><entry>
As for <guimenuitem>Large, With...</guimenuitem>, but with extra large icons.
</entry></row><row><entry>

<guimenuitem>Large, With...</guimenuitem></entry><entry>
        <para>Entries are displayed along with some extra details:</para>
        <itemizedlist>

        <listitem><para><guimenuitem>Summary</guimenuitem>
        shows the file permissions, owner, group, size and modification time.
        </para></listitem>

        <listitem><para><guimenuitem>Sizes</guimenuitem>
        shows just the size of each file (not directories).
        </para></listitem>

        <listitem><para><guimenuitem>Permissions</guimenuitem>
        shows just the permissions and owner.
        </para></listitem>

        <listitem><para><guimenuitem>Type</guimenuitem>
        shows the MIME type of each file.
        </para></listitem>

        <listitem><para><guimenuitem>Times</guimenuitem>
        shows the times the file was last accessed, modifed and changed.
        Reading a file's contents or listing a directory updates the
        <emphasis>access time</emphasis>; modifying the contents of a file or
        the list of files in a directory updates the <emphasis>modification
        time</emphasis>; changing a file's owner or permissions updates the
        <emphasis>change time</emphasis>.
        </para></listitem>

        </itemizedlist>

</entry></row><row><entry>

<guimenuitem>Small, With...</guimenuitem></entry><entry>
As above, but with a smaller icon and all on one line.
</entry></row><row><entry>

<guimenuitem>Sort by Name</guimenuitem></entry><entry>
Items are arranged by name. There is an option to make this case-sensitive.
</entry></row><row><entry>

<guimenuitem>Sort by Type</guimenuitem></entry><entry>
Items are grouped by their types and then sorted by name within the
groups.
</entry></row><row><entry>

<guimenuitem>Sort by Date</guimenuitem></entry><entry>
Most recently modified first.
</entry></row><row><entry>

<guimenuitem>Sort by Size</guimenuitem></entry><entry>
Largest first.
</entry></row><row><entry>

<guimenuitem>Show Hidden</guimenuitem></entry><entry>
If on, files beginning with a dot are shown, otherwise they are hidden.
</entry></row><row><entry>

<guimenuitem>Refresh</guimenuitem></entry><entry>
Rereads the contents of the directory and details of all the files
in it. Use this if the display becomes out-of-date.
</entry></row><row><entry>

<guimenuitem>Create Thumbs</guimenuitem></entry><entry>
Tries to load every file as an image and use that image as the file's
icon. Useful if you have a directory full of photos and can't remember
which is which!
</entry></row>
</tbody></tgroup></informaltable>

  </para>

<sect2><title><anchor id="Permissions" xreflabel="Permissions"/>
    Permissions
  </title>
  <para>

The permissions field, when shown, is made up of four groups of three
flags. Each flag is displayed as a letter if it is on and a dash (&ndash;)
if not. The first three characters show the permissions for the owner
of the file, the second for other members of the file's group and
the third for everyone else. Whichever group applies to the <application>ROX-Filer</application>
process itself is shown underlined. The fourth group shows any special
flags.
  </para><para>
The meanings of the characters are:

<itemizedlist>

<listitem><para><computeroutput>r</computeroutput> &mdash;
Permission to read the contents of a file, or the names of files
in a directory.</para></listitem>

<listitem><para><computeroutput>w</computeroutput> &mdash;
Permission to alter the contents of a file, or change which names
appear in a directory.</para></listitem>

<listitem><para><computeroutput>x</computeroutput> &mdash;
Permission to run the file as a program, or refer to the files
listed within the directory.</para></listitem>

<listitem><para><computeroutput>U</computeroutput> &mdash;
This program executes with the <emphasis>effective user ID</emphasis> of its
owner rather than the person who ran it.</para></listitem>

<listitem><para><computeroutput>G</computeroutput> &mdash;
This program executes with the <emphasis>effective group ID</emphasis> of its
group, regardless of who ran it.</para></listitem>

<listitem><para><computeroutput>T</computeroutput> &mdash;
Entries in this directory can only be altered or removed by the
people who own the files even if they have write permission on the
directory itself.</para></listitem>

</itemizedlist>
For example,
<programlisting>
<emphasis role="underline">rwx</emphasis>,rwx,r-x/---</programlisting>
means that the owner of the file is the same as the effective user of
<application>ROX-Filer</application> (basically, you own the file), you and
members of the file's group have read, write and execute permission and other
people have only read and execute permission. There are no special flags set.

The rules which determine which permissions apply may vary slightly between
operating systems, but a rough guide is:

<itemizedlist>

<listitem><para>If the <emphasis>effective user ID</emphasis> of the process is equal to the file's
owner, then the owner permissions apply.
</para></listitem>

<listitem><para>Otherwise, if the <emphasis>effective group ID</emphasis> of the process is equal
to the file's group OR the file's group is one of the process's <emphasis>supplemental
groups</emphasis> then the group permissions apply.
</para></listitem>

<listitem><para>Otherwise, the `other' permissions apply. The <emphasis>real user ID</emphasis>
and <emphasis>real group ID</emphasis> have no effect (except that a process may
set its real IDs to its effective IDs).
</para></listitem>

</itemizedlist>

  </para>
</sect2>
</sect1>

<sect1>
  <title>The selection menu</title>
  <para>

All of these work in the same way &mdash; if you open the menu with some
items selected then the operation applies to those items. If you open
then menu over an item while there is no selection then that item
is temporarily selected. If you choose one of these while there is
no selection at all then the window goes into `target mode'; the operation
happens to the next item you click on. Click on the window background,
press Escape, or click with the right mouse button to cancel target
mode. Target mode is mainly useful with the `Single click navigation'
option and keys bound to the various menu entries.

Note that individual applications may add extra menu items to the
top of this submenu when you click over them &mdash; see
<xref linkend="AppDir"/> for details.


<informaltable><tgroup cols="2">
<thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
<tbody>

<row><entry> 
<guimenuitem>Copy...</guimenuitem></entry><entry>
Make a copy of this object.
</entry></row>

<row><entry>
<guimenuitem>Rename...</guimenuitem></entry><entry>
Change the name used for this object, or move it between directories.
</entry></row>

<row><entry>
<guimenuitem>Link...</guimenuitem></entry><entry>
Create a symbolic link to this name.
</entry></row>

<row><entry>
<guimenuitem>Shift Open</guimenuitem></entry><entry>
Opens applications as directories, files as text/plain, mount points by
mounting or unmounting them and symlinks by opening the directory containing
the thing they point to. This is the same effect as clicking with Shift
held down. The text of the menu entry changes to show which action
will be performed.
</entry></row>

<row><entry>
<guimenuitem>Help</guimenuitem></entry><entry>
Explain what kind of thing is selected. For applications, display
the help files.
</entry></row>

<row><entry>
<guimenuitem>Info</guimenuitem></entry><entry>
Display extra information about this object.
</entry></row>

<row><entry>
<guimenuitem>Set Run Action...</guimenuitem></entry><entry>
Allows you to set the default program to use when opening files of
this type. See <xref linkend="RunAction"/> section for details.
</entry></row>

<row><entry>
<guimenuitem>Set Icon...</guimenuitem></entry><entry>
You can give each file or directory its own special icon using this
feature &mdash; simply drag a suitable image onto <xref linkend="SetIcon"/>.
</entry></row>

<row><entry>
<guimenuitem>Open (A)VFS</guimenuitem></entry><entry>
Open the file as if it was a directory &mdash; see the
<xref linkend="vfs"/> section.
</entry></row>

<row><entry>
<guimenuitem>Send To...</guimenuitem></entry><entry>
Opens the `Send To' menu, allowing you to send the selected files
to one of a list of applications. See the
<xref linkend="SendTo"/> section.
</entry></row>

<row><entry>
<guimenuitem>Delete</guimenuitem></entry><entry>
Remove all the selected entries from the directory. Subdirectories
will have their contents deleted first. Deleting symlinks only removes
the link, not the thing it points to.
</entry></row>

<row><entry>
<guimenuitem>Disk Usage</guimenuitem></entry><entry>
Count the sizes of all the selected items. Directories also have their contents
counted. Symlinks count themselves, not the things they point to.
</entry></row>

<row><entry>
<guimenuitem>Permissions</guimenuitem></entry><entry>
Allows you to change the permissions for the selected files.
</entry></row>

<row><entry>
<guimenuitem>Find</guimenuitem></entry><entry>
Search for files by specifying various conditions &mdash; see the
<xref linkend="Searching"/> section.
</entry></row>

</tbody></tgroup></informaltable>
  </para>

  <formalpara><title>Note about symlinks:</title>
    <para>
A symbolic link stores the <emphasis>location</emphasis>
of another file. Deleting the symlink doesn't affect the other file.
Deleting the other file means that the symlink won't work. There are
two types of symbolic link &mdash; Relative and Absolute. An absolute
link stores the path from the root directory to the target file (eg
<filename>/home/fred/MyFile</filename>).

A relative path stores the path from the symlink
to the target (eg <filename>../fred/MyFile</filename>).
If the target file is never going to move then you want an absolute link, but
if the target may move (and the symlink will be moved with it) then you want a
relative link.
    </para>
  </formalpara>
</sect1>

<sect1>
  <title>The new menu</title>
  <para>

Each entry in this submenu opens a savebox for creating a new file
or directory. There are two standard entries; the others are the contents
of your <filename>&lt;Choices&gt;/Templates</filename> directory, if it exists.


<informaltable><tgroup cols="2">
<thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
<tbody>
<row><entry> 
Directory</entry><entry>
Create a new directory.
</entry></row><row><entry>
File</entry><entry>
Create a blank file.
</entry></row><row><entry>
&lt;user entries&gt;</entry><entry>
Copy a file from your Templates directory.
</entry></row>
</tbody></tgroup></informaltable>


To add your own entries, create a new directory called
<filename>~/Choices/Templates</filename>
(if you have the default CHOICESPATH) and put any files you want in
there. Each file in the directory will appear on the menu and the
box that appears will copy it. For example, you could create a blank
HTML file:

<programlisting>
&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;My Page&lt;/title&gt;
  &lt;/head&gt;
  &lt;body&gt;
    The contents.
  &lt;/body&gt;
&lt;/html&gt;
</programlisting>

Save this as <filename>index.html</filename> inside the
<filename>Templates</filename> directory and you can easily create new
HTML files. You can also save blank documents from various applications
into here (eg, a blank spreadsheet, a blank letter, etc).
  </para><para>
Note that you cannot set keyboard shortcuts for these user-defined
entries at present.

  </para>
</sect1>

<sect1>
  <title>The select menu</title>
  <para>
<informaltable><tgroup cols="2">
<thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
<tbody>
<row><entry> 
<guimenuitem>Select All</guimenuitem></entry><entry>
Select every item in this window.
</entry></row>

<row><entry><guimenuitem>Clear Selection</guimenuitem></entry><entry>
Unselect every item in this window.
</entry></row>

<row><entry>
<guimenuitem>Select If...</guimenuitem></entry><entry>
Select just those files that match the given pattern &mdash;
see the <xref linkend="SelectIf"/> section).
</entry></row>

</tbody></tgroup></informaltable>

  </para>
</sect1>

<sect1>
  <title>The window menu</title>
  <para>


<informaltable><tgroup cols="2">
<thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
<tbody>
<row><entry> 
<guimenuitem>Parent, New Window</guimenuitem></entry><entry>
Open a new window displaying this window's parent.
</entry></row>

<row><entry>
<guimenuitem>Parent, Same Window</guimenuitem></entry><entry>
As above, but reuse this window.
</entry></row>

<row><entry>
<guimenuitem>New Window</guimenuitem></entry><entry>
Open another window onto this directory.
</entry></row>

<row><entry>
<guimenuitem>Home Directory</guimenuitem></entry><entry>
Change to your home directory.
</entry></row>

<row><entry>
<guimenuitem>Resize Window</guimenuitem></entry><entry>
Set the window to a sensible size for its contents.
</entry></row>

<row><entry>
<guimenuitem>Close Window</guimenuitem></entry><entry>
Close this window.
</entry></row>

<row><entry>
<guimenuitem>Enter Path...</guimenuitem></entry><entry>
Open the path-entry box (see the the <xref linkend="mini"/> section).
</entry></row>

<row><entry>
<guimenuitem>Shell Command...</guimenuitem></entry><entry>
Open the shell command box (see the <xref linkend="mini"/> section).
</entry></row>

<row><entry>
<guimenuitem>Show ROX-Filer Help</guimenuitem></entry><entry>
Same as selecting ROX-Filer and choosing `Help' from the menu.
</entry></row>

</tbody></tgroup></informaltable>


  </para>
</sect1>

<sect1>
  <title><anchor id="SendTo" xreflabel="Send To menu"/>The send to menu</title>
  <para>

The `Send To' menu provides a quick way to send some files to an application.
The filer scans all the <filename>SendTo</filename> directories in your
<envar>CHOICESPATH</envar> and lists the contents on this menu.
  </para><para>
To change which applications appear here you should choose the
<guimenuitem>Customise</guimenuitem> item from the bottom
of the menu to create and open your own SendTo directory. Applications can be
symlinked into this directory by dragging them in with <keycap>Control</keycap>
and <keycap>Shift</keycap> held down.
  </para><para>
Opening the Send To menu via the main menu is rather slow, so it is
normally opened by clicking the Menu mouse button over a file while
holding the <keycap>Shift</keycap> key down.

  </para>
</sect1>

</chapter>

<chapter id="icons">
  <title>The pinboard and panels</title>
  <para>

The <xref linkend="run_pin"/> and <xref linkend="run_pan"/> sections explain
how to turn the pinboard and panels on. Once on, you may drop items from filer
windows onto the them to pin them up. Clicking on a pinned item acts just like
clicking on it in a filer window. You can drag pinned icons just like normal
icons and you can right-click on one to see the popup menu.
  </para><para>
Drag pinned icons with the middle mouse button to move them around
(they snap to a grid on the pinboard). Changes to the pinboard and
panel are automatically saved. Clicking on pinned icons with Control
held down selects and unselects them. Click on the background to unselect
them all.
  </para><para>
If the panel has so many icons that they can't all be shown at once
then you can scroll it by dragging the blank area in the middle.
  </para>

  <important><para>
Pinning a file does <emphasis>not</emphasis> copy it, it merely
creates a shortcut to the original file. If you delete the file, then
you've lost it! Removing a pinned file from its pinboard or panel
only removes the link. This is different to most other filers...
  </para></important>

<sect1>
  <title>The pinboard and panel menus</title>
  <para>

These menus are both the same, and very simple:


<informaltable><tgroup cols="2">
<thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
<tbody>

<row><entry> 
<guimenuitem>ROX-Filer</guimenuitem></entry><entry>
Show the filer's help, edit the options or open your home directory.
</entry></row>

<row><entry> 
<guimenuitem>File `file'</guimenuitem></entry><entry>
Offers a smaller version of the filer's submenu of the same name.
</entry></row>

<row><entry> 
<guimenuitem>Edit Item</guimenuitem></entry><entry>
Change the name displayed under the icon, or the pathname the item
points to.
</entry></row>

<row><entry> 
<guimenuitem>Show Location</guimenuitem></entry><entry>
Open a directory viewer showing where the file is stored.
</entry></row>

<row><entry> 
<guimenuitem>Remove Item(s)</guimenuitem></entry><entry>
Remove the selected items from the pinboard or panel.
</entry></row>

</tbody></tgroup></informaltable>

If you are setting up the defaults for multiple users and
you wish to create a `Home' icon that leads to each user's home directory
then you should first create a new icon and then use
<guimenuitem>Edit Icon</guimenuitem> to change the location to
<filename>~</filename> and the name to `Home'.
  </para><para>
Note that individual applications may add extra menu items to the
top of this menu when you click over them &mdash; see <xref linkend="AppDir"/>
for details.
</para>
</sect1>

<sect1>
  <title>Panel applets</title>
  <para>

<application>ROX-Filer</application> allows you to run small programs inside the panel &mdash; such
programs are called <emphasis>applets</emphasis>. To run an applet, drag it onto
the panel from a filer window and instead of the applet's icon being
shown, the applet will run.
  </para>

  <procedure><title>To create your own applets (programmers only!):</title>

    <step><para>
Create a directory for the applet (eg <filename>MyApplet</filename>).
    </para></step>

    <step><para>
Put an icon called <filename>.DirIcon.png</filename> inside it (so the directory
appears with an icon).
    </para></step>

    <step><para>
Make a <filename>Help</filename> directory inside it for when the user chooses
<guimenuitem>Help</guimenuitem> from the menu.
    </para></step>

    <step><para>
Create an executable file called <filename>AppletRun</filename>. This will be
passed the XID of the panel socket window when the directory is dragged
onto the panel. You can use this to create a GtkSocket widget. An
example applet (written in python) is available at 
<ulink url="http://rox.sourceforge.net/applets.php3"/>
    </para></step>

  </procedure>
</sect1>
</chapter>

<chapter id="virtual">
  <title>
    <anchor id="vfs" xreflabel="Virtual file systems"/>Virtual file systems
  </title>
  <para>

Some types of file can be represented as a directory. A typical example
is a zip file, which contains an entire directory structure in compressed
form. It is often useful to be able to open up such a file as if it
was a real directory, and the VFS system allows you to do this.

<itemizedlist><title>To use this feature you must have one or both of the following:</title>

<listitem><para>
A system such as AVFS<citation>AVFS</citation> which causes the kernel to support
various Virtual File Systems directly. This is the best option since
all programs will be able to access the contents of the VFS. You may
require root access to install such a system, however, and it is not
available on all platforms.
</para></listitem>

<listitem><para>
Support for the Midnight Commander VFS library compiled into
<application>ROX-Filer</application>. This happens automatically when you
compile <application>ROX-Filer</application> if it can find
the VFS library &mdash; this means having <filename>libvfs.so</filename>
(or <filename>libvfs.a</filename>) in a system library directory or in the
directory in the environment variable <envar>LD_LIBRARY_PATH</envar>. In this case,
you will be able to view the directory structure and copy files out of it, but
not change it. Support for this may be added later.
<application>Midnight Commander</application> is part of the GNOME project.
</para>

<para>
When using libvfs, the menu structure is slightly different &mdash; <guimenuitem>Open
AVFS</guimenuitem> is replaced by the <guisubmenu>Open VFS</guisubmenu> submenu.
This is simply a short-cut for using the path-entry box (explained below), so
if you want to use a VFS not listed on the menu you can type in the path
directly, eg: <filename>/home/fred/archive.zip#uzip/</filename>.

Don't forget the final slash!

</para></listitem>
</itemizedlist>

</para>

<procedure><title>Step by step example of adding VFS support</title>
<note><para>
        Some versions of libvfs don't work correctly this way. AVFS is recommended instead.
</para></note>

  <step><para>
                  
This assumes that you have the Midnight Commander source in a directory
called <filename>mc</filename>.
You might need to replace <filename>libvfs.so</filename> with
<filename>libvfs.a</filename>.

<screen>
$ cd mc
$ ./configure
$ cd vfs
$ make libvfs.so
</screen>

  </para></step><step><para>

If you have the root password then install the library in a system library
directory as normal.

  </para></step><step><para>

If not,

<screen>
$ mkdir ~/lib
$ cp libvfs.so ~/lib
$ cd ~/Apps/ROX-Filer
</screen>
Edit the <filename>AppRun</filename> file to include this as the <emphasis>second</emphasis>
line:

<programlisting>LD_LIBRARY_PATH=$HOME/lib; export LD_LIBRARY_PATH</programlisting>

This will ensure that <application>ROX-Filer</application> will look for the
library in the new <filename>~/lib</filename> directory.

  </para></step><step><para>

Finally, recompile:

<screen>
$ ./AppRun --compile

...

checking for mc_stat in -lvfs... yes
</screen>

If you saw that line then it's worked! Well done!

  </para></step>

</procedure>

</chapter>

<chapter id="minibuffer">
  <title><anchor id="mini" xreflabel="Minibuffer"/>The mini-buffer</title>
  <para>

The mini-buffer is a white bar that appears along the bottom of the
window and allows you to enter some text. Press Escape to get rid
of it again. It behaves in different ways depending on how you invoked
it:
  </para>

<sect1>
  <title>The path-entry box</title>
  <para>

This allows you to type in a path directly. As you type the display
is updated to show the item entered visually. The main use is to find
a file in a large directory quickly, but you can also use it for navigating
between directories, or for selecting a full pathname from somewhere
else and pasting it directly into the path-entry box.


<informaltable><tgroup cols="2">
<thead><row><entry>Key</entry><entry>Action</entry></row></thead>
<tbody>

<row><entry> 
<keycap>Return</keycap></entry><entry>
Open the currently selected item.
</entry></row>

<row><entry>
<keycap>Tab</keycap></entry><entry>
Shell-style tab completion.
</entry></row>

<row><entry>
<keycap>Up</keycap>, <keycap>Down</keycap></entry><entry>
Select the previous/next matching entry.
</entry></row>
</tbody></tgroup></informaltable>

  </para>

  <para>
If you start entering a name beginning with a `.' then the `Show Hidden'
feature is temporarily turned on so that the file can be shown.
  </para>

  <para>
Tab completion tries to fill in as many characters for you as it can.
For example, if there are two files in a directory called `save-mail-nov-1999'
and `save-mail-dec-1999' then typing 'save' and pressing Tab will
expand `save' to `save-mail-' and beep to indicate that the match
is not complete. If you use tab completion on a directory and it is
unique then the filer will automatically change into the directory.
This behavior should be familiar to shell users.
  </para>

  <informalexample><para>
Let's say you want to locate the documentation for Wine in the directory
<filename>/usr/doc</filename> (which is usually very large).
Here's how you could do it:

<orderedlist>

<listitem><para>
Open the minibuffer by choosing <guimenuitem>Enter Path...</guimenuitem> from the
<guimenu>Window</guimenu> menu.
I usually bind this function to the slash (<keycap>/</keycap>) key.
</para></listitem>

<listitem><para>
Press <keycap>CTRL</keycap>+<keycap>U</keycap> to delete the existing contents
&mdash; this moves you to the root directory.
</para></listitem>

<listitem><para>
Type <userinput>u&lt;Tab&gt;do&lt;Tab&gt;wi&lt;Tab&gt;</userinput>.
As you type, the cursor will move to the correct subdirectory.
If it beeps when you press Tab then you need to supply more letters.
</para></listitem>

</orderedlist>

  </para></informalexample>
</sect1>

<sect1>
  <title>The shell command box</title>
  <para>

This provides a quick way of entering shell commands if you don't
want to open an xterm. If you don't know what shell commands are,
skip this section!
  </para><para>
Just type in the command and press <keycap>Return</keycap> to execute it.
<keycap>Up</keycap> and <keycap>Down</keycap> arrows move through previously
entered commands.
<keycap>Tab</keycap> does shell-style completion.
Clicking on an item inserts its name into the minibuffer.
If some items are selected then they are assigned to the positional
parameters <userinput>$1</userinput>, <userinput>$2</userinput>, etc.
  </para><para>
Opening the minibuffer with a selection adds <computeroutput>$@</computeroutput>
to the end of the command &mdash; this expands to all the selected files.
If there is no selection, but a file is under the cursor, the name
of that file is inserted.
  </para>

  <informalexample><para>Examples:

<orderedlist><title>To untar a <filename>.tgz</filename> archive:</title>

<listitem><para>
Open the minibuffer by choosing <guimenuitem>Shell Command...</guimenuitem> from
the <guimenu>Window</guimenu> menu.
I usually bind this to the bang (<keycap>!</keycap>) key.
</para></listitem>

<listitem><para>
Type <userinput>tar xzf</userinput> and click on the file.
The leading space is automatically inserted.
</para></listitem>

<listitem><para>
Press <keycap>Return</keycap> to execute it.
</para></listitem>

</orderedlist>

<orderedlist><title>To print all the selected files:</title>

<listitem><para>
Open the shell command minibuffer.
</para></listitem>

<listitem><para>
Type <userinput>lpr</userinput> at the beginning of the line and press
<keycap>Return</keycap>.
</para></listitem>

</orderedlist>

</para></informalexample>

<itemizedlist><title>Notes</title>

<listitem><para>
Be careful; you will not be asked to confirm! If in doubt, start the
command with <userinput>xmessage</userinput> so that it will be displayed
rather than executed.
</para></listitem>

<listitem><para>
<citerefentry><refentrytitle>sh</refentrytitle></citerefentry>
is always used as the name of the shell to run (mainly because
<citerefentry><refentrytitle>bash</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>csh</refentrytitle></citerefentry> treat
positional parameters differently).
However, <envar>PATH</envar> is searched to find it so you can still use
another shell if you want by naming it sh and putting it in your path.
</para></listitem>

<listitem><para>
Commands execute in the background, so you can say:

<command>sleep 240; xmessage Time to go!</command>
</para></listitem>

</itemizedlist>
</sect1>

<sect1>
  <title><anchor id="SelectIf" xreflabel="Select If"/>The conditional selection box</title>
  <para>

Use this if you want to automatically select all files in the directory
which match a condition.

<orderedlist><title>For example, to select all files larger than 5Mb:</title>

<listitem><para>
Open the Select If minibuffer.
</para></listitem>

<listitem><para>
Type <userinput>Size &gt; 5Mb</userinput> and press <keycap>Return</keycap>.
</para></listitem>

</orderedlist>

Just those files over 5 Mb in size will be selected. The expressions
you can enter are in the same form as described in the
<xref linkend="Searching"/> section, except that
<userinput>prune</userinput> has no effect since the contents of
directories are never checked anyway. You can press <keycap>Tab</keycap>
to jump to each selected file in turn.

  </para>
</sect1>
</chapter>

<chapter id="actions">
  <title>Action windows</title>
  <para>

Action windows are those boxes that appear while you're doing a
Copy/Move/Link/etc
operation. The status line at the top of the window shows the current
directory or object that the window is processing. The scrolling area
below is the log area &mdash; it shows what has been done and may display
questions here.
  </para><para>
At the bottom are four buttons and, sometimes, some options. The buttons
work as follows:

<variablelist>

<varlistentry><term><guibutton>Quiet</guibutton></term><listitem><para>
will do simple operations without asking you to confirm each
one. By turning this on and off during an operation you can use it
like a pause button.
</para></listitem></varlistentry>

<varlistentry><term><guibutton>Yes</guibutton></term><listitem><para>
answers yes to the question displayed in the log area.
</para></listitem></varlistentry>

<varlistentry><term><guibutton>No</guibutton></term><listitem><para>
answers no to the question displayed in the log area.
</para></listitem></varlistentry>

<varlistentry><term><guibutton>Abort</guibutton></term><listitem><para>
kills the current operation (if any) and closes the action
window.
</para></listitem></varlistentry>

</variablelist>

You can control which actions get started automatically (without you
having to click on <guibutton>Quiet</guibutton> at the start) from the
Options window.
  </para>

<sect1>
  <title>Action window options</title>
  <para>

Some actions have options, which appear as option boxes at the bottom
of the window. They are:

<itemizedlist>

<listitem><para>
<guilabel>Force</guilabel> means that the filer won't treat non-writeable
files as special.  Normally, it confirms the deletion even if
<guibutton>Quiet</guibutton> is pressed.
Note that you still can't remove files from non-writeable directories because
in that case you really don't have permission.
</para></listitem>

<listitem><para>
<guilabel>Brief</guilabel> prevents the filer logging a message every time it
does something.  Use this to speed things up if large numbers of messages are
being logged.
</para></listitem>

<listitem><para>
<guilabel>Recurse</guilabel> means that doing something to a directory will
also do the same thing to all its contents, and the contents of any
subdirectories, and so on.
</para></listitem>

</itemizedlist>

  </para>
</sect1>
</chapter>

<chapter id="searching">
  <title><anchor id="Searching" xreflabel="Searching"/>Searching</title>
  <para>

The Find feature looks through all the selected files and directories
and any subdirectories (recursively) looking for items that match
a particular expression.

If you know the name of a file then just enter it in the `Expression:'
box, enclosed in single quotes. For example, to find a file called
<filename>log</filename> you would enter <userinput>'log'</userinput>.

Remember to use normal quotes, not double quotes (") or back-quotes (`).
  </para><para>
As the filer finds matching files they are added to the results list.
Clicking on an entry in the list opens a viewer showing the file you
clicked on. The filer will use the same window to view other results
(so, if you want the results shown in separate windows you must explicitly
create a new window from the <guimenu>Window</guimenu> menu).
  </para>

<sect1>
  <title>Wildcards</title>
  <para>

You can also put shell-style wildcard characters inside the quotes,
for example:

  <simplelist>

    <member><command>'*.html'</command></member>
    <member><command>'Report.*'</command></member>
    <member><command>'Draft[1-5]'</command></member>
    <member><command>'main.[ch]'</command></member>

  </simplelist>

Look at the
<citerefentry><refentrytitle>glob</refentrytitle>
<manvolnum>7</manvolnum></citerefentry>
manpage if you want to know more about shell wildcards.
  </para><para>
If the pattern you enter contains a slash (`/') character then the
pattern is matched against the file's full path, otherwise only the
leafname is used. That is, <userinput>'*tmp*'</userinput> will find
<filename>tmp</filename> and <filename>tmpfile</filename> but not
<filename>/tmp/file</filename> &mdash; <userinput>'/*tmp*'</userinput> will find
all three.
  </para>
</sect1>

<sect1>
  <title>Simple tests</title>
  <para>
As well as finding files by their names you can also find them by
various other attributes. Note that <emphasis>file</emphasis> is used here to
mean anything that can appear in the filesystem &mdash; including directories,
devices and so on.
  </para>

<itemizedlist><title>These look at the type of the item being checked:</title>

<listitem><para>
<userinput>IsReg</userinput> matches any regular (ie, normal) file.
</para></listitem>

<listitem><para>
<userinput>IsLink</userinput> matches symlinks.
</para></listitem>

<listitem><para>
<userinput>IsDir</userinput> matches directories.
</para></listitem>

<listitem><para>
<userinput>IsChar</userinput> matches character device files.
</para></listitem>

<listitem><para>
<userinput>IsBlock</userinput> matches block device files.
</para></listitem>

<listitem><para>
<userinput>IsDev</userinput> matches block or character device files.
</para></listitem>

<listitem><para>
<userinput>IsPipe</userinput> matches pipes.
</para></listitem>

<listitem><para>
<userinput>IsSocket</userinput> matches sockets.
</para></listitem>

</itemizedlist>

<itemizedlist><title>These look at the permissions set on the file &mdash;
see the <xref linkend="Permissions"/> section.</title>

<listitem><para>
<userinput>IsSUID</userinput> matches files which have the Set-UID bit set.
</para></listitem>

<listitem><para>
<userinput>IsSGID</userinput> matches files which have the Set-GID bit set.
</para></listitem>

<listitem><para>
<userinput>IsSticky</userinput> matches files with the sticky bit set.
</para></listitem>

<listitem><para>
<userinput>IsReadable</userinput> matches files which you can read from.
</para></listitem>

<listitem><para>
<userinput>IsWriteable</userinput> matches files which you can write to.
</para></listitem>

<listitem><para>
<userinput>IsExecutable</userinput> matches files which you can execute.
</para></listitem>

</itemizedlist>

<itemizedlist><title>And a couple of other useful ones:</title>

<listitem><para>
<userinput>IsEmpty</userinput> finds empty files (ie, those whose length is 0 bytes).
</para></listitem>

<listitem><para>
<userinput>IsMine</userinput> finds files which you own.
</para></listitem>

</itemizedlist>

</sect1>

<sect1>
  <title>Logic operators</title>
  <para>
You can combine the above tests in various ways to perform more advanced
searches.
An expression is actually made up of a list of <emphasis>cases</emphasis>,
separated by commas. The filer will try to match each case in turn
until one matches or there are no more cases left. For example, to
search for files with several possible endings:

<userinput>'*.gif', '*.htm', '*.html'</userinput>

Further, each of the cases is actually a list of conditions. The case
only matches if all of its conditions are met. So, to find a directory
called <filename>lib</filename> or a regular file ending in
<filename>.so</filename>:

<userinput>IsDir 'lib', IsReg '*.so'</userinput>

You can negate a condition by putting a <userinput>!</userinput> in front of it
and you can use a sub-expression as a condition by bracketing it, like this:

<screen>
!(IsDir, IsReg)

!IsDir !IsReg

Not isdir and not isreg
</screen>
All three do the same thing.
  </para>
</sect1>

<sect1>
  <title>Comparisons</title>
  <para>
You can also compare various values using the operators
<userinput>&lt;</userinput>,
<userinput>&lt;=</userinput>,
<userinput>=</userinput>,
<userinput>!=</userinput>,
<userinput>&gt;</userinput>, and
<userinput>&gt;=</userinput>
(for less-than, less-than-or-equal-to, equal-to,
not-equal-to, greater-than and greater-than-or-equal-to).

When comparing times, you may find it helpful to use
<userinput>after</userinput> and <userinput>before</userinput> instead of
<userinput>&gt;</userinput> and <userinput>&lt;</userinput> to make things
clearer.
  </para>

<itemizedlist><title>
The following are read from the file being checked and may be used
for the values being compared:
</title>

<listitem><para>
<userinput>atime</userinput> The time that the file was last accessed.
</para></listitem>

<listitem><para>
<userinput>ctime</userinput> The time that the file's status was last changed.
</para></listitem>

<listitem><para>
<userinput>mtime</userinput> The time that the file's contents were last modified.
</para></listitem>

<listitem><para>
<userinput>size</userinput> The size of the file.
</para></listitem>

<listitem><para>
<userinput>inode</userinput> The file's inode (index) number.
</para></listitem>

<listitem><para>
<userinput>nlinks</userinput> The number of links to this file. That is, the number of directory
entries which refer to this file. Note that symlinks don't count as
references.
</para></listitem>

<listitem><para>
<userinput>uid</userinput> The User ID of the file.
</para></listitem>

<listitem><para>
<userinput>gid</userinput> The Group ID of the file.
</para></listitem>

<listitem><para>
<userinput>blocks</userinput> The number of disk blocks being used by the file.
</para></listitem>

</itemizedlist>

  <para>
Times are measured as seconds since the Unix Epoch (00:00:00 UTC,
January 1, 1970). Sizes are in bytes. When specifying constants to
compare these values with you may use various keywords to scale the
value:

<itemizedlist>

<listitem><para>
<userinput>Byte(s)</userinput> has no effect, but looks better.
</para></listitem>

<listitem><para>
<userinput>Kb</userinput> multiplies by 1024, so 2Kb is the same as 2048.
</para></listitem>

<listitem><para>
<userinput>Mb</userinput> multiplies by 1024<superscript>2</superscript>,
ie 1024 Kb.
</para></listitem>

<listitem><para>
<userinput>Sec(s)</userinput> has no effect, but looks nice.
</para></listitem>

<listitem><para>
<userinput>Min(s)</userinput> multiplies by 60 to get minutes.
</para></listitem>

<listitem><para>
<userinput>Hour(s), Day(s), Week(s), Year(s)</userinput> likewise convert to the relevant
unit.
</para></listitem>

<listitem><para>
<userinput>Ago</userinput> makes the time in the past relative to when the check is done.
</para></listitem>

<listitem><para>
<userinput>Hence</userinput> makes the time in the future.
</para></listitem>

<listitem><para>
<userinput>Now</userinput> is short for <userinput>0 Secs Hence</userinput>.
</para></listitem>

</itemizedlist>

Some examples should make this all a bit clearer!

<screen>
mtime after 1 day ago

size &gt; 10 Mb

IsReg and nlinks &gt; 1
</screen>
The first finds files modified within the last 24 hours. You could
use <userinput>&gt;</userinput> instead of <userinput>after</userinput>,
but it's not so clear what is meant.
</para><para>
The second finds files larger than 10 Mb and the last finds
regular files with more than one directory entry.
</para><para>
Be careful though &mdash; the filer doesn't check the context of the modifiers,
so <userinput>size &gt; 1 day ago</userinput> is allowed, although it
doesn't make much sense!

Also, forgetting to use <userinput>ago</userinput> or
<userinput>hence</userinput> will cause odd effects (the time will be
measured relative to the Epoch rather than the current time).
Finally, don't use <userinput>=</userinput> with times &mdash;
<userinput>atime = 1 day ago</userinput> looks for a file accessed
<emphasis>exactly</emphasis> 86400 seconds ago...

  </para>
</sect1>

<sect1>
  <title>Specials</title>
  <para>

<itemizedlist>

<listitem><para>
<userinput>System(Command)</userinput> executes `Command' on the file. The test
succeeds if the command returns an exit status of zero. A `%' character in
`Command' is replaced by the full path of the file being checked.
<userinput>System</userinput> is a very slow test to perform, so do it last if
possible.  For example, if you're looking for a <filename>.c</filename> file
containing the word `main', do:

<screen>
'*.c' system(grep -q main "%")
</screen>
so that the grep is only performed for files ending in <filename>.c</filename>
(as opposed to only checking that the file ends in <filename>.c</filename> if
it contains the word `main').
</para></listitem>

<listitem><para>
<userinput>Prune</userinput> Always fails!
<footnote><para>Note that this is the opposite of the
<citerefentry><refentrytitle>find</refentrytitle><manvolnum>1</manvolnum>
</citerefentry> command.</para></footnote>

However, if it gets evaluated at all then it prevents the filer
from checking inside the current directory. Remember the order in which
the filer checks the expression!
</para></listitem>

</itemizedlist>

Examples:

<screen>
'*.old' system(rm '%')

'src' prune, '*.c'
</screen>
The first deletes each file ending in <filename>.old</filename>.
The second looks for <filename>.c</filename> files, but does not bother
checking inside directories called <filename>src</filename>.
The expression is evaluated like this:

<mediaobject>
  <imageobject>
    <imagedata align="center" format="PNG" fileref="../Prune.png"/>
  </imageobject>
  <textobject>
    <para>
If file is named <filename>src</filename> then `Prune'.
Either way, check if it ends in <filename>.c</filename> and include
it in the results if so.
    </para>
  </textobject>
</mediaobject>

  </para>
</sect1>
</chapter>

<chapter id="options">
  <title>Options</title>
  <para>

You can configure various aspects of <application>ROX-Filer</application> from
the Options box.
Choose <guimenuitem>Options...</guimenuitem> from a filer window menu to open
it. 

At the bottom of the window are four buttons:

<itemizedlist>

<listitem><para>
<guibutton>Save</guibutton>
puts all your choices into effect, and also saves them into
your Choices directory for next time <application>ROX-Filer</application> is
loaded. <application>ROX-Filer</application> will never save any preferences to
disk unless you click on the <guibutton>Save</guibutton> button in the options
window. Exactly where choices are loaded from and saved to is controlled by
the <envar>CHOICESPATH</envar> environment variable &mdash; see
<citation>Choices</citation> for details.
</para></listitem>

<listitem><para>
<guibutton>OK</guibutton>
puts your choices into effect without writing anything to disk.
</para></listitem>

<listitem><para>
<guibutton>Apply</guibutton>
works like <guibutton>OK</guibutton>, but without closing the Options window.
</para></listitem>

<listitem><para>
<guibutton>Cancel</guibutton>
closes the options box and forgets any changes you made.
</para></listitem>

</itemizedlist>

Many of the options in the Options window have tooltips &mdash; hold the
mouse pointer over the option to find out what it does.

  </para>

<sect1>
  <title>Translation options</title>
  <para>

You can choose which language the filer will display messages in from
here. There are also two special choices:

<itemizedlist>

<listitem><para>
<guimenuitem>None</guimenuitem> causes the untranslated English messages to be
used;
</para></listitem>

<listitem><para>
<guimenuitem>From LANG</guimenuitem> will use the value of the
<envar>LANG</envar> environment variable as the name of the file to load
from <filename>ROX-Filer/Messages</filename>.
</para></listitem>

</itemizedlist>

  </para>
</sect1>

<sect1>
  <title>Display options</title>
  <para>

<itemizedlist>
<listitem><para><guilabel>Ignore case when sorting</guilabel>
treats upper and lower case letters as
equivalent when sorting. If this is off then <filename>Zoo</filename> comes
before <filename>animal</filename>, for example.
</para></listitem>

<listitem><para><guilabel>Ignore eXecutable bit for known extensions</guilabel> means that when a file
has a known extension (eg <filename>.gif</filename>) the executable bit is
ignored. This is useful if you have files on a Windows-type filesystem which are
being shown as executable programs. However, it prevents a file such
as <filename>script.sh</filename> from being treated as a program.
</para></listitem>

<listitem><para><guilabel>Directories always come first</guilabel> means that
all directories are sorted and displayed at the top, then all the other items
are sorted and displayed below. With this option off, directories are mixed in
with the other files.
</para></listitem>

<listitem><para><guilabel>Large wrap width</guilabel> sets the maximum width
for a file's name in `Large Icons' display mode before the text will wrap onto
two lines. In `Huge Icons' mode, the wrap width is 50% larger than this value.
</para></listitem>

<listitem><para><guilabel>Max Small Icons width</guilabel> &mdash; as above,
but applies when the display is in `Small Icons' display mode.
</para></listitem>

<listitem><para><guilabel>Inherit options from source window</guilabel> controls what
happens when you open a new window from an existing window (eg, by clicking the middle button
over a file). If on, the new window has the same options (icon size, sort order, etc) as the
old window. If off, the new window has the default options.</para></listitem>

<listitem><para><guilabel>Default settings for new windows</guilabel>. These correspond to the
display styles you can choose from the <guimenuitem>Display</guimenuitem> menu.
</para></listitem>

<listitem><para><guilabel>Colour files based on their types</guilabel>.
If on, each file's name is coloured depending on what kind of thing it is
(regular file, directory, executable, etc). You can choose the colours from
the list below.</para></listitem>

</itemizedlist>

The remaining options provide the default settings for newly opened
windows &mdash; they correspond to choosing styles from the Display menu.
Icon size is also used when switching off the details display from
the toolbar.

  </para>
</sect1>

<sect1>
  <title>Pinboard options</title>
  <para>

If you are using the pinboard features (see the <xref linkend="run_pin"/>
section) then you can choose how the text under each icon is displayed. If
you have a fairly uniform background then you may like to choose <guilabel>No
background</guilabel>, which simply draws the text directly over the desktop
background. However, users with more `noisy' backdrops may find such
text hard to read; selecting <guilabel>Rectangular background slab</guilabel>
will draw a solid rectangle behind the text to make it easier to read.

You may also change the foreground and background colours used for
the text by clicking on the colour slabs in the Options window.

<itemizedlist>
<listitem><para> <guilabel>Keep icons within screen limits</guilabel> prevents icons from going partly
off the side of the screen.
</para></listitem>

<listitem><para> <guilabel>Icon grid step</guilabel> controls how finely the icons may be positioned.
</para></listitem>

</itemizedlist>

  </para>
</sect1>

<sect1>
  <title>Panel options</title>
  <para>

If you are using panels (see the <xref linkend="run_pan"/> section)
then this section lets you choose which icons will have textual labels
underneath them.
You can have labels on all icons, on no icons, or on all icons except
applications.

  </para>
</sect1>

<sect1>
  <title>Action window options</title>
  <para>

You can choose to start some operations automatically, without waiting
for you to click on <guibutton>Quiet</guibutton>.
Select each operation that you want to
auto-start here. You can also set the default state for each of the
options that appear inside action windows.

  </para>
</sect1>

<sect1>
  <title>Toolbar options</title>
  <para>

<itemizedlist>
<listitem><para> <guilabel>Unshade the tools you want:</guilabel> allows you to set which tools
should appear on the toolbar. Click on the buttons below to shade and unshade
them &mdash; shaded tools will not be shown on filer window toolbars.
</para></listitem>

<listitem><para> <guilabel>Toolbar type</guilabel> allows you to choose what
kind of toolbars you want.
<guimenuitem>None</guimenuitem> means that windows will not have a
toolbar,
<guimenuitem>Normal</guimenuitem> provides a small bar of icons, and
<guimenuitem>Large</guimenuitem> displays larger buttons, with textual labels.
</para></listitem>

<listitem><para> <guilabel>Show totals of items</guilabel> shows the number of items displayed in a filer
window, as well as the number of hidden items (if any) on the toolbar.
When there's a selection, it shows the number of selected items and
their combined size (excluding directories).
</para></listitem>

</itemizedlist>

See the <xref linkend="Toolbar"/> section for details.

  </para>
</sect1>

<sect1>
  <title>Filer window options</title>
  <para>

<itemizedlist>
<listitem><para><guilabel>Automatically resize filer windows</guilabel> can be
used to control when windows are automatically resized:

        <itemizedlist>
        <listitem><para><guilabel>...never</guilabel>
        turns off auto-resizing. Windows must be
        resized manually.
        </para></listitem>

        <listitem><para><guilabel>...when changing the display style</guilabel>
        will resize the
        window automatically when you change the icon size or the type of
        details to be displayed.
        </para></listitem>

        <listitem><para><guilabel>...always</guilabel>
        causes the window to resize whenever it
        seems useful (that is, when changing to a different directory or when
        switching between display styles).
        </para></listitem>
        </itemizedlist>

</para></listitem>

<listitem><para> <guilabel>Window size limit</guilabel> sets the largest size
(as a percentage of the screen size) that the auto-resizer will resize windows
to.
</para></listitem>

<listitem><para> <guilabel>Unique windows</guilabel> prevents you from having
two windows showing the same directory. Opening a second view onto a directory
closes the first.
</para></listitem>

</itemizedlist>

The next two options control what happens when you press <keycap>Tab</keycap>
in the path entry minibuffer:

<itemizedlist>

<listitem><para> <guilabel>Beep if Tab-completion fails</guilabel> &mdash; beep
if there is no match, or there are several possible completions, each starting
differently.
</para></listitem>

<listitem><para> <guilabel>Beep if there are several matches</guilabel> &mdash;
beep if there are several matches, even though some letters were added.
</para></listitem>

</itemizedlist>

  </para>
</sect1>

<sect1>
  <title>Drag-And-Drop options</title>
  <para>

<itemizedlist>
<listitem><para><application>ROX-Filer</application> uses the standard XDND protocol for drag-and-drop. This
protocol recommends that URIs should contain the hostname of the computer
that the resource is on so that the program receiving the data can
determine whether it can get the data directly or whether it must
go via the X-server. However, many older programs (particularly GNOME
applications) get confused by the hostname and fail to load the data
correctly. If <guilabel>Don't use hostnames</guilabel> is on then the hostname part is
omitted and <application>ROX-Filer</application> will work with these applications BUT you can't
drag data to a program running on a different machine.
</para></listitem>

<listitem><para><guilabel>Allow dragging to icons in filer windows</guilabel> controls what happens when
you drop files onto icons in filer windows. If on then drops onto
directories will save the data inside the directory, while dropping
onto programs will invoke the program on that data. If off then drops
anywhere inside a filer window act like drops onto the window background
&mdash; that is, the data will be saved into the directory being displayed.
</para></listitem>

<listitem><para><guilabel>Dragging files with the middle mouse button...</guilabel>
you can choose whether this displays a menu (like <keycap>Alt</keycap> dragging) or moves the
files (like <keycap>Shift</keycap> dragging).
</para></listitem>

<listitem><para><guilabel>Directories spring open</guilabel> controls what happens when you hold a file
over a directory while dragging it. If on, the directory will `spring
open' after a short pause, allowing you to navigate to any directory
during a drag. You can also hold the pointer over the Home and Up
buttons on the toolbar for a similar effect. You need to have the
previous option enabled for this to have any effect on files displayed
in a directory.
</para></listitem>

<listitem><para><guilabel>Spring delay</guilabel> sets how long, in thousanths of a second, the filer
will wait before spring opening a directory as described above. If
the above option is turned off, then this has no effect.
</para></listitem>

</itemizedlist>

  </para>
</sect1>

<sect1>
  <title>Menu options</title>
  <para>

<itemizedlist>

<listitem><para><guilabel>Xterm here program</guilabel> is the command used when you choose
<guimenuitem>Xterm here</guimenuitem> from the menu.
You can replace it with another command such as
<command>gnome-terminal</command>, <command>konsole</command>, or anything
else.</para></listitem>

<listitem><para><guilabel>Size of icons in menus</guilabel> controls the size of the
icons in the <guimenuitem>Send To</guimenuitem> and <guimenuitem>New</guimenuitem> menus.
</para></listitem>

</itemizedlist>

  </para>
</sect1>

<sect1>
  <title>Mouse bindings</title>
  <para>

<itemizedlist>
<listitem><para> <guilabel>New window on button 1</guilabel> swaps the actions of the two non-menu buttons
when opening directories. This is provided for people who are used
to the RISC OS mouse bindings.
</para></listitem>

<listitem><para> <guilabel>Menu on button 2</guilabel> swaps the actions of buttons 2 and 3 so that the
middle button brings up the menus. This is provided for people who
are used to the RISC OS mouse bindings.
</para></listitem>

<listitem><para> <guilabel>Single-click navigation</guilabel> means that clicking on a file or directory
will open it. If off, clicking on files selects them instead &mdash; you
must double click on a file to open it.
</para></listitem>
</itemizedlist>

As an alternative to using the options window to put menu on button-2,
some people prefer to use the command <command>xmodmap -e "pointer
= 1 3 2"</command>, which makes the right mouse button button-2 and
the middle one button-3 (this affects all programs, not just
<application>ROX-Filer</application>).

  </para>
</sect1>
</chapter>

<chapter id="types">
  <title>Filetypes</title>
  <para>

All files have a MIME type in the form <emphasis>text/plain</emphasis>. Here,
<emphasis>text</emphasis> is the <emphasis>media type</emphasis> and
<emphasis>plain</emphasis> is the <emphasis>sub-type</emphasis>.
  </para><para>
<application>ROX-Filer</application> uses a file's name to decide what its MIME
type is, and then uses the MIME type to decide what icon to give it and what
program to use when you open the file.
  </para>

<sect1>
  <title><anchor id="RunAction" xreflabel="the Set Run Action box"/>
    The run action box
  </title>
  <para>

This box appears when you choose <guimenuitem>Set Run Action...</guimenuitem>
from the File menu, and is used to set which application is loaded when you click
on a file.
  </para><para>
For example, let's say you want to set things up so that opening a
<filename>.gif</filename> file loads it into the Gimp.
First, right-click over a gif image to open the menu and choose
<guimenuitem>Set Run Action...</guimenuitem> from the
<guimenuitem>File</guimenuitem> submenu.
Then, you have a choice of two methods to set the run action:
  </para>

  <sect2><title>Setting the run action by drag-and-drop</title>
    <para>
Drag the Gimp (from a filer window, a panel or the pinboard) onto
the area marked <guilabel>Drop a suitable application here</guilabel>.
From now on, clicking on a GIF file will load it into the Gimp.
    </para>
  </sect2>

  <sect2><title>Setting the run action by entering a shell command</title>
    <para>
Type: <userinput>gimp "$1"</userinput>
into the box labelled <guilabel>Enter a shell command</guilabel> and press
<keycap>Return</keycap>. <userinput>$1</userinput>
will be replaced by the name of the file you click on when this command
is used. As before, clicking on any GIF image will now load it into
the Gimp.
    </para>
  </sect2>

  <sect2><title>Setting the default media-type handlers</title>
    <para>
Whichever method you use to set the action you have the choice of
setting the run action just for that type, or setting the default
for all files with that media-type which don't already have a specific
action.
    </para><para>
Since the Gimp can load many types of image, it makes sense
to select the <guilabel>Set default for all `image/&lt;anything&gt;'</guilabel>
option so you don't have to do it again for image/jpeg files and so on. However,
this only affects types that don't already have a specific action
(ie, those that would have brought up an error box if you tried to
open them).
    </para>
  </sect2>
</sect1>

<sect1>
<title><anchor id="SetIcon" xreflabel="the Set Icon box"/>
    The Set Icon box
  </title>
  <para>

This box appears when you choose <guimenuitem>Set Icon...</guimenuitem>
from the File menu, and is used to set which image to use to represent
the file.
  </para><para>
It works much like the Set Run Action box described above, except that
you may specifiy an icon for one file individually (by name) as well as
for all files of a particular type.
  </para><para>
The directory icon inside the <guilabel>Drop an icon here</guilabel>
area allows you to quickly get to a directory from which you are already
using one or more icons.
  </para>
</sect1>
  
<sect1>
  <title>How filetypes are stored</title>
  <para>

<application>ROX-Filer</application> uses three sub-directories in your Choices
directory for filetypes:

<variablelist>

<varlistentry><term><filename>MIME-info</filename></term><listitem><para>
contains files which specify what the MIME types for files
should be, based on their extentions. All the files in all the
<filename>MIME-info</filename> directories are scanned when the filer loads.
<application>ROX-Filer</application> comes with a file containing many such
rules &mdash; this is installed into the <filename>MIME-info</filename>
directory by the rox-base package.
  </para><para>
Many applications now come with a file called
<filename>something.mime</filename>; copy these files into your
<filename>MIME-info</filename> directory to make
<application>ROX-Filer</application> automatically recognise the new extensions.
Note that the filer must be restarted for the new files to be read.
</para></listitem></varlistentry>

<varlistentry><term><filename>MIME-types</filename></term><listitem><para>
contains symlinks, one for each MIME type, which point
to programs that can handle files of that type. To set what program
is run when you click on the file you should normally use the <guimenuitem>Set
Run Action...</guimenuitem> feature (see the <xref linkend="RunAction"/> section).
However, you can also set the actions manually &mdash; for example, to make
opening an HTML file load it into Netscape:

<orderedlist>
<listitem><para>
Find the Netscape application and go to <guimenuitem>Link...</guimenuitem>
on the menu.
</para></listitem>

<listitem><para>
Enter <userinput>text_html</userinput> as the name for the link and drag the
icon from the Link box into the <filename>MIME-types</filename> directory.
</para></listitem>

</orderedlist>

You can also put actual programs in here as well as links if you want
to.
</para></listitem></varlistentry>

<varlistentry><term><filename>MIME-icons</filename></term><listitem><para>
contains the images used to display each type of file.
So the filer will try to display an HTML file using the icon
<filename>MIME-icons/text_html.xpm</filename>.
</para></listitem></varlistentry>

</variablelist>

In both <filename>MIME-types</filename> and <filename>MIME-icons</filename>
directories you can also provide default actions/images for each media type.
For example, if <filename>text_html</filename> isn't found then the filer
will try simply using <filename>text</filename>.

  </para>
</sect1>
</chapter>

<chapter id="appdirs">
  <title><anchor id="AppDir" xreflabel="Application directories"/>
    Application directories
  </title>
  <para>
An application directory is a directory which can be run as an application.
It contains all the resources of an application &mdash; source code, binaries,
documentation and so on. Keeping everything in one place make installation
and uninstallation much easier for users. You can also keep multiple
versions of a program by simply having several application directories.
You may move and rename them as you please. Application directories
make programs easier to use and install.
  </para><para>
  <!-- Note to translaters: Changed the wording here a bit from 1.1.7 -->
They're more secure too, because you can compile an application as a user and
then simply copy it as root. Since you don't have to run an install script
you are free from the danger of running untrusted code as root. All you have
to watch out for is setuid binaries.
  </para><para>

The following files are treated as special by
<application>ROX-Filer</application>:

<itemizedlist>

<listitem><para>
<filename>AppRun</filename>
is executed when you click on the directory &mdash; make sure
it is executable (use the Permissions box)!
</para></listitem>

<listitem><para>
<filename>.DirIcon.png</filename>
is the image used to represent the directory (this works even if
there is no <filename>AppRun</filename>).
</para></listitem>

<listitem><para>
<filename>Help</filename>
is the directory to be opened when you choose <guimenuitem>Help</guimenuitem>
from the File menu.
</para></listitem>

<listitem><para>
<filename>AppInfo.xml</filename>
contains extra information about an application (see below).
</para></listitem>

<listitem><para>
<filename>AppIcon.xpm</filename>
is used if <filename>.DirIcon.png</filename> is missing (for backwards
compatibility).
</para></listitem>

</itemizedlist>

Have a look at the <filename>ROX-Filer</filename> application directory for a
full example.

  </para>

<note><para>For security reasons, an application directory must have the
same owner as the <filename>AppRun</filename> file inside.</para></note>

<sect1>
  <title>The AppInfo file</title>
  <para>

<filename>AppInfo.xml</filename> is an XML file with the following structure
(any elements may be omitted, and the file itself is optional):

<screen>
&lt;?xml version="1.0"?&gt;
&lt;AppInfo&gt;
  &lt;Summary&gt;A graphical file manager&lt;/Summary&gt;
  &lt;About&gt;
    &lt;Purpose&gt;File manager&lt;/Purpose&gt;
    &lt;Version&gt;1.1.3 (07-May-2001)&lt;/Version&gt;
    &lt;Authors&gt;Thomas Leonard and others&lt;/Authors&gt;
    &lt;License&gt;GNU General Public License&lt;/License&gt;
    &lt;Homepage&gt;http://rox.sourceforge.net&lt;/Homepage&gt;
  &lt;/About&gt;
  &lt;AppMenu&gt;
    &lt;Item label="Enable pinboard" option="-p=Default"/&gt;
    &lt;Item label="Disable pinboard" option="-p="/&gt;
  &lt;/AppMenu&gt;
&lt;/AppInfo&gt;
</screen>

<itemizedlist>

<listitem><para>
<userinput>Summary</userinput>
is displayed in a tooltip when the mouse is held over the application.
</para></listitem>

<listitem><para>
<userinput>About</userinput>
contains a list of fields which are shown in the `File Info'
box for the application (any element names may be used, but the above
are suggested).
</para></listitem>

<listitem><para>
<userinput>AppMenu</userinput>
is a list of extra menu items to display for the application.
When one is chosen, <filename>AppRun</filename> is called with
<userinput>option</userinput> as its only argument. You can nest
AppMenus inside other AppMenus.
</para></listitem>

</itemizedlist>

  </para>
</sect1>
</chapter>

<chapter id="i18n">
  <title>Internationalisation</title>
  <para>

  </para>

<sect1>
  <title><anchor id="LANG" xreflabel="Translations"/>
    Selecting a translation
  </title>
  <para>

<application>ROX-Filer</application> is able to translate many of its messages,
provided suitable translation files are provided: 

<orderedlist>
<listitem><para>Open the Options box from the menu,</para></listitem>
<listitem><para>Select a language from the menu at the top,</para></listitem>
<listitem><para>Click on <guibutton>Save</guibutton> and restart the filer
for the new setting to take full effect.</para></listitem>
</orderedlist>

  </para>
</sect1>

<sect1>
  <title>Creating a new translation</title>
  <para>

<orderedlist>
<listitem><para>Go into the <filename>src</filename> directory and create
the file <filename>messages.pot</filename>:

<screen>
$ cd ROX-Filer/src
$ make messages.pot
</screen>

</para></listitem>

<listitem><para>Copy the file into the <filename>po</filename>
subdirectory under <filename>src</filename> as
<filename>&lt;name&gt;.po</filename>. Eg, if your
language is referred to as `ml' (`my language'):

<screen>$ cp messages.pot po/ml.po</screen>
</para></listitem>

<listitem><para>Load the copy into a text editor.</para></listitem>

<listitem><para>Fill in the translations, which are all blank to start with.
</para></listitem>

<listitem><para>Run the <filename>make-mo</filename> script to create the
binary file which <application>ROX-Filer</application> can use.
You will need the GNU gettext package for this.
If you don't have it then just send me the <filename>.po</filename> file
and I'll convert it for you.

<screen>
$ cd ROX-Filer/src/po
$ ./make-mo ml
Created file ../../Messages/ml.gmo OK
</screen>
</para></listitem>

<listitem><para>Edit <filename>ROX-Filer/Options.xml</filename> so that
your language is listed, restart the filer and select it from the Options box
(see the <xref linkend="LANG"/> section).
</para></listitem>

<listitem><para>Submit the <filename>.po</filename> file to me so that I
can include it in future releases of the filer.
</para></listitem>

</orderedlist>
  </para>
</sect1>

<sect1>
  <title>Updating an existing translation</title>
  <para>

<orderedlist>
<listitem><para>Go into the directory containing the <filename>.po</filename>
files and run the <filename>update-po</filename> script.
This checks the source code for new and changed strings and updates all
the translation files.

<screen>
$ cd ROX-Filer/src/po
$ ./update-po
</screen>
</para></listitem>

<listitem><para>Edit the file by hand as before, filling in the new blanks
and updating out-of-date translations.
Look out for <computeroutput>fuzzy</computeroutput> entries where
<command>update-po</command> has made a guess; check it's correct and
remove the <computeroutput>fuzzy</computeroutput> line.
</para></listitem>

<listitem><para>Run <command>make-mo</command> as before.</para></listitem>

<listitem><para>Submit the updated file to me.</para></listitem>

</orderedlist>

See the <command>gettext</command> info page for more instructions on creating
a translation.

  </para>
</sect1>
</chapter>

<chapter id="hacking">
  <title>Hacking</title>
  <para>
This is a quick start guide for people who want to modify the source
code. If you make useful changes or fix bugs, please send patches
to me or to the mailing list. Tell me which version you're using!
  </para>

<sect1>
  <title>Compiling</title>
  <para>
The first time you compile the program you need to do <command>AppRun
--compile</command>, but in future you only need to run <command>make</command>
in the <filename>src</filename> directory when you change the
<filename>.c</filename> and <filename>.h</filename> files.
You might want to run <command>make depend</command> too.
  </para>
</sect1>

<sect1>
  <title>Creating and applying patches</title>
  <para>
When people make small modifications to the sources they will often
distribute them as <emphasis>patch files</emphasis> &mdash; usually on the
mailing list.

To apply a patch, go into the <filename>src</filename> directory and run
<command>patch</command> with the patch file. Then recompile, like this:

<screen>
$ cd ROX-Filer/src
$ patch &lt; patchfile
$ ../AppRun --compile
</screen>

You can remove the patch by simply repeating the above sequence &mdash;
<command>patch</command> will detect that the patch is already applied
and offer to remove it.
  </para><para>
To create a patch you should first get the latest version of the filer
from CVS (instructions on using CVS can be found on the web-site).
Modify the program as you please. Create the patch using
<command>cvs diff</command> from the appropriate directory:

<screen>
$ cvs diff -c &gt; my_patch
</screen>

This creates a human&ndash; and machine-readable patch file. Submit this
to the mailing list. The are many reasons for posting patches rather
that the modified files:

<itemizedlist>
<listitem><para>They are smaller, and hence shouldn't bounce.
They are also quicker to download for people with slow connections.
</para></listitem>

<listitem><para>People can see what they're getting into before applying them!
</para></listitem>

<listitem><para>Patches can (usually) be applied to slightly modified
versions of the sources. This means that people can apply several patches
without each new one overwriting the others.
</para></listitem>

</itemizedlist>

  </para>
</sect1>

<sect1>
  <title>Autoconf</title>
  <para>
Here's a quick explanation of the autoconf system in case you haven't
used it before. See <command>info autoconf</command> for full details.
  </para><para>
There's a file called <filename>configure.in</filename> which contains
various tests (<command>info autoconf</command>).
You run <command>autoconf</command> and it reads through the file
and generates a shell script to perform the tests, saving it as
<filename>configure</filename>.
<filename>configure</filename> is normally distributed with the program because
not everyone has autoconf.
  </para><para>
You then run <filename>configure</filename> (in fact, let the
<filename>AppRun</filename> script do it because
it passes it some arguments), which performs all the tests. It reads
in <filename>Makefile.in</filename> and <filename>config.h.in</filename>
and fills in the missing values with the test results to produce
<filename>Makefile</filename> and <filename>config.h</filename>.
  </para><para>
You run <command>make</command>, which creates <filename>.o</filename>
files from the <filename>.c</filename> files and links to produce
<filename>ROX-Filer</filename>.
  </para>
</sect1>

<sect1><title>Data-structures</title>
  <para>
The diagram below shows some of the major structures found in the
filer and the relationships between them.
  </para>
<mediaobject>
  <imageobject>
    <imagedata align="center" format="PNG" fileref="../Structs.png"/>
  </imageobject>
  <textobject><para>Can't display image.</para></textobject>
</mediaobject>

  <para>
To summarise, each window has its own <classname>FilerWindow</classname>
structure.
  </para><para>
This structure has pointers to a <classname>Collection</classname>
(which is the widget which actually displays the files) and to a
<classname>Directory</classname>, which is used to cache the directory
contents.
  </para><para>
Both <classname>Collection</classname> and
<classname>Directory</classname> have pointers to (the same)
<classname>DirItem</classname>s, each of which corresponds to one filesystem
object.
  </para><para>
Several <classname>FilerWindow</classname>s may share the same
<classname>Directory</classname>.
  </para><para>
While scanning is in progress the <classname>Directory</classname>
keeps a list of the new items it has found
(<emphasis>new_items</emphasis>) and the items which have changed in some way
(<emphasis>up_items</emphasis>). It periodically notifies the filer window of
the changes-so-far by calling all the functions in the
<emphasis>users</emphasis> list (use <function>attach()</function>
and <function>detach()</function> to add and remove functions to or from
the list).
  </para>
</sect1>
</chapter>

<appendix id="manpage"><title>Manual page</title>

<refentry id="rox">

<refmeta>
<refentrytitle>ROX</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>ROX-Filer</refname>
<refpurpose>a simple graphical file manager</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>rox</command>
<arg choice="opt" rep="repeat"><option>OPTION</option></arg>
<arg choice="opt" rep="repeat">FILE</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>DESCRIPTION</title>
<para>
ROX-Filer is a simple and easy to use graphical file manager for X11, the
windowing system used on Unix and Unix-like operating systems.
</para><para>
It is also the core component of the ROX Desktop:
<ulink url="http://rox.sourceforge.net"/>
</para><para>
Invoking <command>rox</command> opens each directory or file listed,
or the current working directory if no arguments are given.
</para>
</refsect1>

<refsect1><title>COMMAND-LINE OPTIONS</title>
  <para>
  <variablelist>

    <varlistentry><term><option>-b</option></term><term><option>--bottom=PANEL</option></term>
<listitem><para>open PANEL as a bottom-edge panel.
</para></listitem></varlistentry>

<varlistentry><term><option>-c</option></term><term><option>--client-id=ID</option></term>
<listitem><para>used for session management.
</para></listitem></varlistentry>

<varlistentry><term><option>-d</option></term><term><option>--dir=DIR</option></term>
<listitem><para>open DIR as directory (not as an application, even if it looks
like one).
</para></listitem></varlistentry>

<varlistentry><term><option>-D</option></term><term><option>--close=DIR</option></term>
<listitem><para>close DIR and all its subdirectories.
</para></listitem></varlistentry>

<varlistentry><term><option>-h</option></term><term><option>--help</option></term>
<listitem><para>display help about the various options.
</para></listitem></varlistentry>

<varlistentry><term><option>-l</option></term><term><option>--left=PANEL</option></term>
<listitem><para>open PANEL as a left-edge panel.
</para></listitem></varlistentry>

<varlistentry><term><option>-m</option></term><term><option>--mime-type=FILE</option></term>
<listitem><para>print MIME type of FILE and exit.
</para></listitem></varlistentry>

<varlistentry><term><option>-n</option></term><term><option>--new</option></term>
<listitem><para>start a new filer, even if one already seems to be running. This also prevents the filer from forking (running in the background), which is useful for debugging.
</para></listitem></varlistentry>

<varlistentry><term><option>-o</option></term><term><option>--override</option></term>
<listitem><para>override window manager control of panels.
</para></listitem></varlistentry>

<varlistentry><term><option>-p</option></term><term><option>--pinboard=PIN</option></term>
<listitem><para>use pinboard PIN as the pinboard.
</para></listitem></varlistentry>

<varlistentry><term><option>-r</option></term><term><option>--right=PANEL</option></term>
<listitem><para>open PANEL as a right-edge panel.
</para></listitem></varlistentry>

<varlistentry><term><option>-R</option></term><term><option>--RPC</option></term>
<listitem><para>read and invoke SOAP RPC from standard input (see <xref linkend="soap"/>).
</para></listitem></varlistentry>

<varlistentry><term><option>-s</option></term><term><option>--show=FILE</option></term>
<listitem><para>open a directory showing FILE.
</para></listitem></varlistentry>

<varlistentry><term><option>-t</option></term><term><option>--top=PANEL</option></term>
<listitem><para>open PANEL as a top-edge panel.
</para></listitem></varlistentry>

<varlistentry><term><option>-u</option></term><term><option>--user</option></term>
<listitem><para>show user name in each window.
</para></listitem></varlistentry>

<varlistentry><term><option>-v</option></term><term><option>--version</option></term>
<listitem><para>display the version information and exit.
</para></listitem></varlistentry>

<varlistentry><term><option>-x</option></term><term><option>--examine=FILE</option></term>
<listitem><para>FILE has changed; re-examine it.
</para></listitem></varlistentry>

  </variablelist>
</para>
</refsect1>

<refsect1><title>NOTES</title>
        <para>
The main documentation for ROX-Filer is available by choosing
<guimenuitem>Show ROX-Filer Help</guimenuitem> from the
popup menu, or by clicking on the <guibutton>i</guibutton>
toolbar icon.
        </para>
</refsect1>

<refsect1><title>LICENSE</title>
        <para>Copyright (C) 2001 Thomas Leonard.
        </para><para>
You may redistribute copies of ROX-Filer under the terms of the GNU General
Public License.
        </para>
</refsect1>

<refsect1><title>BUGS</title>
        <para>
                Report bugs to <email>tal197@users.sourceforge.net</email>.
        </para>
</refsect1>

<refsect1><title>AUTHORS</title>
<para>
ROX-Filer was created by Thomas Leonard, with help from:
</para><para>
<simplelist columns='4'>
        <member>Christopher Arndt</member>
        <member>Jens Askengren</member>
        <member>Liav Asseraf</member>
        <member>Andrzej Borsuk</member>
        <member>Richard Boulton</member>
        <member>Simon Britnell</member>
        <member>Arnaud Calvo</member>
        <member>Andrew Clover</member>
        <member>Fabien Coutant</member>
        <member>Dmitry Elfimov</member>
        <member>Mattias Engdegard</member>
        <member>Andrew Flegg</member>
        <member>Alex Holden</member>
        <member>Jasper Huijsmans</member>
        <member>Bernard Jungen</member>
        <member>James Kermode</member>
        <member>Vincent Ledda</member>
        <member>Vincent Lefevre</member>
        <member>Victor Liu See-le</member>
        <member>Anders Lundmark</member>
        <member>Jose Romildo Malaquias</member>
        <member>Denis Manente</member>
        <member>Andras Mohari</member>
        <member>Christiansen Merel</member>
        <member>Jimmy Olgeni</member>
        <member>Andy Piper</member>
        <member>Michel Alexandre Salim</member>
        <member>Chris Sawer</member>
        <member>Taras</member>
        <member>Simon Truss</member>
        <member>Jan Wagemakers</member>
        <member>Stephen Watson</member>
        <member>Andre Wyrwa</member>
        <member>Diego Zamboni</member>
</simplelist>
</para><para>
and many others; the <filename>Changes</filename> file contains more
detailed information!
</para>
</refsect1>

</refentry>
</appendix>

<appendix id="soap"><title>SOAP RPC</title>

<para>When the filer starts you can use command-line options to control its behaviour.
As an alternative to this, the filer allows you to specify operation as a
<citation>SOAP</citation> RPC format message. In fact, if you use the command-line options,
the filer converts to SOAP RPC internally.
</para>

<para>Currently, there is no advantage to this method, but in future this may provide
a more flexible way to interface to the filer.</para>

<para>All SOAP RPC messages are passed on standard input, like this:

<screen>
$ rox --RPC &lt;&lt; EOF
&lt;?xml version="1.0"?&gt;
&lt;env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope"&gt;
  &lt;env:Body xmlns="http://rox.sourceforge.net/SOAP/ROX-Filer"&gt;
    &lt;Panel&gt;
      &lt;Name&gt;Default&lt;/Name&gt;
      &lt;Side&gt;Bottom&lt;/Side&gt;
    &lt;/Panel&gt;
  &lt;/env:Body&gt;
&lt;/env:Envelope&gt;
EOF
</screen>

The following methods are recognised:</para>

<itemizedlist>

<listitem><para><function>CloseDir(Filename)</function>
Close directory Filename and all its subdirectories.
</para></listitem>

<listitem><para><function>Examine(Filename)</function>
Filename may have changed &mdash; check it and update the display.
</para></listitem>

<listitem><para><function>OpenDir(Filename)</function>
Open a window showing directory Filename.
</para></listitem>

<listitem><para><function>Panel(Name, Side)</function>
Open the panel named Name on screen side Side (Top|Bottom|Left|Right).
Name can be a name in Choices (eg, `MyPanel') or a full pathname.
</para></listitem>

<listitem><para><function>Pinboard(Name)</function>
Display pinboard Name on the desktop background.
Name can be a name in Choices (eg, `MyPinboard') or a full pathname.
</para></listitem>

<listitem><para><function>Run(Filename)</function>
Run Filename as if it was clicked on in the filer.
</para></listitem>

<listitem><para><function>Show(Directory, Leafname)</function>
Open Directory and flash the file Leafname inside it.
</para></listitem>

</itemizedlist>

</appendix>

<bibliography>
  <title>References</title>

<bibliomixed>
  <abbrev>ROX</abbrev><citetitle>The ROX desktop,
  <ulink url="http://rox.sourceforge.net"/></citetitle>
</bibliomixed>

<bibliomixed>
  <abbrev>RISC OS</abbrev><citetitle>RISC OS,
  <ulink url="http://www.riscos.com"/></citetitle>
</bibliomixed>

<bibliomixed>
  <abbrev>GTK+</abbrev><citetitle>GTK+ Toolkit,
  <ulink url="http://www.gtk.org"/></citetitle>
</bibliomixed>

<bibliomixed>
  <abbrev>GNOME</abbrev><citetitle>The GNOME desktop,
  <ulink url="http://www.gnome.org"/></citetitle>
</bibliomixed>

<bibliomixed>
  <abbrev>DND</abbrev><citetitle>The Drag and Drop protocol,
  <ulink url="http://www.newplanetsoftware.com/xdnd/"/></citetitle>
</bibliomixed>

<bibliomixed>
  <abbrev>XDS</abbrev><citetitle>The X Direct Save protocol,
  <ulink url="http://www.newplanetsoftware.com/xds/"/></citetitle>
</bibliomixed>

<bibliomixed>
  <abbrev>Choices</abbrev><citetitle>The ROX Choices system,
  <ulink url="http://rox.sourceforge.net/choices.php3"/></citetitle>
</bibliomixed>

<bibliomixed>
  <abbrev>enlightenment</abbrev><citetitle>Enlightenment,
  <ulink url="http://www.enlightenment.org"/></citetitle>
</bibliomixed>

<bibliomixed>
  <abbrev>AVFS</abbrev><citetitle>AVFS - A Virtual File System,
  <ulink url="http://sourceforge.net/projects/avf/"/></citetitle>
</bibliomixed>

<bibliomixed>
  <abbrev>SOAP</abbrev><citetitle>Simple Object Access Protocol (SOAP) 1.1
  <ulink url="http://www.w3.org/TR/SOAP/"/></citetitle>
</bibliomixed>

</bibliography>

</book>