r4085: Updated French manual translation (Arnaud Calvo).
[rox-filer.git] / ROX-Filer / src / Docs / Manual.xml
blobc6232c3b26b5e52226e44e0cca8bb80e8573b9fa
1 <?xml version="1.0" standalone="no"?>
2 <?xml-stylesheet href="to_html.xsl" type="text/xml"?>
3 <!-- vim: set sw=1 sts=1 : -->
4 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
5 "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd">
7 <book>
8  <bookinfo>
9   <title>
10    ROX-Filer User Manual
11    <ulink url="http://rox.sourceforge.net"/>
12   </title>
13   <author>
14    <firstname>Thomas</firstname><surname>Leonard</surname>
15   </author>
16   <copyright><year>2005</year><holder>Thomas Leonard</holder></copyright>
17   <legalnotice>
18    <title>Conditions</title>
19    <para>
20     This program is free software; you can redistribute it and/or modify
21     it under the terms of the GNU General Public License as published
22     by the Free Software Foundation; either version 2 of the License,
23     or (at your option) any later version.
25     This program is distributed in the hope that it will be useful, but
26     WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
27     or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
28     for more details.
30     You should have received a copy of the GNU General Public License
31     along with this program; if not, write to the Free Software Foundation,
32     Inc., 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA.
33    </para>
34   </legalnotice>
36   <abstract>
37    <para>
38     <application>ROX-Filer</application> is a graphical file manger for the X
39     Window System. Its user interface is based on the RISC OS filer and it
40     supports similar features such as application directories and drag-and-drop
41     loading and saving of files. The filer can also act as a pinboard, allowing
42     you to pin frequently used files onto the desktop background.
43    </para>
44   </abstract>
45  </bookinfo>
47  <chapter id="intro">
48   <title>Introduction</title>
49   <para>
50    <application>ROX-Filer</application> is a simple and easy to use graphical
51    file manager for X11 &mdash; the windowing system used on Unix and Unix-like
52    operating systems.  It is also the core component of the ROX Desktop
53    <citation>ROX</citation>. Many of the filer's features were inspired by RISC
54    OS <citation>RISC OS</citation>. `ROX' stands for `RISC OS&ndash;On&ndash;X'.
55   </para>
57   <sect1>
58    <title>Features</title>
59    <para>
61     <variablelist>
63      <varlistentry><term>XDND</term>
64       <listitem><para>
65         A common drag-and-drop protocol used, for example, by the GNOME
66         desktop<citation>GNOME</citation>. This allows data to be loaded into an
67         application by dragging it from a filer window to a program. The full
68         specification is given in <citation>DND</citation>.
69      </para></listitem></varlistentry>
71      <varlistentry><term>XDS</term>
72       <listitem><para>
73         An extension to XDND that allows applications to save data by
74         dragging an icon back to a filer window. The full specification is given in
75         <citation>XDS</citation>.
76      </para></listitem></varlistentry>
78      <varlistentry><term>Basedir spec</term>
79       <listitem><para>
80         A simple, but flexible, system for managing user choices. By default, choices are
81         saved under <filename>~/.config</filename>. However, you can change this by setting
82         the <envar>XDG_CONFIG_HOME</envar> environment variable. See
83         <citation>BaseDir</citation> for details.
84      </para></listitem></varlistentry>
86      <varlistentry><term>Application directories</term>
87       <listitem><para>
88         Self contained relocatable applications, where installation is as simple as
89         copying it to where you want it and uninstalling it is just a matter of
90         deleting a directory. Described later in this documentation.
91      </para></listitem></varlistentry>
93      <varlistentry><term>Thumbnails</term>
94       <listitem><para>
95         The filer can be made to display image files by using the image itself for the
96         icon, instead of a generic `this-is-an-image' icon. Very useful for organising
97         a directory full of photos! See <citation>Thumbs</citation> for details.
98      </para></listitem></varlistentry>
100      <varlistentry><term>Shared MIME Info Database</term>
101       <listitem><para>
102         In the past, each desktop had its own database of rules for determining the
103         type of files. The Shared MIME Info Database<citation>SharedMIME</citation>
104         unifies these into a single system shared by all desktops.
105      </para></listitem></varlistentry>
107      <varlistentry><term>Icon Themes</term>
108       <listitem><para>
109         Collections of file icons, called themes, can be installed (eg, to
110         <filename>~/.icons</filename>). You can switch between themes in
111         the Options box. Once other desktops support this fully, themes
112         will be sharable between desktops. See <citation>IconTheme</citation> for details.
113      </para></listitem></varlistentry>
115      <varlistentry><term>DNotify support (Linux only)</term>
116       <listitem><para>
117         If used with a recent Linux kernel (2.4.x series), the filer will notice changes
118         to directories automatically. On other systems, directories will update when the
119         pointer is moved over them.
120      </para></listitem></varlistentry>
122     </variablelist>
124    </para>
125   </sect1>
127  </chapter>
129  <chapter id="invoking">
130   <title>Invoking</title>
131   <para>
132    You should be able to start the filer by simply running the <userinput>rox</userinput>
133    command, by typing it at a shell prompt or otherwise. If the filer isn't installed yet,
134    consult <xref linkend="compiling"/>.
135   </para>
136   <para>
137    By default, <application>ROX-Filer</application> will start by displaying
138    the current directory.  You can get it to display other directories instead
139    by listing them after the command:
141    <screen>$ rox /home /usr /usr/local</screen>
143    You can also use it to open files, like this:
145    <screen>$ rox README</screen>
147    The filer supports various options; use <option>-h</option> for a list.
148    All options have long and short forms (eg <option>-h</option> and
149    <option>--help</option>) &mdash; although on some systems you can only use the
150    short versions.
151    </para><para>
152    Note that if the same version of the filer is already running on this
153    machine then, by default, it will be used to open the directories.
154    </para><para>
155    For a complete list of command-line options, see <xref linkend="manpage"/>
156   </para>
158   <sect1>
159    <title><anchor id="run_pin" xreflabel="Pinboard support"/>Pinboard support</title>
160    <para>
162     If you want the filer to manage your desktop background then you use
163     the <option>--pinboard</option> option and supply a name for the pinboard,
164     eg:
166     <screen>$ rox --pinboard=MyPinboard</screen>
168     The pinboard configuration is saved in
169     <filename>~/.config/rox.sourceforge.net/ROX-Filer/pb_MyPinboard</filename>
170     as soon as you change it in some way (for example, by dropping a file
171     onto the background). You can have as many pinboards as you like and
172     switch between them by running rox again, eg:
174     <screen>$ rox --pinboard=MyOtherPinboard</screen>
176     To turn off the pinboard again, set the name to an empty string:
178     <screen>$ rox --pinboard=</screen>
180     See the <xref linkend="winman"/> if you have trouble getting the icons to
181     display correctly. The pinboard may also be turned on and off by locating
182     <filename>ROX-Filer</filename> in a filer window and choosing <guimenuitem>Enable
183     pinboard</guimenuitem> or <guimenuitem>Disable pinboard</guimenuitem> from the menu.</para>
184   </sect1>
186   <sect1>
187    <title><anchor id="run_pan" xreflabel="Panel support"/>Panels</title>
188    <para>
190     Panels work just like the pinboard, except that they run along the edge of the screen.
191     To create a panel:
193     <screen>$ rox -b=MyPanel</screen>
195     The panel should be displayed in a window without a title bar. If
196     this does not work then see the <xref linkend="winman"/> for some ideas.
197     You can drag files onto either side of the panel to add them. Panel icons
198     can be repositioned by dragging them with the middle mouse button.
199     Changes to the panel are automatically saved to
200     <filename>~/.config/rox.sourceforge.net/ROX-Filer/pan_MyPanel</filename>.
201     As with the pinboard, you can switch between panel configurations
202     simply by running rox again with a different panel name.
204     <screen>$ rox -b=MyOtherPanel</screen>
206     You can set which edge of the screen the panel appears on using the popup menu.
207     You can also set the edge when enabling the panel by using the side instead of -b.
208     Specify a blank name to remove the panel:
210     <screen>$ rox --bottom=</screen>
211    </para>
212   </sect1>
214   <sect1>
215    <title><anchor id="winman" xreflabel="window manager notes"/>Window manager notes</title>
216    <para>
217     You may have to play around with your window manager a bit to get
218     the pinboard icons and panels to display correctly (eg, without borders
219     and underneath all other windows). In particular, try setting the
220     stacking level / depth to low (or a negative value). Make sure any
221     'Keep transients above other windows' type options are turned off!
222    </para>
224    <sect2><title>Sawfish / sawmill</title>
225     <para>
226      Sawfish tries to guess whether you are using GNOME at start-up and only
227      provides support if so. You may need to add the line
228      <programlisting>(require 'gnome)</programlisting>
229      to your <filename>.sawfishrc</filename> file (see the sawfish manual
230      for more details).
231     </para>
232    </sect2>
234    <sect2><title>IceWM</title>
235     <para>
237      Paste these configuration settings into
238      <filename>~/.icewm/preferences</filename>:
240      <programlisting>
241       # Manage root window (EXPERIMENTAL - normally enabled!)
242       GrabRootWindow=1 # 0/1
243       # Bitmask of root window button click to use in window manager
244       UseRootButtons=3 # [0-255]
245       # Desktop mouse-button click to show the menu
246       DesktopWinMenuButton=1 # [0-20]
247       # Desktop mouse-button click to show the window list
248       DesktopWinListButton=2 # [0-5]
249       # Desktop mouse-button click to show the window list menu
250       DesktopMenuButton=0 # [0-20]</programlisting>
251      Paste these into <filename>~/.icewm/winoptions</filename>:
253      <programlisting>
254       # ROX-Filer pinboard and panel
255       ROX-Filer.icon: folder
256       ROX-Panel.layer: Dock
257       ROX-Panel.doNotCover: 1
258       ROX-Panel.ignoreWinList: 1
259       ROX-Panel.ignoreTaskBar: 1
260       ROX-Panel.ignoreQuickSwitch: 1
261       ROX-Pinboard.layer: Below
262       ROX-Pinboard.ignoreWinList: 1
263       ROX-Pinboard.ignoreTaskBar: 1
264       ROX-Pinboard.ignoreQuickSwitch: 1
265       ROX-Filer.layer: Normal</programlisting>
266      Restart IceWM and the filer for the new settings to take effect.
268     </para>
269    </sect2>
271    <sect2><title>Window Maker</title>
272     <procedure>
273      <step><para>Run the filer using <userinput>rox -p=Default</userinput>.</para></step>
274       <step><para>
275        Press <keycap>Control</keycap>+<keycap>Escape</keycap>, or
276        [RightButtonDown] on any window's titlebar.
277        Choose <guimenuitem>Attributes...</guimenuitem> from the menu.
278       </para></step>
280       <step><para>
281        The Attributes Inspector window appears. From the pulldown menu
282        at the top, choose <guimenuitem>Window Specification</guimenuitem>
283        (the top item).
284       </para></step>
286       <step><para>
287        Press the <guibutton>Select window</guibutton> button.
288        The cursor changes to a double crosshair. Select one of the
289        <application>ROX-Filer</application> pinboard icons. The radio buttons
290        in the <guilabel>Window Specification</guilabel> frame should change
291        their labels to include <userinput>ROX-Pinboard.ROX-Filer</userinput>
292        as the first item. Select that radio button.
293       </para></step>
295       <step><para>
296        Choose <guimenuitem>Window Attributes</guimenuitem> from the pulldown
297        menu. In the <guilabel>Attributes</guilabel> frame, choose the
298        features you want the pinboard icons to have; I recommend the
299        following:
300         <itemizedlist>
301          <listitem><para>Disable titlebar</para></listitem>
302          <listitem><para>Disable resizebar</para></listitem>
303          <listitem><para>Disable close button</para></listitem>
304          <listitem><para>Disable miniaturize button</para></listitem>
305          <listitem><para>Keep at bottom (sunken)</para></listitem>
306          <listitem><para>Omnipresent</para></listitem>
307         </itemizedlist>
308        </para>
309       </step>
311       <step><para>
312        Choose <guimenuitem>Advanced Options</guimenuitem> from the pulldown
313        menu. In the <guilabel>Advanced</guilabel> frame, choose the advanced
314        features you wish; I recommend the following:
316        <itemizedlist>
317         <listitem><para>Do not show in the window list</para></listitem>
318         <listitem><para>Ignore 'Hide Others'</para></listitem>
319         <listitem><para>Ignore 'Save Session' (possibly)</para></listitem>
320        </itemizedlist>
321       </para></step>
323       <step><para>
324        When you're finished selecting window attributes, press the
325        <guibutton>Save</guibutton> button, and then close the Attributes
326        Inspector window using the <guibutton>X</guibutton> button in the titlebar.
327       </para></step>
328      </procedure>
329    </sect2>
331    <sect2><title>Others</title>
332     <para>
333      If all else fails, try the Compatibility section of the Options window.
334     </para>
335    </sect2>
336   </sect1>
338   <sect1>
339    <title>Running as root</title>
340    <para>
342     If you run the filer as the `root' user then the filer will display
343     a message at the top of each window to remind you. The root user has
344     permission to access or change any file in the system, so be very
345     careful when using the filer like this.
347     Normally, you should log in as an ordinary user and only change to
348     root when you need to. If you have <command>sudo</command> installed
349     and set up then you can run the filer like this:
351     <screen>$ sudo rox</screen>
353     Remember, any file operations you perform and any programs you run from
354     these windows will run as root too! Be careful!
355     </para><para>
356     You may find that the X server won't allow root (or other users) to
357     connect. Reading the manual pages for <command>xauth</command> and
358     <command>xhost</command> may give you some hints, but it varies
359     between systems (which is why this isn't built in to the filer!).
361    </para>
362    
363    <para>
364     Note: <command>gnomesu</command> can also be used to run the filer as root,
365     but you'll need to use <command>setsid</command> to run it in a new
366     session group, otherwise gnomesu kills it before it has a chance to open
367     a window. For example:
368     <screen>gnomesu -c 'setsid /usr/local/bin/rox /'</screen>
369    </para>
370   </sect1>
372  </chapter>
374  <chapter id="keys" xreflabel="mouse and key bindings">
375   <title>Mouse button and key bindings</title>
377   <itemizedlist><title>Quick start:</title>
379    <listitem><para>Click the left
380      <footnote><para>This documentation assumes that button&ndash;1 is the left
381        button, button&ndash;2 is the middle button and button&ndash;3 is the
382        right button. This is not always the case &mdash; for example, in a
383        left-handed setup.</para></footnote> mouse button to open files and
384      directories.</para></listitem>
386    <listitem><para>
387      Click the right button to get a menu. Click over a file to perform an action on that file.
388    </para></listitem>
390    <listitem><para>
391      Drag files between windows with the left button to copy, move or link them
392      (choose from a menu). Linking creates a shortcut to the original file.
393    </para></listitem>
395   </itemizedlist>
397   <para>
398    By default, the mouse button bindings are designed to fit in with X
399    conventions. However, the behaviour is highly configurable &mdash; have a play in
400    the Options window if you don't like the normal settings. The normal settings
401    behave as follows:
402   </para>
404   <informaltable>
405    <tgroup cols="2">
406     <thead><row><entry>Key or mouse button</entry><entry>Action</entry></row></thead>
408     <tbody>
410      <row><entry>Left button click</entry><entry>
411        Open the file or directory clicked on. Hold down <keycap>Control</keycap>
412        to select things instead of opening them. Hold down <keycap>Shift</keycap>
413        to look inside applications, treat files as text, follow symlinks, or
414        get more control over mount points (see <xref linkend="media"/>).
415      </entry></row>
417      <row><entry>Middle button click</entry><entry>
418        Same as left click, but open a directory in a new window or close the viewer
419        when opening a file.
420      </entry></row>
422      <row><entry>Right button click</entry><entry>
423        Open the main menu. Hold down <keycap>Control</keycap> while clicking to go
424        directly to the Selection submenu. Hold down <keycap>Shift</keycap> to get the
425        <guimenu>Send To</guimenu> menu (see the <xref linkend="SendTo"/> section).
426      </entry></row>
428      <row><entry>Drag an item  (left mouse button)</entry><entry>
429        Show a menu of possible actions. There is an option to disable this menu,
430        in which case this gesture will copy the file(s) to the destination (an
431        application or another filer window). Hold down <keycap>Shift</keycap>
432        to move the file, <keycap>Control</keycap>+<keycap>Shift</keycap> to
433        create a symbolic link, or <keycap>Alt</keycap> to get the menu of
434        possible actions.
435      </entry></row>
437      <row><entry>Drag an item (middle mouse button)</entry><entry>
438        When you let go, display a menu of possible actions.
439        There is an option to make this move the files rather than open the menu.
440      </entry></row>
442      <row><entry>Drag (not over an item)</entry><entry>
443        Select a group of items by dragging a box around them. With the left
444        mouse button, only the files in the box will be selected. If you hold
445        down <keycap>Control</keycap> then the boxed items are added to the selection.
446        If you use the middle button then the boxed items switch between being selected
447        and unselected.
448      </entry></row>
450      <row><entry>Double-click background</entry><entry>
451        Resize the window to a sensible size (this can be turned off from
452        the Options window).
453      </entry></row>
455      <row><entry><keycap>Backspace</keycap></entry><entry>
456        Change to viewing the parent directory.
457      </entry></row>
459      <row><entry>Cursor keys</entry><entry>
460        Move the cursor around.
461      </entry></row>
463      <row><entry>
464        <keycap>Page Up</keycap>, <keycap>Page Down</keycap></entry><entry>
465        Move the cursor up and down a page at a time.
466      </entry></row>
468      <row><entry><keycap>Home</keycap>, <keycap>End</keycap></entry><entry>
469        Move to the first/last entry in the directory.
470      </entry></row>
472      <row><entry><keycap>Return</keycap></entry><entry>
473        Acts like clicking on the file. You may hold down Shift for other
474        effects, as with clicking. Holding down Alt works like clicking with
475        the middle button; directories open in a new window and opening files
476        closes the directory at the same time.
477      </entry></row>
479      <row><entry><keycap>Spacebar</keycap></entry><entry>
480        Toggles the item under the cursor between being selected and unselected,
481        and moves to the next item.
482      </entry></row>
484      <row><entry><keycap>Tab</keycap>, <keycap>Shift</keycap>+<keycap>Tab</keycap></entry><entry>
485        Moves the cursor to the next/previous selected item.
486      </entry></row>
488      <row><entry>Hold mouse over an item</entry><entry>
489        Shows a tooltip containing a brief description of an application (if
490        available), the target of a symbolic link, and the full name of a file,
491        if it's too long to show in the main window.
492      </entry></row>
494   </tbody></tgroup></informaltable>
496   <para>
497    If you have user-defineable key-bindings enabled, then other keys can easily
498    be set by opening the menu, moving the pointer over the item you want to use
499    and pressing a key. The key will appear in the menu and can be used from
500    then on. Key bindings are automatically saved when the filer quits.
501    You can use an XSettings manager, such as ROX-Session, to turn this feature
502    on for all Gtk+-2.0 applications.
503   </para>
504  </chapter>
506  <chapter id="selection">
507   <title>The selection and file groups</title>
508   <para>
509    When you select items in a <application>ROX-Filer</application> window,
510    the filer takes the <emphasis>primary selection</emphasis>. You can then paste
511    into another window to get the pathnames of the selected files.
512   </para>
514   <procedure>
515    <title>Example: loading a file into an application that doesn't support
516     drag-and-drop:</title>
518    <step><para>Open the application's Open dialog box.</para></step>
520    <step><para>
521      <keycap>Control</keycap>-click on the file in
522      <application>ROX-Filer</application> to select it.</para></step>
524    <step><para>
525      Click the middle button in the filename box in the application to paste the
526      name in.
527    </para></step>
528   </procedure>
530   <para>
531    Note that clicking the middle mouse button in the main area of most web-browsers
532    will open the selected file.
533    </para><para>
534    If you select something else (eg, some text in another program), the selected
535    items in the filer window will be shown shaded (the filer no longer has the
536    primary selection).  Clicking on one of the shaded items will cause the
537    filer to regain the primary selection.
538   </para>
540   <sect1><title>Saving and restoring the selection</title>
541    <para>
542     It is sometimes useful to save the current selection for later. You can
543     save the current selection to one of ten numbered groups by pressing
544     <keycap>Control</keycap>+<keycap>&lt;number&gt;</keycap>.
545     You can restore a saved group by pressing the group number on its own. You
546     can do this from a different directory, or even a different filer window.
547     </para><para>
548     Saving is also useful even if there is no selection, since it still saves
549     the current directory.
550    </para>
551    <procedure><title>Example: saving a directory and returning to it later:</title>
552     <step><para>You are looking at a directory, and wish to remember it.
553       Press <keycap>Control</keycap>+<keycap>1</keycap>.</para></step>
554     <step><para>Move to another directory, or close the window, etc.</para></step>
555     <step><para>Press <keycap>1</keycap> in any filer window to return
556       to the first directory.</para></step> </procedure>
557    <para>The groups are saved automatically for next time the filer is loaded.
558   </para></sect1>
559  </chapter>
561  <chapter id="toolbar">
562   <title><anchor id="Toolbar" xreflabel="Toolbar"/>The toolbar</title>
563   <para>
565    By default, each window has a toolbar along the top. You can disable
566    this (or make it larger) from the Options window, as well as set which
567    tools appear on the toolbar. Normally, you should click with the left
568    mouse button (1). However, many tools can perform a related function
569    if clicked on with buttons 2 or 3 (middle or right).
570   </para>
572   <informaltable><tgroup cols="3">
574     <thead>
575      <row><entry>
576        Icon</entry><entry>
577        Mouse button 1</entry><entry>
578        Other button
579      </entry></row>
581     </thead>
582     <tbody>
584      <row><entry>
585        Cross</entry><entry>
586        Close the window</entry><entry>
587        Open a new window
588        </entry></row><row><entry>
589        Up arrow</entry><entry>
590        Change to parent directory</entry><entry>
591        Show parent in a new window <xref linkend="newwin_fn"/>
592        </entry></row><row><entry>
593        House</entry><entry>
594        Change to home directory</entry><entry>
595        Show home in a new window <xref linkend="newwin_fn"/>
596        </entry></row><row><entry>
597        Jump to point</entry><entry>
598        Open the <xref linkend="bookmarks"/>
599        </entry><entry>
600        Edit the bookmarks
601        </entry></row><row><entry>
602        Looping arrows</entry><entry>
603        Reread the directory contents</entry><entry>
604        Open a new window
605        </entry></row><row><entry>
606        Magnifying glass (+)</entry><entry>
607        Select a larger icon size.</entry><entry>
608        Select a smaller icon size.
609        </entry></row><row><entry>
610        Magnifying glass (fit)</entry><entry>
611        Set Automatic sizing mode and resize the window.</entry><entry>
612        -
613        </entry></row><row><entry>
614        List</entry><entry>
615        Hide or show extra details</entry><entry>
616        Same
617        </entry></row><row><entry>
618        A..Z</entry><entry>
619        Step forward through the different sort types.</entry><entry>
620        Step backward through the sort types.
621        </entry></row><row><entry>
622        Eye</entry><entry>
623        Toggle the display of hidden files (those with names starting with a dot)</entry><entry>
624        Same
625        </entry></row><row><entry>
626        List with selections</entry><entry>
627        Select All.</entry><entry>
628        Invert Selection.
629        </entry></row><row><entry>
630        Life-belt</entry><entry>
631        Show <application>ROX-Filer</application>'s help files</entry><entry>
632        Open manual directly
633      </entry></row>
634   </tbody></tgroup></informaltable>
636   <para>
637    <anchor id="newwin_fn" xreflabel="[1]"/>[1]
638    If the 'New window on button 1' option is turned on
639    then the default is to open a new window &mdash; clicking with the other
640    button reuses the same window instead.
641   </para>
643   <para>
644    Dragging files to the Up or Home icons acts just like dragging them
645    into the directory which the button leads to. Dragging to the Bookmarks button
646    will add the directory as a bookmark.
647   </para>
648   <para>
649    The toolbar can also show the number of files in the directory, and
650    information about the selection. This can be turned on or off in the
651    Options box.
652   </para>
653  </chapter>
655  <chapter id="menus">
656   <title>The menus</title>
657   <para>
658    By default, you can open a menu by right clicking over a pinboard, panel or
659    filer window.
661    In filer windows, you may also press <keycap>\</keycap> to open the menu. As
662    a shortcut, you can open the File submenu directly by holding down the
663    <keycap>Control</keycap> key when opening the menu. Here is a full
664    description of each menu item:
666    <informaltable><tgroup cols="2">
668      <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
670      <tbody>
671       <row><entry><guimenuitem>Display</guimenuitem></entry><entry>
672         Change the display settings.
673       </entry></row>
675       <row><entry><guimenuitem>File</guimenuitem></entry><entry>
676         Operations on the selected items.
677       </entry></row>
679       <row><entry><guimenuitem>Select</guimenuitem></entry><entry>
680         Control which items are selected.
681       </entry></row>
683       <row><entry><guimenuitem>Options...</guimenuitem></entry><entry>
684         Configure <application>ROX-Filer</application>.
685       </entry></row>
687       <row><entry><guimenuitem>New</guimenuitem></entry><entry>
688         Create a new file or subdirectory inside this directory.
689       </entry></row>
691       <row><entry><guimenuitem>Window</guimenuitem></entry><entry>
692         Operations on the window as a whole.
693       </entry></row>
695       <row><entry><guimenuitem>Help</guimenuitem></entry><entry>
696         Information about the filer.
697       </entry></row>
699    </tbody></tgroup></informaltable>
701   </para>
703   <sect1>
704    <title>The display menu</title>
705    <para>
707     <informaltable><tgroup cols="2">
709       <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
711       <tbody>
712        <row><entry><guimenuitem>Icons View</guimenuitem></entry><entry>
713        Files are displayed as rows of icons.
714        </entry></row>
716        <row><entry><guimenuitem>Icons, With...</guimenuitem></entry><entry>
717        Files are displayed as rows of icons with additional details
718        (chosen from the submenu). To see fuller information about each file
719        use the List View instead.
720        </entry></row>
722        <row><entry><guimenuitem>List View</guimenuitem></entry><entry>
723        Show files in a list along with their details. Click on a column heading
724        to sort by that column.
725        </entry></row>
727        <row><entry><guimenuitem>Bigger Icons</guimenuitem></entry><entry>
728        Increase the size of the icons. Turns off Automatic mode.
729        </entry></row>
731        <row><entry><guimenuitem>Smaller Icons</guimenuitem></entry><entry>
732        Reduce the size of the icons. Turns off Automatic mode.
733        </entry></row>
735        <row><entry><guimenuitem>Automatic</guimenuitem></entry><entry>
736        Select a sensbile icon size automatically now and when changing
737        directory, etc.
738        </entry></row>
740        <row><entry><guimenuitem>Sort by XXX</guimenuitem></entry><entry>
741        Set the sort mode. In List View you can also set the sort type by
742        clicking on the column headings.
743        </entry></row>
745        <row><entry><guimenuitem>Reversed</guimenuitem></entry><entry>
746        Sort in reverse order (newest to oldest, largest to smallest, etc).
747        </entry></row>
749        <row><entry><guimenuitem>Show Hidden</guimenuitem></entry><entry>
750        If on, files beginning with a dot are shown, otherwise they are hidden.
751        The titlebar shows <guilabel>(All)</guilabel> when this is on.
752        </entry></row>
754        <row><entry><guimenuitem>Filter Files...</guimenuitem></entry><entry>
755        Restrict the display to only show files with names matching the
756        given pattern.
757        The titlebar shows <guilabel>(Glob (pattern))</guilabel> when this is on.
758        </entry></row>
760        <row><entry><guimenuitem>Show Thumbnails</guimenuitem></entry><entry>
761        When on, the filer tries to load every image file and use that
762        image as the file's icon. Useful if you have a directory full of
763        photos and can't remember which is which!
764        See the <xref linkend="thumbnails"/> section for details.
765        </entry></row>
767        <row><entry><guimenuitem>Refresh</guimenuitem></entry><entry>
768        Rereads the contents of the directory and details of all the files
769        in it. Use this if the display becomes out-of-date.
770        </entry></row>
772        <row><entry><guimenuitem>Save Display Settings...</guimenuitem></entry><entry>
773        Remember the display settings just for this directory. Each time you
774        open the directory, the saved settings will be used.
775        </entry></row>
776     </tbody></tgroup></informaltable>
778    </para>
780    <sect2><title><anchor id="Permissions" xreflabel="Permissions"/>
781      Permissions
782     </title>
783     <para>
785      The permissions field, when shown, is made up of four groups of three
786      flags. Each flag is displayed as a letter if it is on and a dash (&ndash;)
787      if not. The first three characters show the permissions for the owner
788      of the file, the second for other members of the file's group and
789      the third for everyone else. Whichever group applies to the
790      <application>ROX-Filer</application> process itself is shown underlined.
791      The fourth group shows any special flags.
792      </para><para>
793      The meanings of the characters are:
795      <itemizedlist>
797       <listitem><para><computeroutput>r</computeroutput> &mdash;
798         Permission to read the contents of a file, or the names of files
799         in a directory.</para></listitem>
801       <listitem><para><computeroutput>w</computeroutput> &mdash;
802         Permission to alter the contents of a file, or change which names
803         appear in a directory.</para></listitem>
805       <listitem><para><computeroutput>x</computeroutput> &mdash;
806         Permission to run the file as a program, or refer to the files
807         listed within the directory.</para></listitem>
809       <listitem><para><computeroutput>U</computeroutput> &mdash;
810         This program executes with the <emphasis>effective user ID</emphasis> of its
811         owner rather than the person who ran it.</para></listitem>
813       <listitem><para><computeroutput>G</computeroutput> &mdash;
814         This program executes with the <emphasis>effective group ID</emphasis> of its
815         group, regardless of who ran it.</para></listitem>
817       <listitem><para><computeroutput>T</computeroutput> &mdash;
818         Entries in this directory can only be altered or removed by the
819         people who own the files even if they have write permission on the
820         directory itself.</para></listitem>
822      </itemizedlist>
823      For example,
824      <programlisting>
825       <emphasis role="underline">rwx</emphasis>,rwx,r-x/---</programlisting>
826      means that the owner of the file is the same as the effective user of
827      <application>ROX-Filer</application> (basically, you own the file), you and
828      members of the file's group have read, write and execute permission and other
829      people have only read and execute permission. There are no special flags set.
831      The rules which determine which permissions apply may vary slightly between
832      operating systems, but a rough guide is:
834      <itemizedlist>
836       <listitem><para>If the <emphasis>effective user ID</emphasis> of the
837         process is equal to the file's owner, then the owner permissions apply.
838       </para></listitem>
840       <listitem><para>Otherwise, if the <emphasis>effective group ID</emphasis>
841         of the process is equal to the file's group OR the file's group is one
842         of the process's <emphasis>supplemental groups</emphasis> then the
843         group permissions apply.
844       </para></listitem>
846       <listitem><para>Otherwise, the `other' permissions apply. The
847         <emphasis>real user ID</emphasis> and <emphasis>real group
848          ID</emphasis> have no effect (except that a process may set its real
849         IDs to its effective IDs).
850       </para></listitem>
852      </itemizedlist>
854     </para>
855    </sect2>
856   </sect1>
858   <sect1>
859    <title>The file menu</title>
860    <para>
861     All of these work in the same way &mdash; if you open the menu with some
862     items selected then the operation applies to those items. If you open
863     then menu over an item while there is no selection then that item
864     is temporarily selected.
865     </para><para>
866     If you choose one of these while there is no selection at all then the
867     window goes into `target mode'; the operation happens to the next item you
868     click on. Click on the window background, press <keycap>Escape</keycap>, or
869     click with the right mouse button to cancel target mode. Target mode is
870     mainly useful with the <guilabel>Single-click navigation</guilabel> option
871     and keys bound to the various menu entries. </para><para>
872     Note that individual applications may add extra menu items to the
873     top of this submenu when you click over them &mdash; see
874     <xref linkend="AppDir"/> for details. There may also be any number of
875     user-defined actions at the top, which depend on the type of file
876     clicked on. You can add programs here by choosing the
877     <guimenuitem>Customise Menu</guimenuitem> item. For example, you could
878     make <application>The Gimp</application> appear on the menu for images, and
879     <application>FreeFS</application> appear for mount points.
881     <informaltable><tgroup cols="2">
882       <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
883       <tbody>
885        <row><entry>
886          <guimenuitem>Copy...</guimenuitem></entry><entry>
887          Make a copy of this object.
888        </entry></row>
890        <row><entry>
891          <guimenuitem>Rename...</guimenuitem></entry><entry>
892          Change the name used for this object, or move it between directories.
893          If multiple files are selected, this opens
894          <xref linkend='bulkrename' />.
895        </entry></row>
897        <row><entry>
898          <guimenuitem>Link...</guimenuitem></entry><entry>
899          Create a symbolic link to this name.
900        </entry></row>
902        <row><entry>
903          <guimenuitem>Delete</guimenuitem></entry><entry>
904          Remove all the selected entries from the directory. Subdirectories
905          will have their contents deleted first. Deleting symlinks only removes
906          the link, not the thing it points to.
907        </entry></row>
909        <row><entry>
910          <guimenuitem>Shift Open</guimenuitem></entry><entry>
911          Opens applications as directories, files as text/plain, and
912          symlinks by opening the directory containing the thing they point to.
913          It also has interesting effects on mount points (see <xref linkend="media"/>).
914          This is the same effect as clicking with <keycap>Shift</keycap> held
915          down. The text of the menu entry changes to show which action will be
916          performed.
917        </entry></row>
919        <row><entry>
920          <guimenuitem>Open AVFS</guimenuitem></entry><entry>
921          Open the file as if it was a directory &mdash; see the
922          <xref linkend="vfs"/> section.
923        </entry></row>
925        <row><entry>
926          <guimenuitem>Send To...</guimenuitem></entry><entry>
927          Opens the `Send To' menu, allowing you to send the selected files
928          to one of a list of applications. See the
929          <xref linkend="SendTo"/> section.
930        </entry></row>
932        <row><entry>
933          <guimenuitem>Set Run Action...</guimenuitem></entry><entry>
934          Allows you to set the default program to use when opening files of
935          this type. See <xref linkend="RunAction"/> section for details.
936        </entry></row>
938        <row><entry>
939          <guimenuitem>Set Icon...</guimenuitem></entry><entry>
940          You can give each file or directory its own special icon using this
941          feature &mdash; simply drag a suitable image onto <xref linkend="SetIcon"/>.
942        </entry></row>
944        <row><entry>
945          <guimenuitem>Properties</guimenuitem></entry><entry>
946          Display extra information about this object. You can also change
947          the access permissions from here (<guimenuitem>Permissions</guimenuitem>
948          below allows you to change many files at once), and change the target
949          to which a symlink points.
950        </entry></row>
952        <row><entry>
953          <guimenuitem>Count</guimenuitem></entry><entry>
954          Count the sizes of all the selected items. Directories also have their
955          contents counted. Symlinks count themselves, not the things they point
956          to.
957        </entry></row>
959        <row><entry>
960          <guimenuitem>Set Type...</guimenuitem></entry><entry>
961          Set the MIME type for a file. This only works on filesystems with extended attribute support. For older filesystems, you will have to rename a file to change its type.
962        </entry></row>
964        <row><entry>
965          <guimenuitem>Permissions</guimenuitem></entry><entry>
966          Allows you to change the permissions for the selected files.
967          If only one file is to be changed, you can use
968          <guimenuitem>Properties</guimenuitem> instead for a simpler interface.
969        </entry></row>
971        <row><entry>
972          <guimenuitem>Find</guimenuitem></entry><entry>
973          Search for files by specifying various conditions &mdash; see the
974          <xref linkend="Searching"/> section.
975        </entry></row>
977     </tbody></tgroup></informaltable>
978    </para>
980    <formalpara><title>Note about symlinks:</title>
981     <para>
982      A symbolic link stores the <emphasis>location</emphasis>
983      of another file. Deleting the symlink doesn't affect the other file.
984      Deleting the other file means that the symlink won't work. There are
985      two types of symbolic link &mdash; Relative and Absolute. An absolute
986      link stores the path from the root directory to the target file (eg
987      <filename>/home/fred/MyFile</filename>).
989      A relative path stores the path from the symlink
990      to the target (eg <filename>../fred/MyFile</filename>).
991      If the target file is never going to move then you want an absolute link,
992      but if the target may move (and the symlink will be moved with it) then
993      you want a relative link.
994     </para>
995    </formalpara>
996   </sect1>
998   <sect1>
999    <title>The select menu</title>
1000    <para>
1001     This menu allows you to select and unselect files in various ways. See the
1002     <xref linkend="keys"/> section for other ways to select files.
1004     <informaltable><tgroup cols="2">
1005       <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1006       <tbody>
1007        <row><entry>
1008          <guimenuitem>Select All</guimenuitem></entry><entry>
1009          Select every item in this window.
1010        </entry></row>
1012        <row><entry><guimenuitem>Clear Selection</guimenuitem></entry><entry>
1013          Unselect every item in this window.
1014        </entry></row>
1016        <row><entry><guimenuitem>Invert Selection</guimenuitem></entry><entry>
1017          Every selected file becomes unselected, and every unselected file
1018          becomes selected.
1019        </entry></row>
1021        <row><entry>
1022          <guimenuitem>Select by Name...</guimenuitem></entry><entry>
1023          Select just those files that match the given name pattern. This
1024          isn't as flexible as <guimenuitem>Select If...</guimenuitem> (see
1025          below), but it is quicker to use. Files also highlight as you type
1026          with this option. The default key binding is <keycap>.</keycap>,
1027          so you can type <userinput>.png</userinput> to select all
1028          <filename>.png</filename> files, for example.
1029        </entry></row>
1031        <row><entry>
1032          <guimenuitem>Select If...</guimenuitem></entry><entry>
1033          Select just those files that match the given pattern &mdash;
1034          see the <xref linkend="SelectIf"/> section.
1035        </entry></row>
1037     </tbody></tgroup></informaltable>
1039    </para>
1040   </sect1>
1042   <sect1>
1043    <title>The new menu</title>
1044    <para>
1046     Each entry in this submenu opens a savebox for creating a new file or
1047     directory. There are three standard entries; the others are the contents of
1048     your <filename>~/.config/rox.sourceforge.net/Templates</filename> directory, if it
1049     exists.
1052     <informaltable><tgroup cols="2">
1053       <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1054       <tbody>
1055        <row><entry>Directory</entry><entry>
1056          Create a new directory.
1057          </entry></row>
1058          
1059          <row><entry>File</entry><entry>
1060          Create a blank file.
1061          </entry></row>
1063          <row><entry>Customise Menu</entry><entry>
1064          Open the <filename>Templates</filename> directory so that you can
1065          add extra items to the menu.
1066          </entry></row>
1067          
1068          <row><entry>&lt;user entries&gt;</entry><entry>
1069          Copy a file from your Templates directory.
1070        </entry></row>
1071     </tbody></tgroup></informaltable>
1074     To add your own entries, choose <guimenuitem>Customise Menu</guimenuitem>
1075     and put any files you want in there. Each file in the directory will appear
1076     on the menu and the box that appears will copy it. For example, you could
1077     create a blank HTML file:
1079     <programlisting>
1080 &lt;html&gt;
1081  &lt;head&gt;
1082   &lt;title&gt;My Page&lt;/title&gt;
1083  &lt;/head&gt;
1084  &lt;body&gt;
1085   The contents.
1086  &lt;/body&gt;
1087 &lt;/html&gt;</programlisting>
1089     Save this as <filename>index.html</filename> inside the
1090     <filename>Templates</filename> directory and you can easily create new
1091     HTML files. You can also save blank documents from various applications
1092     into here (eg, a blank spreadsheet, a blank letter, etc).
1093     </para><para>
1094     Note that you cannot set keyboard shortcuts for these user-defined
1095     entries at present.
1097    </para>
1098   </sect1>
1100   <sect1>
1101    <title>The window menu</title>
1102    <para>
1105     <informaltable><tgroup cols="2">
1106       <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1107       <tbody>
1108        <row><entry>
1109          <guimenuitem>Parent, New Window</guimenuitem></entry><entry>
1110          Open a new window displaying this window's parent.
1111        </entry></row>
1113        <row><entry>
1114          <guimenuitem>Parent, Same Window</guimenuitem></entry><entry>
1115          As above, but reuse this window.
1116        </entry></row>
1118        <row><entry>
1119          <guimenuitem>New Window</guimenuitem></entry><entry>
1120          Open another window onto this directory.
1121        </entry></row>
1123        <row><entry>
1124          <guimenuitem>Home Directory</guimenuitem></entry><entry>
1125          Change to your home directory.
1126        </entry></row>
1128        <row><entry>
1129          <guimenuitem>Show Bookmarks</guimenuitem></entry><entry>
1130          Open the bookmarks menu (see <xref linkend="bookmarks"/>).
1131        </entry></row>
1133        <row><entry>
1134          <guimenuitem>Follow Symbolic Links</guimenuitem></entry><entry>
1135          Converts the path shown in the window's titlebar to its canonical form.
1136          For example, if <filename>/home/fred/link</filename> is a symlink
1137          pointing to <filename>/usr/share/doc/</filename> then clicking on the symlink
1138          will take you to that directory and going `up' will take you back to
1139          <filename>/home/fred</filename>.
1140          If you'd used <guimenuitem>Follow Symbolic Links</guimenuitem>, you would
1141          have ended up in <filename>/usr/share</filename> instead.
1142        </entry></row>
1144        <row><entry>
1145          <guimenuitem>Resize Window</guimenuitem></entry><entry>
1146          Set the window to a sensible size for its contents.
1147        </entry></row>
1149        <row><entry>
1150          <guimenuitem>Close Window</guimenuitem></entry><entry>
1151          Close this window.
1152        </entry></row>
1154        <row><entry>
1155          <guimenuitem>Enter Path...</guimenuitem></entry><entry>
1156          Open the path-entry box (see the the <xref linkend="mini"/> section).
1157        </entry></row>
1159        <row><entry>
1160          <guimenuitem>Shell Command...</guimenuitem></entry><entry>
1161          Open the shell command box (see the <xref linkend="mini"/> section).
1162        </entry></row>
1164       <row><entry><guimenuitem>Xterm Here</guimenuitem></entry><entry>
1165         Open an xterm with its current directory set to this directory.
1166       </entry></row>
1168       <row><entry><guimenuitem>Switch to xterm</guimenuitem></entry><entry>
1169         Open an xterm with its current directory set to this directory, and close the
1170         filer window at the same time.
1171       </entry></row>
1173     </tbody></tgroup></informaltable>
1176    </para>
1177   </sect1>
1179   <sect1>
1180    <title>The help menu</title>
1181    <para>
1183     <informaltable><tgroup cols="2">
1184       <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1185       <tbody>
1186        <row><entry>
1187          <guimenuitem>About ROX-Filer...</guimenuitem></entry><entry>
1188          Display information about the file. This is the same as locating ROX-Filer
1189          itself in a filer window and selecting <guimenuitem>Properties</guimenuitem> from
1190          the file menu.
1191        </entry></row>
1193        <row><entry>
1194          <guimenuitem>Show Help Files</guimenuitem></entry><entry>
1195          Same as selecting ROX-Filer and choosing
1196          <guimenuitem>Help</guimenuitem> from the file menu.
1197        </entry></row>
1199        <row><entry>
1200          <guimenuitem>Manual</guimenuitem></entry><entry>
1201          Opens the HTML manual for your language, or the English version if there
1202          is no translation.
1203        </entry></row>
1205     </tbody></tgroup></informaltable>
1207    </para>
1208   </sect1>
1210   <sect1>
1211    <title><anchor id="SendTo" xreflabel="Send To menu"/>The send to menu</title>
1212    <para>
1214     The `Send To' menu provides a quick way to send some files to an application.
1215     The filer scans all the <filename>$XDG_CONFIG_DIRS/rox.sourceforge.net/SendTo</filename>
1216     directories (see <citation>BaseDir</citation>) and lists
1217     the contents on this menu.
1218     </para><para>
1219     To change which applications appear here you should choose the
1220     <guimenuitem>Customise</guimenuitem> item from the bottom
1221     of the menu to create and open your own <filename>SendTo</filename>
1222     directory. Applications can be symlinked into this directory by dragging
1223     them in and choosing <guimenuitem>Link</guimenuitem> from the menu.
1224     </para><para>
1225     Opening the Send To menu via the main menu is rather slow, so it is
1226     normally opened by clicking the Menu mouse button over a file while
1227     holding the <keycap>Shift</keycap> key down.
1228    </para>
1229    <sect2>
1230     <title>Showing different applications for different types</title>
1231     <para>
1232      You may want to set things up so that, for example, the Gimp is
1233      only shown when an image is selected. To do this, create a
1234      hidden directory inside <filename>SendTo</filename> called
1235      <filename>.image</filename>, or whatever type you want to use.
1236      You can use either the complete type (eg <filename>.image_png</filename>)
1237      or just the media type. Use <guimenuitem>Properties</guimenuitem> over a
1238      file to find out its MIME type.
1239     </para>
1240     <para>
1241      Entries in these hidden directories are shown only for files of
1242      the appropriate type. If multiple files are selected, the
1243      <filename>.group</filename> directory is used instead.
1244     </para>
1245    </sect2>
1246   </sect1>
1248   <sect1>
1249    <title><anchor id="bookmarks" xreflabel="Bookmarks menu"/>The bookmarks menu</title>
1250    <para>
1251     The bookmarks menu can be used to store a list of frequently used directories.
1252     You can also open the menu from the main popup menu (in the <guimenuitem>Window</guimenuitem> submenu)
1253     and you can use this to bind a shortcut key to it. From the bookmarks menu
1254     you can add the currently shown directory to the list, jump to one of the
1255     stored directories, or open a dialog letting you edit the list. In the dialog
1256     box, you can remove entries, rearrange them (using the arrows or by
1257     dragging) and edit the pathnames directly, if required.
1258    </para>
1259    <para>
1260     The <guimenuitem>Recently Visited</guimenuitem> submenu shows the last few directories
1261     viewed. Choosing one will switch to that directory. The current directory is shown
1262     shaded, since you are already there.
1263    </para>
1264   </sect1>
1266  </chapter>
1268  <chapter id="icons">
1269   <title>The pinboard and panels</title>
1270   <para>
1272    The <xref linkend="run_pin"/> and <xref linkend="run_pan"/> sections explain
1273    how to turn the pinboard and panels on. Once on, you may drop items from filer
1274    windows onto the them to pin them up. Clicking on a pinned item acts just like
1275    clicking on it in a filer window. You can drag pinned icons just like normal
1276    icons and you can right-click on one to see the popup menu.
1277    </para><para>
1278    Drag panel icons with the middle mouse button to move them around.
1279    In previous versions of the filer, pinboard icons were also moved using the
1280    middle mouse button, but this is no longer supported (as the middle button
1281    is reserved for the window manager's use).
1282    </para><para>
1283    You can assign keyboard shortcuts to pinboard and panel icons. These can be
1284    used to open directories, files or applications quickly, even if another
1285    window has the focus.
1286    </para><para>
1287    Changes to the pinboard and panel are automatically saved. Clicking on pinned
1288    icons with <keycap>Control</keycap> held down selects and unselects them.
1289    Click on the background to unselect them all.
1290   </para>
1292   <important><para>
1293     Pinning a file does <emphasis>not</emphasis> copy it, it merely
1294     creates a shortcut to the original file. If you delete the file, then
1295     you've lost it! Removing a pinned file from its pinboard or panel
1296     only removes the link. This is different to most other filers...
1297   </para></important>
1299   <sect1>
1300    <title>The pinboard and panel menus</title>
1301    <para>
1303     <informaltable><tgroup cols="2">
1304       <thead><row><entry>Entry</entry><entry>Action</entry></row></thead>
1305       <tbody>
1307        <row><entry>
1308          <guimenuitem>ROX-Filer</guimenuitem></entry><entry>
1309          Show the filer's help, edit the options or open your home directory.
1310        </entry></row>
1312        <row><entry>
1313          <guimenuitem>File `file'</guimenuitem></entry><entry>
1314          Offers a smaller version of the filer's submenu of the same name.
1315        </entry></row>
1317        <row><entry>
1318          <guimenuitem>Edit Item</guimenuitem></entry><entry>
1319          Change the name displayed under the icon, or the pathname the item
1320          points to. You can also set a keyboard shortcut for the icon here.
1321          For programs, you can specify extra arguments to be passed in.
1322        </entry></row>
1324        <row><entry>
1325          <guimenuitem>Show Location</guimenuitem></entry><entry>
1326          Open a directory viewer showing where the file is stored.
1327        </entry></row>
1329        <row><entry>
1330          <guimenuitem>Remove Item(s)</guimenuitem></entry><entry>
1331          Remove the selected items from the pinboard or panel.
1332        </entry></row>
1334        <row><entry>
1335          <guimenuitem>Backdrop...</guimenuitem></entry><entry>
1336          Set the desktop backdrop image (see below). Only available from
1337          the pinboard menu.
1338        </entry></row>
1340        <row><entry>
1341          <guimenuitem>Panel Options...</guimenuitem></entry><entry>
1342          Set the edge of the screen on which the panel is displayed. Only available from
1343          the panel menu.
1344        </entry></row>
1346     </tbody></tgroup></informaltable>
1348     </para><para>
1349     If you are setting up the defaults for multiple users and
1350     you wish to create a `Home' icon that leads to each user's home directory
1351     then you should first create a new icon and then use
1352     <guimenuitem>Edit Icon</guimenuitem> to change the location to
1353     <filename>~</filename> and the name to `Home'.
1354     </para><para>
1355     Note that individual applications may add extra menu items to the
1356     top of this menu when you click over them &mdash; see <xref linkend="AppDir"/>
1357     for details.
1358    </para>
1359   </sect1>
1361   <sect1>
1362    <title>Panel applets</title>
1363    <para>
1365     <application>ROX-Filer</application> allows you to run small programs
1366     inside the panel &mdash; such programs are called
1367     <emphasis>applets</emphasis>. To run an applet, drag it onto the panel from
1368     a filer window and instead of the applet's icon being shown, the applet
1369     will run.
1370    </para>
1372    <procedure><title>To create your own applets (programmers only!):</title>
1374     <step><para>
1375       Create a directory for the applet (eg <filename>MyApplet</filename>).
1376     </para></step>
1378     <step><para>
1379       Use the <guimenuitem>Set Icon...</guimenuitem> feature to create an icon
1380       called <filename>.DirIcon</filename> inside it (so the directory appears
1381       with an icon).
1382     </para></step>
1384     <step><para>
1385       Make a <filename>Help</filename> directory inside it for when the user
1386       chooses <guimenuitem>Help</guimenuitem> from the menu.
1387     </para></step>
1389     <step><para>
1390       Create an executable file called <filename>AppletRun</filename>. This will be
1391       passed the XID of the panel socket window when the directory is dragged
1392       onto the panel. You can use this to create a GtkPlug widget. A
1393       tutorial is available at
1394       <ulink url="http://rox.sourceforge.net/phpwiki/index.php/Tutorials/Applets"/>
1395     </para></step>
1397    </procedure>
1398   </sect1>
1400   <sect1>
1401    <title><anchor id="iconify" xreflabel="Iconified windows"/>Iconified windows on the pinboard</title>
1402    <para>
1403     When the pinboard is in use, ROX-Filer can be used to display an icon for each iconified
1404     (or 'minimised') window. You can turn this on or off from the Options box. Iconified window icons
1405     have a semi-transparent background slab effect, and can be dragged around.
1406     Clicking on one will expand it back into the window it represents. Some
1407     older window managers do not support this, and no icons will be shown.
1408    </para>
1409   </sect1>
1411   <sect1>
1412    <title><anchor id="backdropapp" xreflabel="Backdrop applications"/>The pinboard backdrop image</title>
1413    <para>
1414     You can set any image for the backdrop by choosing <guimenuitem>Backdrop...</guimenuitem>
1415     from the pinboard menu (right-click over the desktop background when the pinboard is turned on).
1416    </para>
1417    <para>
1418     To set an image, select <guilabel>Centre</guilabel>, <guilabel>Scale</guilabel>,
1419     <guilabel>Stretch</guilabel> or <guilabel>Tile</guilabel> to set the style,
1420     and then drag an image onto the marked area.  To return to a solid colour
1421     backdrop (as set in the Options box), click on <guibutton>Clear</guibutton>.
1422    </para><para>
1423     The Wallpaper<citation>Wallpaper</citation> application can be used for more complicated
1424     effects, such as choosing a new random image each hour, or rendering an image of the Earth
1425     as it is currently lit by the sun.
1426    </para>
1427    <formalpara><title>For programmers...</title>
1428     <para>
1429      If you want to create an application to set the backdrop (eg, to choose a
1430      random image, or a slideshow) you need to first create an application directory
1431      (see <xref linkend="AppDir"/>).
1432     </para>
1433    </formalpara><para>
1434     When run without arguments, the application should invoke the
1435     <function>SetBackdropApp</function> SOAP method (see <xref
1436     linkend="soap"/>). The filer will immediately run the application again,
1437     this time with the <option>--backdrop</option> option.
1438    </para><para>
1439     When run with <option>--backdrop</option>, the program should write the style and name of
1440     the image file to display to its standard output stream, eg:
1441     <screen>tile /tmp/image.png</screen>
1442     <userinput>centre</userinput> and <userinput>scale</userinput> are the other possible
1443     styles. The filer will then load this image and display it. The application does not
1444     set the backdrop itself, it only tells the filer what to display.
1445    </para><para>
1446     In the case of a random backdrop chooser, the program may then quit immediately. If
1447     the application created a temporary image then it should read the line "ok\n" from its
1448     standard input before deleting the image.
1449    </para><para>
1450     If the application wishes to show a sequence of images it should still read "ok\n",
1451     then wait until it's time to display the next image and then write that filename, and
1452     so on.
1453    </para><para>
1454     The filer will indicate that the program should stop running by closing the two
1455     streams. The program should clean up and exit at this point. Be sure to catch
1456     SIGPIPE when writing to standard output if you need to delete any temporary files.
1457    </para><para>
1458     See the Wallpaper<citation>Wallpaper</citation> application for a complete example application
1459     (written in python).
1460    </para>
1461   </sect1>
1462  </chapter>
1464  <chapter>
1465   <title>
1466    <anchor id="media" xreflabel="Removable devices"/>Removable devices
1467   </title>
1468   <para>
1469    Using removable devices, such as floppy disks and CDROMs under ROX-Filer is quite
1470    simple. However, it is important to understand about <emphasis>mounting</emphasis> and
1471    <emphasis>unmounting</emphasis> devices.
1472   </para>
1473   <para>
1474    Mounting a device causes its contents to appear in the filesystem. On a typical setup,
1475    the directory <filename>/floppy</filename> is an empty directory on the hard disk.
1476    The floppy device is then mounted onto this directory, causing its contents to appear
1477    inside. For example, a file called <filename>Letter</filename> on the floppy disk will
1478    appear as <filename>/floppy/Letter</filename>.
1479   </para>
1480   <para>
1481    Devices must be unmounted before the disk is removed. Unmounting causes the system to
1482    write any buffered data to the disk. If you remove a disk without unmounting
1483    it, it will probably be corrupted. CD and Zip drives often lock the tray while the
1484    device is mounted so you can't remove it accidentally.
1485   </para>
1486   <para>
1487    So that you don't have to specify which device should be mounted at which point in the
1488    filesystem every time you want to use a disk, a preset list is usually found in the
1489    file <filename>/etc/fstab</filename>. ROX-Filer shows mount points (such as
1490    <filename>/floppy</filename>) which are listed here but not mounted with transparent
1491    grey circles overlayed on their icons.
1492   </para>
1493   <para>
1494    Clicking on one of these mount points will mount the device for you. The circle turns
1495    green to indicate that the device is now mounted. Do <emphasis>not</emphasis> remove
1496    the device while the circle is lit! You can unmount the device by clicking
1497    while holding down <keycap>Shift</keycap> on the <filename>/floppy</filename>
1498    directory icon.
1499   </para>
1500   <para>
1501    You can also unmount a device by closing its directory window (eg, closing
1502    the view of <filename>/floppy</filename>) and choosing Unmount when prompted. The
1503    filer will only offer to unmount devices this way if they were mounted by
1504    the filer in the first place.
1505   </para>
1506   <para>
1507    If you want to open a directory without mounting anything (eg, if you want to
1508    see the contents of <filename>/floppy</filename> on the hard disk), you can
1509    click on the unmounted mount point with <keycap>Shift</keycap> held down.
1510    This isn't usually useful, as these directories are typically empty.
1511   </para>
1512  </chapter>
1514  <chapter>
1515   <title><anchor id="thumbnails" xreflabel="Thumbnails"/>File thumbnails</title>
1516   <para>
1517     When thumbnailing is turned on, the filer tries to load every image file
1518     and use that image as the file's icon. Useful if you have a directory full
1519     of photos and can't remember which is which! You can turn it on for
1520     a single directory by choosing <guimenuitem>Show Thumbnails</guimenuitem>
1521     from the <guimenu>Display</guimenu> menu. You can set it as the default
1522     from the Options box.
1523     The titlebar shows <guilabel>(Thumbs)</guilabel> when thumbnailing is on.
1524   </para>
1525   <para>
1526     The thumbnails are saved in <filename>~/.thumbnails</filename> for
1527     quick loading next time.
1528     While loading thumbnails, a progress bar appears at the bottom of
1529     the window. Clicking on the <guibutton>Cancel</guibutton> button
1530     beside the bar stops the scan.
1531     It is also possible to thumbnail other types of file, such as videos
1532     (eg, by showing the first frame), with a suitable helper program.
1533   </para>
1534   <sect1><title>Technical details</title>
1535   <para>
1536 When in thumbnail mode <application>ROX-Filer</application> checks the
1537 thumbnail directory (<filename>~/.thumbs/normal</filename>) for a
1538 thumbnail for each file it scans. If a thumbnail exists it loads it and
1539 continues on to the next file.
1540   </para><para>
1541 To generate a thumbnail for a given file of type media/subtype the filer looks
1542 for a program <filename>~/.config/rox.sourceforge.net/MIME-thumb/media_subtype</filename>,
1543 falling back to <filename>~/.config/rox.sourceforge.net/MIME-thumb/media</filename> if one
1544 cannot be found (this duplicates how run actions for files are looked up). If
1545 neither file can be found and the file is of type image/* then the internal
1546 routines are used. If the file is not of type image/* then no thumbnail is
1547 generated.
1548   </para><para>
1549 If the generator program is found, is executed with the parameters
1550 <screen>thumbnailer /path/to/source/file /path/to/thumbnail pixel_size</screen>
1551   </para><para>
1552 Once the child program exits, it attempts to load
1553 <filename>/path/to/thumbnail</filename>. If that fails no thumbnail is
1554 displayed.
1555   </para><para>
1556 Note that because of the order it does things ROX-Filer will happily
1557 use any pre-existing thumbnail even if it has no idea how it was
1558 generated.
1559   </para>
1560   </sect1>
1562  </chapter>
1564  <chapter id="virtual">
1565   <title>
1566    <anchor id="vfs" xreflabel="Virtual file systems"/>Virtual file systems
1567   </title>
1568   <para>
1569    Some types of file can be represented as a directory. A typical example
1570    is a zip file, which contains an entire directory structure in compressed
1571    form. It is often useful to be able to open up such a file as if it
1572    was a real directory, and the VFS system allows you to do this.
1573   </para><para>
1574    To use this feature you must have a system such as
1575    AVFS<citation>AVFS</citation> installed, which causes the kernel to support
1576    various Virtual File Systems directly.
1577   </para>
1579  </chapter>
1581  <chapter id="minibuffer">
1582   <title><anchor id="mini" xreflabel="Minibuffer"/>The mini-buffer</title>
1583   <para>
1585    The mini-buffer is a white bar that appears along the bottom of the
1586    window and allows you to enter some text. Press <keycap>Escape</keycap> to
1587    get rid of it again. It behaves in different ways depending on how you
1588    invoked it:
1589   </para>
1591   <sect1>
1592    <title>The path-entry box</title>
1593    <para>
1595     This allows you to type in a path directly. As you type the display
1596     is updated to show the item entered visually. The main use is to find
1597     a file in a large directory quickly, but you can also use it for navigating
1598     between directories, or for selecting a full pathname from somewhere
1599     else and pasting it directly into the path-entry box.
1602     <informaltable><tgroup cols="2">
1603       <thead><row><entry>Key</entry><entry>Action</entry></row></thead>
1604       <tbody>
1606        <row><entry>
1607          <keycap>Return</keycap></entry><entry>
1608          Open the currently selected item.
1609        </entry></row>
1611        <row><entry>
1612          <keycap>Tab</keycap></entry><entry>
1613          Shell-style tab completion.
1614        </entry></row>
1616        <row><entry>
1617          <keycap>Up</keycap>, <keycap>Down</keycap></entry><entry>
1618          Select the previous/next matching entry.
1619        </entry></row>
1620     </tbody></tgroup></informaltable>
1622    </para>
1624    <para>
1625     If you start entering a name beginning with a `.' then the `Show Hidden'
1626     feature is temporarily turned on so that the file can be shown.
1627    </para>
1629    <para>
1630     Tab completion tries to fill in as many characters for you as it can.
1631     For example, if there are two files in a directory called 
1632     <filename>save-mail-nov-1999</filename> and
1633     <filename>save-mail-dec-1999</filename> then typing
1634     <userinput>save</userinput> and pressing <keycap>Tab</keycap> will expand
1635     <userinput>save</userinput> to <userinput>save-mail-</userinput> and beep
1636     to indicate that the match is not complete. If you use tab completion on a
1637     directory and it is unique then the filer will automatically change into
1638     the directory. This behavior should be familiar to shell users.
1639    </para>
1641    <informalexample><para>
1642      Let's say you want to locate the documentation for Wine in the directory
1643      <filename>/usr/share/doc</filename> (which is usually very large).
1644      Here's how you could do it:
1646      <orderedlist>
1648       <listitem><para>
1649         Open the minibuffer by choosing <guimenuitem>Enter
1650         Path...</guimenuitem> from the <guimenu>Window</guimenu> menu, or
1651         by pressing the slash (<keycap>/</keycap>) key.
1652       </para></listitem>
1654       <listitem><para>
1655         Press <keycap>CTRL</keycap>+<keycap>A</keycap> to select the existing
1656         contents.
1657       </para></listitem>
1659       <listitem><para>
1660         Type
1661         <userinput>u&lt;Tab&gt;sh&lt;Tab&gt;do&lt;Tab&gt;wi&lt;Tab&gt;</userinput>.
1662         As you type, the cursor will move to the correct subdirectory.
1663         If it beeps when you press <keycap>Tab</keycap> then you need to supply
1664         more letters, or press <keycap>Return</keycap>.
1665       </para></listitem>
1667      </orderedlist>
1669    </para></informalexample>
1670   </sect1>
1672   <sect1>
1673    <title>The shell command box</title>
1674    <para>
1676     This provides a quick way of entering shell commands if you don't
1677     want to open an xterm. If you don't know what shell commands are,
1678     skip this section!
1679     </para><para>
1680     Just type in the command and press <keycap>Return</keycap> to execute it.
1681     <keycap>Up</keycap> and <keycap>Down</keycap> arrows move through previously
1682     entered commands.
1683     <keycap>Tab</keycap> does shell-style completion.
1684     Clicking on an item inserts its name into the minibuffer.
1685     If some items are selected then they are assigned to the positional
1686     parameters <userinput>$1</userinput>, <userinput>$2</userinput>, etc.
1687     </para><para>
1688     Opening the minibuffer with a selection adds <computeroutput>"$@"</computeroutput>
1689     to the end of the command &mdash; this expands to all the selected files.
1690    </para>
1692    <informalexample><para>Examples:
1694      <orderedlist><title>To untar a <filename>.tgz</filename> archive:</title>
1696       <listitem><para>
1697         Open the minibuffer by choosing <guimenuitem>Shell Command...</guimenuitem> from
1698         the <guimenu>Window</guimenu> menu.
1699         I usually bind this to the bang (<keycap>!</keycap>) key.
1700       </para></listitem>
1702       <listitem><para>
1703         Type <userinput>tar xzf</userinput> and click on the file.
1704         The leading space is automatically inserted.
1705       </para></listitem>
1707       <listitem><para>
1708         Press <keycap>Return</keycap> to execute it.
1709       </para></listitem>
1711      </orderedlist>
1713      <orderedlist><title>To print all the selected files:</title>
1715       <listitem><para>
1716         Open the shell command minibuffer.
1717       </para></listitem>
1719       <listitem><para>
1720         Type <userinput>lpr</userinput> at the beginning of the line and press
1721         <keycap>Return</keycap>.
1722       </para></listitem>
1724      </orderedlist>
1726    </para></informalexample>
1728    <itemizedlist><title>Notes</title>
1730     <listitem><para>
1731       Be careful; you will not be asked to confirm! If in doubt, start the
1732       command with <userinput>xmessage</userinput> so that it will be displayed
1733       rather than executed.
1734     </para></listitem>
1736     <listitem><para>
1737       <citerefentry><refentrytitle>sh</refentrytitle></citerefentry>
1738       is always used as the name of the shell to run (mainly because
1739       <citerefentry><refentrytitle>bash</refentrytitle></citerefentry> and
1740       <citerefentry><refentrytitle>csh</refentrytitle></citerefentry> treat
1741       positional parameters differently).
1742       However, <envar>PATH</envar> is searched to find it so you can still use
1743       another shell if you want by naming it sh and putting it in your path.
1744     </para></listitem>
1746     <listitem><para>
1747       Commands execute in the background, so you can say:
1749       <command>sleep 240; xmessage Time to go!</command>
1750     </para></listitem>
1752    </itemizedlist>
1753   </sect1>
1755   <sect1>
1756    <title><anchor id="SelectIf" xreflabel="Select If"/>The conditional
1757     selection box</title> <para>
1759     Use this if you want to automatically select all files in the directory
1760     which match a condition.
1762     <orderedlist><title>For example, to select all files larger than 5Mb:</title>
1764      <listitem><para>
1765        Open the Select If minibuffer (bound to <keycap>?</keycap> by dafault).
1766      </para></listitem>
1768      <listitem><para>
1769        Type <userinput>Size &gt; 5Mb</userinput> and press <keycap>Return</keycap>.
1770      </para></listitem>
1772     </orderedlist>
1774     Just those files over 5 Mb in size will be selected. The expressions
1775     you can enter are in the same form as described in the
1776     <xref linkend="Searching"/> section, except that
1777     <userinput>prune</userinput> has no effect since the contents of
1778     directories are never checked anyway. You can press <keycap>Tab</keycap>
1779     to jump to each selected file in turn.
1781    </para>
1782   </sect1>
1783  </chapter>
1785  <chapter>
1786   <title>
1787    <anchor id="bulkrename" xreflabel="The Bulk Rename window"/>Renaming files in bulk
1788   </title>
1789   <para>
1790    If you have a large number of files to rename, it is tedious to rename them one
1791    by one. Instead, select all the files and choose <guimenuitem>Rename...</guimenuitem>
1792    from the menu to open the bulk rename window.
1793   </para>
1795   <para>
1796    The window shows a table with two columns. The <guilabel>Old name</guilabel> column
1797    shows the current name of each selected file, and the <guilabel>New name</guilabel>
1798    column shows the new name, which is initially the same.
1799   </para>
1801   <para>
1802    There are two ways to change the new names. You can edit the names in the table
1803    directly, or you can use the search and replace feature at the top of the window.
1804    This takes a regular expression to search for, and some text to replace matches
1805    with. For example, if you had a lot of files with names ending in
1806    <filename>.htm</filename> and you wanted to change them to use
1807    <filename>.html</filename>, you would enter <userinput>\.htm$</userinput> in
1808    the <guilabel>Replace:</guilabel> field and <userinput>.html</userinput> in the
1809    <guilabel>With:</guilabel> field. When you click <guibutton>Apply</guibutton>, the
1810    table is updated to show the proposed new names (but no actual renaming is done
1811    yet).
1812   </para>
1814   <para>
1815    Having checked that the new names look OK, click on the <guibutton>Rename</guibutton>
1816    button to actually perform the rename operation.
1817   </para>
1818  </chapter>
1820  <chapter id="actions">
1821   <title>Action windows</title>
1822   <para>
1823    Action windows are those boxes that appear while you're doing a
1824    Copy/Move/Link/etc operation. The status line at the top of the window shows
1825    the current directory or object that the window is processing. The scrolling
1826    area below is the log area &mdash; it shows what has been done, and questions
1827    may be displayed here.
1828    </para><para>
1829    Below this are four buttons and some options. All windows have the
1830    <guilabel>Quiet</guilabel> option. When this is on the filer will only
1831    confirm some operations (such as deleting a non-writeable file). Otherwise,
1832    all operations are confirmed.
1833    </para><para>
1834    The buttons work as follows:
1836    <variablelist>
1838     <varlistentry><term><guibutton>Yes</guibutton></term><listitem><para>
1839        answers yes to the question displayed in the log area.
1840     </para></listitem></varlistentry>
1842     <varlistentry><term><guibutton>No</guibutton></term><listitem><para>
1843        answers no to the question displayed in the log area.
1844     </para></listitem></varlistentry>
1846     <varlistentry><term><guibutton>Cancel</guibutton></term><listitem><para>
1847        kills the current operation (if any) and closes the action
1848        window.
1849     </para></listitem></varlistentry>
1851     <varlistentry><term><guibutton>Quiet</guibutton></term><listitem><para>
1852        is a quick way to turn <guilabel>Quiet</guilabel> on and click
1853        <guibutton>Yes</guibutton>.
1854     </para></listitem></varlistentry>
1857    </variablelist>
1859    You can control which actions get started automatically (without you
1860    having to click on <guibutton>Quiet</guibutton> at the start) from the
1861    Options window.
1862   </para>
1864   <sect1>
1865    <title>Action window options</title>
1866    <para>
1868     Some actions have options, which appear as option boxes at the bottom
1869     of the window. They are:
1871     <itemizedlist>
1873      <listitem><para>
1874        <guilabel>Force</guilabel> means that the filer won't treat non-writeable
1875        files as special.  Normally, it confirms the deletion even if
1876        <guibutton>Quiet</guibutton> is pressed.
1877        Note that you still can't remove files from non-writeable directories because
1878        in that case you really don't have permission.
1879      </para></listitem>
1881      <listitem><para>
1882        <guilabel>Brief</guilabel> prevents the filer logging a message every time it
1883        does something.  Use this to speed things up if large numbers of messages are
1884        being logged.
1885      </para></listitem>
1887      <listitem><para>
1888        <guilabel>Recurse</guilabel> means that doing something to a directory will
1889        also do the same thing to all its contents, and the contents of any
1890        subdirectories, and so on.
1891      </para></listitem>
1893      <listitem><para>
1894        <guilabel>Newer</guilabel> will automatically copy a file over an existing one
1895        if the file is newer than the one it replaces (later modification time).
1896      </para></listitem>
1898     </itemizedlist>
1899    </para>
1900    <para>
1901      You can set the defaults for these options from the Options box.
1902    </para>
1903   </sect1>
1904  </chapter>
1906  <chapter id="searching">
1907   <title><anchor id="Searching" xreflabel="Searching"/>Searching</title>
1908   <para>
1909    The Find feature looks through all the selected files and directories
1910    and any subdirectories (recursively) looking for items that match
1911    a particular expression.
1912    </para><para>
1913    Choose <guimenuitem>Find</guimenuitem> from the <guimenu>File</guimenu>
1914    submenu to search all the selected objects. If you want to select all the
1915    files within a single directory which meet certain criteria, use
1916    <guimenuitem>Select</guimenuitem> -> <guimenuitem>Select If...</guimenuitem>
1917    instead.
1918    </para><para>
1919    If you know the name of a file then just enter it in the `Expression:'
1920    box, enclosed in single quotes. For example, to find a file called
1921    <filename>log</filename> you would enter <userinput>'log'</userinput>.
1923    Remember to use normal quotes, not double quotes (") or back-quotes (`).
1924    </para><para>
1925    As the filer finds matching files they are added to the results list.
1926    Double-clicking on an entry in the list opens a viewer showing that file.
1927    The filer will use the same window to view other results (so, if you want
1928    the results shown in separate windows you must explicitly create a new
1929    window from the <guimenu>Window</guimenu> menu).
1930   </para>
1932   <sect1>
1933    <title>Wildcards</title>
1934    <para>
1936     You can also put shell-style wildcard characters inside the quotes,
1937     for example:
1939     <simplelist>
1941      <member><command>'*.html'</command></member>
1942      <member><command>'Report.*'</command></member>
1943      <member><command>'Draft[1-5]'</command></member>
1944      <member><command>'main.[ch]'</command></member>
1946     </simplelist>
1948     Look at the
1949     <citerefentry><refentrytitle>glob</refentrytitle>
1950      <manvolnum>7</manvolnum></citerefentry>
1951     manpage if you want to know more about shell wildcards.
1952     </para><para>
1953     If the pattern you enter contains a slash (`/') character then the
1954     pattern is matched against the file's full path, otherwise only the
1955     leafname is used. That is, <userinput>'*tmp*'</userinput> will find
1956     <filename>tmp</filename> and <filename>tmpfile</filename> but not
1957     <filename>/tmp/file</filename> &mdash; <userinput>'/*tmp*'</userinput> will find
1958     all three.
1959    </para>
1960   </sect1>
1962   <sect1>
1963    <title>Simple tests</title>
1964    <para>
1965     As well as finding files by their names you can also find them by
1966     various other attributes. Note that <emphasis>file</emphasis> is used here to
1967     mean anything that can appear in the filesystem &mdash; including directories,
1968     devices and so on.
1969     </para><para>
1970     You can also use a short form for each test; these are shown in brackets.
1971     You can combine multiple tests &mdash; `<userinput>-rw</userinput>' is
1972     the same as `<userinput>IsReadable and IsWriteable</userinput>'.
1973    </para>
1975    <itemizedlist><title>These look at the type of the item being checked:</title>
1977     <listitem><para>
1978       <userinput>IsReg (-f)</userinput> matches any regular (ie, normal) file.
1979     </para></listitem>
1981     <listitem><para>
1982       <userinput>IsLink (-l)</userinput> matches symlinks.
1983     </para></listitem>
1985     <listitem><para>
1986       <userinput>IsDir (-d)</userinput> matches directories.
1987     </para></listitem>
1989     <listitem><para>
1990       <userinput>IsChar (-c)</userinput> matches character device files.
1991     </para></listitem>
1993     <listitem><para>
1994       <userinput>IsBlock (-b)</userinput> matches block device files.
1995     </para></listitem>
1997     <listitem><para>
1998       <userinput>IsDev (-D)</userinput> matches block or character device files.
1999     </para></listitem>
2001     <listitem><para>
2002       <userinput>IsPipe (-p)</userinput> matches pipes.
2003     </para></listitem>
2005     <listitem><para>
2006       <userinput>IsSocket (-S)</userinput> matches sockets.
2007     </para></listitem>
2009     <listitem><para>
2010       <userinput>IsDoor (-O)</userinput> matches door objects (Solaris).
2011     </para></listitem>
2013    </itemizedlist>
2015    <itemizedlist><title>These look at the permissions set on the file &mdash;
2016      see the <xref linkend="Permissions"/> section.</title>
2018     <listitem><para>
2019       <userinput>IsSUID (-u)</userinput> matches files which have the Set-UID
2020       bit set.</para></listitem>
2022     <listitem><para>
2023       <userinput>IsSGID (-g)</userinput> matches files which have the Set-GID
2024       bit set.</para></listitem>
2026     <listitem><para>
2027       <userinput>IsSticky (-k)</userinput> matches files with the sticky bit
2028       set.</para></listitem>
2030     <listitem><para>
2031       <userinput>IsReadable (-r)</userinput> matches files which you can read
2032       from.</para></listitem>
2034     <listitem><para>
2035       <userinput>IsWriteable (-w)</userinput> matches files which you can write to.
2036     </para></listitem>
2038     <listitem><para>
2039       <userinput>IsExecutable (-x)</userinput> matches files which you can execute.
2040     </para></listitem>
2042    </itemizedlist>
2044    <itemizedlist><title>And a couple of other useful ones:</title>
2046     <listitem><para>
2047       <userinput>IsEmpty (-z)</userinput> finds empty files (ie, those whose
2048       length is 0 bytes).
2049     </para></listitem>
2051     <listitem><para>
2052       <userinput>IsMine (-o)</userinput> finds files which you own.
2053     </para></listitem>
2055    </itemizedlist>
2057   </sect1>
2059   <sect1>
2060    <title>Logic operators</title>
2061    <para>
2062     You can combine the above tests in various ways to perform more advanced
2063     searches.
2064     An expression is actually made up of a list of <emphasis>cases</emphasis>,
2065     separated by commas. The filer will try to match each case in turn
2066     until one matches or there are no more cases left. For example, to
2067     search for files with several possible endings:
2069     <screen>'*.gif', '*.htm', '*.html'</screen>
2071     Further, each of the cases is actually a list of conditions. The case
2072     only matches if all of its conditions are met. So, to find a directory
2073     called <filename>lib</filename> or a regular file ending in
2074     <filename>.so</filename>:
2076     <screen>IsDir 'lib', IsReg '*.so'</screen>
2078     You can negate a condition by putting a <userinput>!</userinput> in front
2079     of it and you can use a sub-expression as a condition by bracketing it,
2080     like this:
2082     <screen>
2083      !(IsDir, IsReg)
2085      !IsDir !IsReg
2087      Not isdir and not isreg
2089      !-d !-f</screen>
2090     All four do the same thing.
2091    </para>
2092   </sect1>
2094   <sect1>
2095    <title>Comparisons</title>
2096    <para>
2097     You can also compare various values using the operators
2098     <userinput>&lt;</userinput>,
2099     <userinput>&lt;=</userinput>,
2100     <userinput>=</userinput>,
2101     <userinput>!=</userinput>,
2102     <userinput>&gt;</userinput>, and
2103     <userinput>&gt;=</userinput>
2104     (for less-than, less-than-or-equal-to, equal-to,
2105     not-equal-to, greater-than and greater-than-or-equal-to).
2107     When comparing times, you may find it helpful to use
2108     <userinput>after</userinput> and <userinput>before</userinput> instead of
2109     <userinput>&gt;</userinput> and <userinput>&lt;</userinput> to make things
2110     clearer.
2111    </para>
2113    <itemizedlist><title>
2114      The following are read from the file being checked and may be used
2115      for the values being compared:
2116     </title>
2118     <listitem><para>
2119       <userinput>atime</userinput> The time that the file was last accessed.
2120     </para></listitem>
2122     <listitem><para>
2123       <userinput>ctime</userinput> The time that the file's status was last changed.
2124     </para></listitem>
2126     <listitem><para>
2127       <userinput>mtime</userinput> The time that the file's contents were last modified.
2128     </para></listitem>
2130     <listitem><para>
2131       <userinput>size</userinput> The size of the file.
2132     </para></listitem>
2134     <listitem><para>
2135       <userinput>inode</userinput> The file's inode (index) number.
2136     </para></listitem>
2138     <listitem><para>
2139       <userinput>nlinks</userinput> The number of links to this file. That is,
2140       the number of directory entries which refer to this file. Note that
2141       symlinks don't count as references.
2142     </para></listitem>
2144     <listitem><para>
2145       <userinput>uid</userinput> The User ID of the file.
2146     </para></listitem>
2148     <listitem><para>
2149       <userinput>gid</userinput> The Group ID of the file.
2150     </para></listitem>
2152     <listitem><para>
2153       <userinput>blocks</userinput> The number of disk blocks being used by the file.
2154     </para></listitem>
2156    </itemizedlist>
2158    <para>
2159     Times are measured as seconds since the Unix Epoch (00:00:00 UTC,
2160     January 1, 1970). Sizes are in bytes. When specifying constants to
2161     compare these values with you may use various keywords to scale the
2162     value:
2164     <itemizedlist>
2166      <listitem><para>
2167        <userinput>Byte(s)</userinput> has no effect, but looks better.
2168      </para></listitem>
2170      <listitem><para>
2171        <userinput>Kb</userinput> multiplies by 1024, so 2Kb is the same as 2048.
2172      </para></listitem>
2174      <listitem><para>
2175        <userinput>Mb</userinput> multiplies by 1024<superscript>2</superscript>,
2176        ie 1024 Kb.
2177      </para></listitem>
2179      <listitem><para>
2180        <userinput>Sec(s)</userinput> has no effect, but looks nice.
2181      </para></listitem>
2183      <listitem><para>
2184        <userinput>Min(s)</userinput> multiplies by 60 to get minutes.
2185      </para></listitem>
2187      <listitem><para>
2188        <userinput>Hour(s), Day(s), Week(s), Year(s)</userinput> likewise
2189        convert to the relevant unit.
2190      </para></listitem>
2192      <listitem><para>
2193        <userinput>Ago</userinput> makes the time in the past relative to when
2194        the check is done.
2195      </para></listitem>
2197      <listitem><para>
2198        <userinput>Hence</userinput> makes the time in the future.
2199      </para></listitem>
2201      <listitem><para>
2202        <userinput>Now</userinput> is short for <userinput>0 Secs Hence</userinput>.
2203      </para></listitem>
2205     </itemizedlist>
2207     Some examples should make this all a bit clearer!
2209     <screen>
2210      mtime after 1 day ago
2212      size &gt; 10 Mb
2214      IsReg and nlinks &gt; 1</screen>
2215     The first finds files modified within the last 24 hours. You could
2216     use <userinput>&gt;</userinput> instead of <userinput>after</userinput>,
2217     but it's not so clear what is meant.
2218     </para><para>
2219     The second finds files larger than 10 Mb. The last finds regular files with
2220     more than one directory entry.
2221     </para><para>
2222     Be careful though &mdash; the filer doesn't check the context of the
2223     modifiers, so <userinput>size &gt; 1 day ago</userinput> is allowed,
2224     although it doesn't make much sense!
2226     Also, forgetting to use <userinput>ago</userinput> or
2227     <userinput>hence</userinput> will cause odd effects (the time will be
2228     measured relative to the Epoch rather than the current time).
2229     Finally, don't use <userinput>=</userinput> with times &mdash;
2230     <userinput>atime = 1 day ago</userinput> looks for a file accessed
2231     <emphasis>exactly</emphasis> 86400 seconds ago...
2233    </para>
2234   </sect1>
2236   <sect1>
2237    <title>Specials</title>
2238    <para>
2240     <itemizedlist>
2242      <listitem><para>
2243        <userinput>System(Command)</userinput> executes `Command' on the file.
2244        The test succeeds if the command returns an exit status of zero. A `%'
2245        character in `Command' is replaced by the full path of the file being
2246        checked.  <userinput>System</userinput> is a very slow test to perform,
2247        so do it last if possible.  For example, if you're looking for a
2248        <filename>.c</filename> file containing the word `main', do:
2250        <screen>'*.c' system(grep -q main "%")</screen>
2251        so that the grep is only performed for files ending in <filename>.c</filename>
2252        (as opposed to only checking that the file ends in <filename>.c</filename> if
2253        it contains the word `main').
2254      </para></listitem>
2256      <listitem><para>
2257        <userinput>Prune</userinput> Always fails!
2258        <footnote><para>Note that this is the opposite of the
2259          <citerefentry><refentrytitle>find</refentrytitle><manvolnum>1</manvolnum>
2260        </citerefentry> command.</para></footnote>
2262        However, if it gets evaluated at all then it prevents the filer
2263        from checking inside the current directory. Remember the order in which
2264        the filer checks the expression!
2265      </para></listitem>
2267     </itemizedlist>
2269     Examples:
2271     <screen>
2272      '*.old' system(rm '%')
2274      'src' prune, '*.c'</screen>
2275     The first deletes each file ending in <filename>.old</filename>.
2276     The second looks for <filename>.c</filename> files, but does not bother
2277     checking inside directories called <filename>src</filename>.
2278     The expression is evaluated like this:
2279     </para><para>
2280     If file is named <filename>src</filename> then `Prune'.
2281     Either way, check if it ends in <filename>.c</filename> and include
2282     it in the results if so.
2283    </para>
2284   </sect1>
2285  </chapter>
2287  <chapter id="options">
2288   <title>Options</title>
2289   <para>
2291    You can configure various aspects of <application>ROX-Filer</application>
2292    from the Options box.
2293    Choose <guimenuitem>Options...</guimenuitem> from a filer window menu to
2294    open it. The list on the left of the window lists the various sections &mdash;
2295    click on one to see its options.
2297    At the bottom of the window are two buttons:
2299    <itemizedlist>
2301     <listitem><para>
2302       <guibutton>OK</guibutton>
2303       saves the current choices into your
2304       <filename>~/.config/rox.sourceforge.net/ROX-Filer</filename> directory for next time
2305       <application>ROX-Filer</application> is loaded, if anything changed.
2306       Exactly where choices are loaded from and saved to is controlled by the
2307       <envar>XDG_CONFIG_HOME</envar> environment variable &mdash; see
2308       <citation>BaseDir</citation> for details.
2309       Changes made in the Options box take effect instantly, so you don't need to
2310       click on <guibutton>OK</guibutton> just to try them out.
2311     </para></listitem>
2313     <listitem><para>
2314       <guibutton>Revert</guibutton>
2315       Restores all choices to how they were when the options box was opened.
2316       This button is shown shaded if you haven't made any changes.
2317       The Options window is not closed when this is used.
2318     </para></listitem>
2320    </itemizedlist>
2322    The options in the Options window have tooltips explaining the use of each
2323    option &mdash; hold the mouse pointer over an option to find out what it
2324    does.
2326   </para>
2327  </chapter>
2329  <chapter id="types">
2330   <title>Filetypes</title>
2331   <para>
2333    All files have a MIME type in the form <emphasis>text/plain</emphasis>. Here,
2334    <emphasis>text</emphasis> is the <emphasis>media type</emphasis> and
2335    <emphasis>plain</emphasis> is the <emphasis>sub-type</emphasis>.
2336    </para><para>
2337    <application>ROX-Filer</application> uses a file's name to decide what its MIME
2338    type is, and then uses the MIME type to decide what icon to give it and what
2339    program to use when you open the file.
2340   </para>
2342   <sect1>
2343    <title><anchor id="RunAction" xreflabel="the Set Run Action box"/>
2344     The Set Run Action box
2345    </title>
2346    <para>
2347     This box appears when you choose <guimenuitem>Set Run Action...</guimenuitem>
2348     from the File menu, and is used to set which application is loaded when you click
2349     on a file.
2350     </para><para>
2351     For example, let's say you want to set things up so that opening a
2352     <filename>.gif</filename> file loads it into the Gimp.
2353     First, right-click over a gif image to open the menu and choose
2354     <guimenuitem>Set Run Action...</guimenuitem> from the
2355     <guimenuitem>File</guimenuitem> submenu.
2356     Then, you have a choice of two methods to set the run action:
2357    </para>
2359    <sect2><title>Setting the run action by drag-and-drop</title>
2360     <para>
2361      Drag the Gimp (from a filer window, a panel or the pinboard) onto
2362      the area marked <guilabel>Drop a suitable application here</guilabel>.
2363      From now on, clicking on a GIF file will load it into the Gimp.
2364     </para>
2365    </sect2>
2367    <sect2><title>Setting the run action by entering a shell command</title>
2368     <para>
2369      Type: <userinput>gimp "$@"</userinput>
2370      into the box labelled <guilabel>Enter a shell command</guilabel> and press
2371      <keycap>Return</keycap>. <userinput>$@</userinput>
2372      will be replaced by the name of the file you click on when this command
2373      is used. As before, clicking on any GIF image will now load it into
2374      the Gimp.
2375     </para>
2376    </sect2>
2378    <sect2><title>Setting the default media-type handlers</title>
2379     <para>
2380      Whichever method you use to set the action you have the choice of
2381      setting the run action just for that type, or setting the default
2382      for all files with that media-type which don't already have a specific
2383      action.
2384      </para><para>
2385      Since the Gimp can load many types of image, it makes sense
2386      to select the <guilabel>Set default for all `image/&lt;anything&gt;'</guilabel>
2387      option so you don't have to do it again for image/jpeg files and so on. However,
2388      this only affects types that don't already have a specific action
2389      (ie, those that would have brought up an error box if you tried to
2390      open them).
2391     </para>
2392    </sect2>
2393   </sect1>
2395   <sect1>
2396    <title><anchor id="SetIcon" xreflabel="the Set Icon box"/>
2397     The Set Icon box
2398    </title>
2399    <para>
2401     This box appears when you choose <guimenuitem>Set Icon...</guimenuitem>
2402     from the File menu, and is used to set which image to use to represent
2403     the file.
2404     </para><para>
2405     It works much like the Set Run Action box described above, except that
2406     you may specifiy an icon for one file individually (by name) as well as
2407     for all files of a particular type. When setting the icon for a single
2408     file, the filer stores the name of the file and the name of the icon inside
2409     your <filename>~/.config/rox.sourceforge.net/MIME-icons</filename>
2410     directory. If either moves, the icon won't be displayed.
2411     </para><para>
2412     When setting the icon for a directory, you have the additional option of
2413     storing the image inside the directory itself as a hidden file. This means
2414     that other users will see the icon too, and you can safely delete the original
2415     image after the copy (note that the image is scaled down if needed, and converted
2416     to PNG format).
2417     </para><para>
2418     The directory icon inside the <guilabel>Drop an icon here</guilabel>
2419     area allows you to quickly get to a directory from which you are already
2420     using one or more icons.
2421    </para>
2422   </sect1>
2424   <sect1>
2425    <title>How filetypes are stored</title>
2426    <para>
2428     <application>ROX-Filer</application> uses two sub-directories in your
2429     <filename>~/.config/rox.sourceforge.net</filename> directory for filetypes:
2431     <variablelist>
2433      <varlistentry><term><filename>MIME-types</filename></term><listitem><para>
2434         contains symlinks, one for each MIME type, which point
2435         to programs that can handle files of that type. To set what program
2436         is run when you click on the file you should normally use the <guimenuitem>Set
2437          Run Action...</guimenuitem> feature (see the <xref linkend="RunAction"/> section).
2438         However, you can also set the actions manually &mdash; for example, to make
2439         opening an HTML file load it into Netscape:
2441         <orderedlist>
2442          <listitem><para>
2443            Find the Netscape application and go to <guimenuitem>Link...</guimenuitem>
2444            on the menu.
2445          </para></listitem>
2447          <listitem><para>
2448            Enter <userinput>text_html</userinput> as the name for the link and drag the
2449            icon from the Link box into the <filename>MIME-types</filename> directory.
2450          </para></listitem>
2452         </orderedlist>
2454         You can also put actual programs in here as well as links if you want
2455         to.
2456      </para></listitem></varlistentry>
2458      <varlistentry><term><filename>MIME-icons</filename></term><listitem><para>
2459         contains the images used to display each type of file.
2460         So the filer will try to display an HTML file using the icon
2461         <filename>MIME-icons/text_html.png</filename>. If no icon is set here,
2462         the filer will use the currently selected icon theme (as set in the options
2463         box); see <citation>IconTheme</citation> for details.
2464      </para></listitem></varlistentry>
2466     </variablelist>
2468     In <filename>MIME-types</filename> you can also provide default actions for each media type.
2469     For example, if <filename>text_html</filename> isn't found then the filer
2470     will try simply using <filename>text</filename>.
2471    </para>
2473   </sect1>
2475   <sect1>
2476    <title>How the filer determines a file's type</title>
2477    <para>
2478     The filer usually works out the type for a file from its name. If this fails,
2479     it tries to guess from the file's contents. It is possible to override this guessing
2480     by setting an extended attribute on the file with the correct type, using the
2481     <guimenuitem>Set Type...</guimenuitem> menu item.
2482    </para>
2483    <para>
2484     To edit the rules used to guess types, open the options box and go to the Types section.
2485     There is a button there that will launch the MIME-Editor application.
2486     You can also edit the rules manually &mdash; see <citation>SharedMIME</citation> for details.
2487    </para>
2488   </sect1>
2489  </chapter>
2491  <chapter id="appdirs">
2492   <title><anchor id="AppDir" xreflabel="Application directories"/>
2493    Application directories
2494   </title>
2495   <para>
2496    An application directory is a directory which can be run as an application.
2497    It contains all the resources of an application &mdash; source code, binaries,
2498    documentation and so on. Keeping everything in one place make installation
2499    and uninstallation much easier for users. You can also keep multiple
2500    versions of a program by simply having several application directories.
2501    You may move and rename them as you please. Application directories
2502    make programs easier to use and install.
2503    </para><para>
2504    They're more secure too, because you can compile an application as a user and
2505    then simply copy it as root. Since you don't have to run an install script
2506    you are free from the danger of running untrusted code as root. All you have
2507    to watch out for is setuid binaries.
2508    </para><para>
2510    The following files are treated as special by
2511    <application>ROX-Filer</application>:
2513    <itemizedlist>
2515     <listitem><para>
2516       <filename>AppRun</filename>
2517       is executed when you click on the directory &mdash; make sure
2518       it is executable (use the Permissions box)!
2519     </para></listitem>
2521     <listitem><para>
2522       <filename>.DirIcon</filename>
2523       is the image used to represent the directory (this works even if
2524       there is no <filename>AppRun</filename>).
2525     </para></listitem>
2527     <listitem><para>
2528       <filename>Help</filename>
2529       is the directory to be opened when you choose <guimenuitem>Help</guimenuitem>
2530       from the File menu.
2531     </para></listitem>
2533     <listitem><para>
2534       <filename>AppInfo.xml</filename>
2535       contains extra information about an application (see below).
2536     </para></listitem>
2538     <listitem><para>
2539       <filename>AppIcon.xpm</filename>
2540       is used if <filename>.DirIcon</filename> is missing (for backwards
2541       compatibility; not to be used anymore).
2542     </para></listitem>
2544    </itemizedlist>
2546    Have a look at the <filename>ROX-Filer</filename> application directory for a
2547    full example.
2549   </para>
2551   <note><para>For security reasons, an application directory must have the
2552     same owner as the <filename>AppRun</filename> file inside.</para></note>
2554   <sect1>
2555    <title>The AppInfo file</title>
2556    <para>
2558     <filename>AppInfo.xml</filename> is an XML file with the following structure
2559     (any elements may be omitted, and the file itself is optional):
2561     <screen>
2562 &lt;?xml version="1.0"?&gt;
2563 &lt;AppInfo&gt;
2564   &lt;Summary xml:lang="en"&gt;A graphical file manager&lt;/Summary&gt;
2565   &lt;Summary xml:lang="de"&gt;Ein grafische Datei-Manager&lt;/Summary&gt;
2566   &lt;Summary xml:lang="nl"&gt;Een grafisch bestandsbeheerprogramma&lt;/Summary&gt;
2567   &lt;Summary xml:lang="es"&gt;Un manejador de archivos gr&#xE1;afico&lt;/Summary&gt;
2568   &lt;About xml:lang="en"&gt;
2569     &lt;Purpose&gt;File manager&lt;/Purpose&gt;
2570     &lt;Version&gt;1.3.5 PREVIEW&lt;/Version&gt;
2571     &lt;Authors&gt;Thomas Leonard and others&lt;/Authors&gt;
2572     &lt;License&gt;GNU General Public License&lt;/License&gt;
2573     &lt;Homepage&gt;http://rox.sourceforge.net&lt;/Homepage&gt;
2574   &lt;/About&gt;
2575   &lt;About xml:lang="es"&gt;
2576     &lt;Purpose&gt;Manejador de Archivos&lt;/Purpose&gt;
2577     &lt;Authors&gt;Thomas Leonard y otros&lt;/Authors&gt;
2578   &lt;/About&gt;
2579   &lt;AppMenu&gt;
2580     &lt;Item option="-p=Default"&gt;
2581       &lt;Label&gt;Enable pinboard&lt;/Label&gt;
2582       &lt;Label xml:lang="es"&gt;Habilitar el pinboard&lt;/Label&gt;
2583     &lt;/Item&gt;
2584     &lt;Item option="-p="&gt;
2585       &lt;Label&gt;Disable pinboard&lt;/Label&gt;
2586       &lt;Label xml:lang="es"&gt;Deshabilitar el pinboard&lt;/Label&gt;
2587     &lt;/Item&gt;
2588   &lt;/AppMenu&gt;
2589 &lt;/AppInfo&gt;
2590 </screen>
2592     <itemizedlist>
2594      <listitem><para>
2595        <userinput>Summary</userinput>
2596        is displayed in a tooltip when the mouse is held over the application.
2597      </para></listitem>
2599      <listitem><para>
2600        <userinput>About</userinput>
2601        contains a list of fields which are shown in the `File Info'
2602        box for the application (any element names may be used, but the above
2603        are suggested).
2604      </para></listitem>
2606      <listitem><para>
2607        <userinput>AppMenu</userinput>
2608        is a list of extra menu items to display for the application.
2609        When one is chosen, <filename>AppRun</filename> is called with
2610        <userinput>option</userinput> as its only argument. You can nest
2611        AppMenus inside other AppMenus to create submenus, provided they have
2612        &lt;Label&gt; elements.
2613      </para></listitem>
2615     </itemizedlist>
2617    </para>
2618   </sect1>
2619  </chapter>
2621  <chapter id="i18n">
2622   <title>Internationalisation</title>
2623   <para>
2625   </para>
2627   <sect1>
2628    <title><anchor id="LANG" xreflabel="Translations"/>
2629     Selecting a translation
2630    </title>
2631    <para>
2633     <application>ROX-Filer</application> is able to translate many of its messages,
2634     provided suitable translation files are provided:
2636     <orderedlist>
2637      <listitem><para>Open the Options box from the menu,</para></listitem>
2638      <listitem><para>Select a language from the menu at the top,</para></listitem>
2639      <listitem><para>Click on <guibutton>Save</guibutton> and restart the filer
2640        for the new setting to take full effect.</para></listitem>
2641     </orderedlist>
2643    </para>
2644   </sect1>
2646   <sect1>
2647    <title>Creating a new translation</title>
2648    <para>
2650     <orderedlist>
2651      <listitem><para>Go into the <filename>src</filename> directory and create
2652        the file <filename>messages.pot</filename>:
2654        <screen>
2655         $ cd ROX-Filer/src
2656         $ make messages.pot</screen>
2658      </para></listitem>
2660      <listitem><para>Copy the file into the <filename>po</filename>
2661        subdirectory under <filename>src</filename> as
2662        <filename>&lt;name&gt;.po</filename>. Eg, if your
2663        language is referred to as `ml' (`my language'):
2665        <screen>$ cp messages.pot po/ml.po</screen>
2666      </para></listitem>
2668      <listitem><para>Load the copy into a text editor.</para></listitem>
2670      <listitem><para>Fill in the translations, which are all blank to start with.
2671      </para></listitem>
2673      <listitem><para>Run the <filename>make-mo</filename> script to create the
2674        binary file which <application>ROX-Filer</application> can use.
2675        You will need the GNU gettext package for this.
2676        If you don't have it then just send me the <filename>.po</filename> file
2677        and I'll convert it for you.
2679        <screen>
2680         $ cd ROX-Filer/src/po
2681         $ ./make-mo ml
2682         Created file ../../Messages/ml.gmo OK</screen>
2683      </para></listitem>
2685      <listitem><para>Edit <filename>ROX-Filer/Options.xml</filename> so that
2686        your language is listed, restart the filer and select it from the Options box
2687        (see the <xref linkend="LANG"/> section).
2688      </para></listitem>
2690      <listitem><para>Submit the <filename>.po</filename> file to me so that I
2691        can include it in future releases of the filer.
2692      </para></listitem>
2694     </orderedlist>
2695    </para>
2696   </sect1>
2698   <sect1>
2699    <title>Updating an existing translation</title>
2700    <para>
2702     <orderedlist>
2703      <listitem><para>Go into the directory containing the <filename>.po</filename>
2704        files and run the <filename>update-po</filename> script.
2705        This checks the source code for new and changed strings and updates all
2706        the translation files.
2708        <screen>
2709         $ cd ROX-Filer/src/po
2710         $ ./update-po</screen>
2711      </para></listitem>
2713      <listitem><para>Edit the file by hand as before, filling in the new blanks
2714        and updating out-of-date translations.
2715        Look out for <computeroutput>fuzzy</computeroutput> entries where
2716        <command>update-po</command> has made a guess; check it's correct and
2717        remove the <computeroutput>fuzzy</computeroutput> line.
2718      </para></listitem>
2720      <listitem><para>Run <command>make-mo</command> as before.</para></listitem>
2722      <listitem><para>Submit the updated file to me.</para></listitem>
2724     </orderedlist>
2726     See the <command>gettext</command> info page for more instructions on creating
2727     a translation.
2729    </para>
2730   </sect1>
2731  </chapter>
2733  <chapter id="hacking">
2734   <title>Hacking</title>
2735   <para>
2736    This is a quick start guide for people who want to modify the source
2737    code. If you make useful changes or fix bugs, please send patches
2738    to me or to the mailing list. Tell me which version you're using!
2739   </para>
2741   <sect1>
2742    <title>Compiling</title>
2743    <para>
2744     The first time you compile the program you need to do <command>AppRun
2745      --compile</command>, but in future you only need to run <command>make</command>
2746     in the <filename>src</filename> directory when you change the
2747     <filename>.c</filename> and <filename>.h</filename> files.
2748     You might want to run <command>make depend</command> too.
2749    </para>
2750   </sect1>
2752   <sect1>
2753    <title>Creating and applying patches</title>
2754    <para>
2755     When people make small modifications to the sources they will often
2756     distribute them as <emphasis>patch files</emphasis> &mdash; usually on the
2757     mailing list.
2759     To apply a patch, go into the <filename>src</filename> directory and run
2760     <command>patch</command> with the patch file. Then recompile, like this:
2762     <screen>
2763      $ cd ROX-Filer/src
2764      $ patch &lt; patchfile
2765      $ ../AppRun --compile</screen>
2767     You can remove the patch by simply repeating the above sequence &mdash;
2768     <command>patch</command> will detect that the patch is already applied
2769     and offer to remove it.
2770     </para><para>
2771     To create a patch you should first get the latest version of the filer
2772     from CVS (instructions on using CVS can be found on the web-site).
2773     Modify the program as you please. Create the patch using
2774     <command>cvs diff</command> from the appropriate directory:
2776     <screen>$ cvs diff -u &gt; my_patch</screen>
2778     This creates a human&ndash; and machine-readable patch file. Submit this
2779     to the mailing list. The are many reasons for posting patches rather
2780     that the modified files:
2782     <itemizedlist>
2783      <listitem><para>They are smaller, and hence shouldn't bounce.
2784        They are also quicker to download for people with slow connections.
2785      </para></listitem>
2787      <listitem><para>People can see what they're getting into before applying them!
2788      </para></listitem>
2790      <listitem><para>Patches can (usually) be applied to slightly modified
2791        versions of the sources. This means that people can apply several patches
2792        without each new one overwriting the others.
2793      </para></listitem>
2795     </itemizedlist>
2797    </para>
2798   </sect1>
2800   <sect1>
2801    <title>Autoconf</title>
2802    <para>
2803     Here's a quick explanation of the autoconf system in case you haven't
2804     used it before. See <command>info autoconf</command> for full details.
2805     </para><para>
2806     There's a file called <filename>configure.in</filename> which contains
2807     various tests (<command>info autoconf</command>).
2808     You run <command>autoconf</command> and it reads through the file
2809     and generates a shell script to perform the tests, saving it as
2810     <filename>configure</filename>.
2811     <filename>configure</filename> is normally distributed with the program because
2812     not everyone has autoconf.
2813     </para><para>
2814     You then run <filename>configure</filename> (in fact, let the
2815     <filename>AppRun</filename> script do it because
2816     it passes it some arguments), which performs all the tests. It reads
2817     in <filename>Makefile.in</filename> and <filename>config.h.in</filename>
2818     and fills in the missing values with the test results to produce
2819     <filename>Makefile</filename> and <filename>config.h</filename>.
2820     </para><para>
2821     You run <command>make</command>, which creates <filename>.o</filename>
2822     files from the <filename>.c</filename> files and links to produce
2823     <filename>ROX-Filer</filename>.
2824    </para>
2825   </sect1>
2827   <sect1><title>Data-structures</title>
2828    <para>
2829     The <filename>global.h</filename> file lists each major data-structure used
2830     in the filer and explains its purpose. This is a good place to start reading
2831     if you want to know how the filer works.
2832    </para>
2833   </sect1>
2834  </chapter>
2836  <appendix id="compiling">
2837   <title>Compiling</title>
2838   <para>
2840    If you've just got hold of the filer by downloading the source archive
2841    then you'll need to compile it before you can use it. If you downloaded
2842    and installed a binary package, or if <application>ROX-Filer</application>
2843    was included with your system, then you can skip this section. If you got
2844    here by clicking on the lifebelt symbol in a filer window, or if typing
2845    <command>rox</command> at a shell prompt works, then you don't need to
2846    compile.
2848    <itemizedlist><title>To compile, you will need the following:</title>
2850     <listitem><para>
2851       Unix or Linux (root access is not required),
2852     </para></listitem>
2854     <listitem><para>
2855       The X Window system (supplied as standard on all modern systems),
2856     </para></listitem>
2858     <listitem><para>
2859       GTK+ 2.4.0 or later (libraries and headers) &mdash; get the latest version
2860       from <citation>GTK+</citation>,
2861     </para></listitem>
2863     <listitem><para>
2864       LibXML 2.0.0 or later (libraries and headers) &mdash; get the latest
2865       version from <citation>libxml</citation>,
2866     </para></listitem>
2868     <listitem><para>
2869       A C compiler, such as `gcc' (standard on most systems).
2870     </para></listitem>
2872    </itemizedlist>
2874    All of the above are standard on most modern Linux distributions.
2875    To check which version of GTK+ you have installed, run the
2876    <command>pkg-config</command> command, like this
2877    (<prompt>$</prompt> is the shell prompt):
2879    <screen>$ pkg-config --modversion gtk+-2.0
2880 2.6.8</screen>
2881   </para>
2883   <procedure><title>To compile:</title>
2885    <step><para>
2886      The filer now uses the Shared MIME Database<citation>SharedMIME</citation>
2887      to work out the types of files. You need to install this before the
2888      filer will work properly (ROX-Filer will warn you if it's not installed
2889      when you run it).
2890    </para></step>
2892    <step><para>
2893      Change to the directory containing the ROX-Filer subdirectory.
2894    </para></step>
2896    <step><para>
2897      Run the <command>install.sh</command> script, like this:
2899      <screen>$ ./install.sh</screen>
2901    </para></step>
2903    <step><para>
2904      <application>ROX-Filer</application> will perform various checks to find
2905      out what kind of system it is being run on and will then compile. If it
2906      doesn't work then please e-mail me and complain! Tell me what kind of
2907      system you have and what errors were reported. If you manage to fix the
2908      problem yourself then please e-mail me the fix.
2909    </para></step>
2911    <step><para>
2912      Once the filer has compiled you will be asked where you want to install
2913      it. If you want to do a system-wide installation as root, you may
2914      want to stop here, <command>su</command> to root and rerun the install
2915      script.
2917      If you don't have the root password then don't worry &mdash; just follow
2918      the instructions for installing into your home directory.
2919    </para></step>
2920   </procedure>
2922   <para>
2923    You can now run the filer by running the <command>rox</command> script
2924    without any options, like this:
2926    <screen>$ rox</screen>
2928    A window should appear and display the contents of the current directory.
2930    If you installed the script into your home directory then you may
2931    need to set your <envar>PATH</envar> environment variable so that the shell can
2932    find it. For example, if you installed it into a directory called
2933    <filename>bin</filename> in your home directory, use this:
2935    <screen>$ PATH=$HOME/bin:$PATH; export PATH</screen>
2937    or (if you are using the <citerefentry><refentrytitle>csh</refentrytitle>
2938     <manvolnum>1</manvolnum></citerefentry> shell):
2940    <screen>$ setenv PATH $HOME/bin:$PATH
2941 $ rehash</screen>
2943   </para>
2945  </appendix>
2947  <appendix id="manpage"><title>Manual page</title>
2949   <refentry id="rox">
2951    <refmeta>
2952     <refentrytitle>ROX</refentrytitle>
2953     <manvolnum>1</manvolnum>
2954    </refmeta>
2956    <refnamediv>
2957     <refname>ROX-Filer</refname>
2958     <refpurpose>a simple graphical file manager</refpurpose>
2959    </refnamediv>
2961    <refsynopsisdiv>
2962     <cmdsynopsis>
2963      <command>rox</command>
2964      <arg choice="opt" rep="repeat"><option>OPTION</option></arg>
2965      <arg choice="opt" rep="repeat">FILE</arg>
2966     </cmdsynopsis>
2967    </refsynopsisdiv>
2969    <refsect1><title>DESCRIPTION</title>
2970     <para>
2971      ROX-Filer is a simple and easy to use graphical file manager for X11, the
2972      windowing system used on Unix and Unix-like operating systems.
2973      </para><para>
2974      It is also the core component of the ROX Desktop:
2975      <ulink url="http://rox.sourceforge.net"/>
2976      </para><para>
2977      Invoking <command>rox</command> opens each directory or file listed,
2978      or the current working directory if no arguments are given.
2979     </para>
2980    </refsect1>
2982    <refsect1><title>COMMAND-LINE OPTIONS</title>
2983     <para>
2984      <variablelist>
2986       <varlistentry><term><option>-b</option></term><term><option>--border=PANEL</option></term>
2987        <listitem><para>open PANEL.
2988       </para></listitem></varlistentry>
2990       <varlistentry><term><option>-B</option></term><term><option>--bottom=PANEL</option></term>
2991        <listitem><para>open PANEL as a bottom-edge panel.
2992       </para></listitem></varlistentry>
2994       <varlistentry><term><option>-c</option></term><term><option>--client-id=ID</option></term>
2995        <listitem><para>used for session management.
2996       </para></listitem></varlistentry>
2998       <varlistentry><term><option>-d</option></term><term><option>--dir=DIR</option></term>
2999        <listitem><para>open DIR as directory (not as an application, even if it looks like one).
3000       </para></listitem></varlistentry>
3002       <varlistentry><term><option>-D</option></term><term><option>--close=DIR</option></term>
3003        <listitem><para>close DIR and all its subdirectories.
3004       </para></listitem></varlistentry>
3006       <varlistentry><term><option>-h</option></term><term><option>--help</option></term>
3007        <listitem><para>display help about the various options.
3008       </para></listitem></varlistentry>
3010       <varlistentry><term><option>-l</option></term><term><option>--left=PANEL</option></term>
3011        <listitem><para>open PANEL as a left-edge panel.
3012       </para></listitem></varlistentry>
3014       <varlistentry><term><option>-m</option></term><term><option>--mime-type=FILE</option></term>
3015        <listitem><para>print MIME type of FILE and exit.
3016       </para></listitem></varlistentry>
3018       <varlistentry><term><option>-n</option></term><term><option>--new</option></term>
3019       <listitem><para>start a new filer, even if one already seems to be
3020       running. This also prevents the filer from forking (running in the
3021       background). This option is mainly useful for debugging.
3022       </para></listitem></varlistentry>
3024       <varlistentry><term><option>-p</option></term><term><option>--pinboard=PIN</option></term>
3025        <listitem><para>use pinboard PIN as the pinboard.
3026       </para></listitem></varlistentry>
3028       <varlistentry><term><option>-r</option></term><term><option>--right=PANEL</option></term>
3029        <listitem><para>open PANEL as a right-edge panel.
3030       </para></listitem></varlistentry>
3032       <varlistentry><term><option>-R</option></term><term><option>--RPC</option></term>
3033        <listitem><para>read and invoke SOAP RPC from standard input (see <xref linkend="soap"/>).
3034       </para></listitem></varlistentry>
3036       <varlistentry><term><option>-s</option></term><term><option>--show=FILE</option></term>
3037        <listitem><para>open a directory showing FILE.
3038       </para></listitem></varlistentry>
3040       <varlistentry><term><option>-S</option></term><term><option>--rox-session</option></term>
3041        <listitem><para>run under ROX-Session, open the default panel and pinboard (implies --new).
3042       </para></listitem></varlistentry>
3044       <varlistentry><term><option>-t</option></term><term><option>--top=PANEL</option></term>
3045        <listitem><para>open PANEL as a top-edge panel.
3046       </para></listitem></varlistentry>
3048       <varlistentry><term><option>-u</option></term><term><option>--user</option></term>
3049        <listitem><para>show user name in each window.
3050       </para></listitem></varlistentry>
3052       <varlistentry><term><option>-v</option></term><term><option>--version</option></term>
3053        <listitem><para>display the version information and exit.
3054       </para></listitem></varlistentry>
3056       <varlistentry><term><option>-x</option></term><term><option>--examine=FILE</option></term>
3057        <listitem><para>FILE has changed; re-examine it.
3058       </para></listitem></varlistentry>
3060      </variablelist>
3061     </para>
3062    </refsect1>
3064    <refsect1><title>NOTES</title>
3065     <para>
3066      The main documentation for ROX-Filer is available by choosing
3067      <guimenuitem>Show Help Files</guimenuitem> from the
3068      popup menu, or by clicking on the right-most toolbar icon.
3069     </para>
3070    </refsect1>
3072    <refsect1><title>LICENSE</title>
3073     <para>Copyright (C) 2004 Thomas Leonard.
3074      </para><para>
3075      You may redistribute copies of ROX-Filer under the terms of the GNU General
3076      Public License.
3077     </para>
3078    </refsect1>
3080    <refsect1><title>BUGS</title>
3081     <para>
3082      Please report bugs to the developer mailing list: <ulink url="http://rox.sourceforge.net/contact.html"/>.
3083     </para>
3084    </refsect1>
3086    <refsect1><title>AUTHORS</title>
3087     <para>
3088      ROX-Filer was created by Thomas Leonard, with help from:
3089      </para><para>
3090      <simplelist columns='3'>
3091       <member>Michael Adams</member>
3092       <member>Christopher Arndt</member>
3093       <member>Jens Askengren</member>
3094       <member>Liav Asseraf</member>
3095       <member>Wilbert Berendsen</member>
3096       <member>Francesco Bochicchio</member>
3097       <member>Yuri Bongiorno</member>
3098       <member>Andrzej Borsuk</member>
3099       <member>Richard Boulton</member>
3100       <member>Simon Britnell</member>
3101       <member>Arnaud Calvo</member>
3102       <member>Babyfai Cheung</member>
3103       <member>Andrew Clover</member>
3104       <member>Fabien Coutant</member>
3105       <member>Couderc Damien</member>
3106       <member>Andreas Dehmel</member>
3107       <member>Micah Dowty</member>
3108       <member>Dmitry Elfimov</member>
3109       <member>Mattias Engdegard</member>
3110       <member>Andrew Flegg</member>
3111       <member>Olivier Fourdan</member>
3112       <member>Eric Gillespie</member>
3113       <member>Thierry Godefroy</member>
3114       <member>Olli Helenius</member>
3115       <member>Alex Holden</member>
3116       <member>Jasper Huijsmans</member>
3117       <member>Sigve Indregard</member>
3118       <member>Bernard Jungen</member>
3119       <member>Marcin Juszkiewicz</member>
3120       <member>James Kermode</member>
3121       <member>Jim Knoble</member>
3122       <member>Krzysztof Krzyzaniak</member>
3123       <member>Aaron Kurtz</member>
3124       <member>Vincent Ledda</member>
3125       <member>Vincent Lefevre</member>
3126       <member>Victor Liu See-le</member>
3127       <member>Alexey Lubimov</member>
3128       <member>Krzysztof Luks</member>
3129       <member>Marcus Lundblad</member>
3130       <member>Anders Lundmark</member>
3131       <member>Jose Romildo Malaquias</member>
3132       <member>Denis Manente</member>
3133       <member>Brendan McCarthy</member>
3134       <member>Andras Mohari</member>
3135       <member>Christiansen Merel</member>
3136       <member>Jimmy Olgeni</member>
3137       <member>Richard Olsson</member>
3138       <member>Matthew O'Phinney</member>
3139       <member>Daniele Peri</member>
3140       <member>Andy Piper</member>
3141       <member>Marcelo Ramos</member>
3142       <member>Michel Alexandre Salim</member>
3143       <member>Adam Sampson</member>
3144       <member>Chris Sawer</member>
3145       <member>Christian Storgaard</member>
3146       <member>Taras</member>
3147       <member>Simon Truss</member>
3148       <member>Hirosi Utumi</member>
3149       <member>Jan Wagemakers</member>
3150       <member>Keith Warno</member>
3151       <member>Götz Waschk</member>
3152       <member>Stephen Watson</member>
3153       <member>Andre Wyrwa</member>
3154       <member>Geoff Youngs</member>
3155       <member>Diego Zamboni</member>
3156      </simplelist>
3157      </para><para>
3158      and many others; the <filename>Changes</filename> file contains more
3159      detailed information!
3160     </para>
3161    </refsect1>
3163   </refentry>
3164  </appendix>
3166  <appendix id="soap"><title>SOAP RPC</title>
3168   <para>When the filer starts you can use command-line options to control its behaviour.
3169    As an alternative to this, the filer allows you to specify an operation with a
3170    <citation>SOAP</citation> RPC format message. In fact, if you use the command-line options,
3171    the filer converts to SOAP RPC internally.
3172   </para>
3174   <para>All SOAP RPC messages are passed on standard input, like this:
3176    <screen>
3177 $ rox --RPC &lt;&lt; EOF
3178 &lt;?xml version="1.0"?&gt;
3179 &lt;env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope"&gt;
3180  &lt;env:Body xmlns="http://rox.sourceforge.net/SOAP/ROX-Filer"&gt;
3181   &lt;Panel&gt;
3182    &lt;Name&gt;Default&lt;/Name&gt;
3183    &lt;Side&gt;Bottom&lt;/Side&gt;
3184   &lt;/Panel&gt;
3185  &lt;/env:Body&gt;
3186 &lt;/env:Envelope&gt;
3187 EOF</screen>
3189    The following methods are recognised:</para>
3191   <itemizedlist>
3193    <listitem><para><function>Version</function>()
3194      Returns the filer's version.
3195    </para></listitem>
3197    <listitem><para><function>CloseDir</function>(<parameter>Filename</parameter>)
3198      Close directory <parameter>Filename</parameter> and all its subdirectories.
3199    </para></listitem>
3201    <listitem><para><function>Examine</function>(<parameter>Filename</parameter>)
3202      <parameter>Filename</parameter> may have changed &mdash; check it and
3203      update the display.
3204    </para></listitem>
3206    <listitem><para><function>OpenDir</function>(<parameter>Filename</parameter>,
3207      [<parameter>Style</parameter>, <parameter>Details</parameter>, <parameter>Sort</parameter>,
3208      <parameter>Class</parameter>, <parameter>ID</parameter>],
3209      <parameter>Hidden</parameter>, <parameter>Filter</parameter>)
3210      Open a window showing directory <parameter>Filename</parameter>.
3211      <parameter>Style</parameter> is one of <userinput>Large</userinput>, <userinput>Small</userinput>, <userinput>Huge</userinput>
3212      or <userinput>Automatic</userinput>.
3213      <parameter>Details</parameter> is one of <userinput>None</userinput>, <userinput>ListView</userinput>, <userinput>Size</userinput>, <userinput>Type</userinput>, <userinput>Times</userinput> or <userinput>Permissions</userinput>.
3214      <parameter>Sort</parameter> is one of <userinput>Name</userinput>, <userinput>Type</userinput>, <userinput>Date</userinput>, <userinput>Size</userinput>,
3215 <userinput>Owner</userinput> or <userinput>Group</userinput>.
3216      If any of these three option parameters are missing, the default is used.
3217      <parameter>Class</parameter> can be used to set the WM_CLASS property on the new window. You can
3218      use this to get your window manager to treat the window
3219 specially.
3220      <parameter>ID</parameter> is a string used to identify the 
3221 opened window. If a window with this ID already exists, it is changed to the
3222 given directory. Otherwise, a new window is created and given this ID.
3223 If used from a program, ensure the IDs you generate are unique, for example
3224 by including your process name, PID and a timestamp in the ID.
3225 <parameter>Hidden</parameter> if <userinput>true</userinput> means
3226 that hidden files (those that start with a dot character) are shown,
3227 or not shown if <userinput>false</userinput>.  If ommitted then the 
3228 configured setting is used.
3229 <parameter>Filter</parameter> can be used to filter files shown by
3230 their name.  For example using a filter of <userinput>*.c</userinput>
3231 means that only files ending in .c are shown.
3232    </para></listitem>
3234    <listitem><para><function>Panel</function>(<parameter>Side</parameter>,
3235      [<parameter>Name</parameter>])
3236      Open the panel named <parameter>Name</parameter> on screen side
3237      <parameter>Side</parameter> (<userinput>Top</userinput>|<userinput>Bottom</userinput>|<userinput>Left</userinput>|<userinput>Right</userinput>).
3238      <parameter>Name</parameter> can be a name in <filename>~/.config/rox.sourceforge.net/ROX-Filer</filename>
3239      (eg, <userinput>MyPanel</userinput>) or a full pathname.
3240      If not given, the panel on that side is turned off.
3241    </para></listitem>
3243    <listitem><para><function>PanelAdd</function>(<parameter>Side</parameter>,
3244      <parameter>Path</parameter>, [<parameter>Label</parameter>,
3245      <parameter>After</parameter>, <parameter>Shortcut</parameter>, <parameter>Args</parameter>])
3246      Add <parameter>Path</parameter> to the panel on side <parameter>Side</parameter>,
3247      with label <parameter>Label</parameter>. If <parameter>After</parameter> is
3248      <userinput>true</userinput> the icon goes on the right/bottom side of the panel,
3249      otherwise on the left/top side.  If <parameter>Shortcut</parameter>
3250 is given it is the keyboard shortcut to trigger this item.  If
3251 <parameter>Args</parameter> is given it is the argument string to
3252 append to the item when run if it is a program.
3253    </para></listitem>
3255    <listitem><para><function>PanelRemove</function>(<parameter>Side</parameter>,
3256      <parameter>Path</parameter>, [<parameter>Label</parameter>])
3257      Remove <parameter>Path</parameter> from the panel on side
3258 <parameter>Side</parameter>. If <parameter>Label</parameter> is given
3259 then this must match the label of the item.  If more than one item matches, only one is removed.
3260    </para></listitem>
3262    <listitem><para><function>Pinboard</function>([<parameter>Name</parameter>])
3263      Display pinboard <parameter>Name</parameter> on the desktop background.
3264      <parameter>Name</parameter> can be a name in  <filename>~/.config/rox.sourceforge.net/ROX-Filer</filename>
3265      (eg, <userinput>MyPinboard</userinput>) or a full pathname.
3266      If not given, the pinboard is turned off.
3267    </para></listitem>
3269    <listitem><para><function>PinboardAdd</function>(<parameter>Path</parameter>,
3270      <parameter>X</parameter>, <parameter>Y</parameter>,
3271 [<parameter>Label</parameter>, <parameter>Shortcut</parameter>, <parameter>Args</parameter>])
3272      Add <parameter>Path</parameter> to the pinboard at position
3273      (<parameter>X</parameter>, <parameter>Y</parameter>), giving it
3274 the (optional) label
3275      <parameter>Label</parameter>.  If <parameter>Shortcut</parameter>
3276 is given it is the keyboard shortcut to trigger this item.  If
3277 <parameter>Args</parameter> is given it is the argument string to
3278 append to the item when run if it is a program.
3279    </para></listitem>
3281    <listitem><para><function>PinboardRemove</function>(<parameter>Path</parameter>, [<parameter>Label</parameter>])
3282      Remove <parameter>Path</parameter> from the pinboard. If <parameter>Label</parameter> is given
3283 then this must match the label of the item.  If more than one item matches, only one is removed.
3284    </para></listitem>
3286    <listitem><para><function>SetBackdropApp</function>(<parameter>App</parameter>)
3287      Make <parameter>App</parameter> (an application directory) the new handler
3288      for the current pinboard's backdrop.
3289      The <filename>AppInfo.xml</filename> file inside <parameter>App</parameter>
3290      must contain the CanSetBackdrop element, eg:
3291      <programlisting>
3292 &lt;?xml version="1.0"?&gt;
3293 &lt;AppInfo&gt;
3294       &lt;ROX:CanSetBackdrop xmlns:ROX="http://rox.sourceforge.net/SOAP/ROX-Filer"/>
3295 &lt;/AppInfo&gt;</programlisting>
3296      The application will be run with the <option>--backdrop</option> option
3297      as it's only argument after invoking this method, and whenever the pinboard is
3298      reloaded. DO NOT use this method if invoked with <option>--backdrop</option> or
3299      you will get stuck in an infinite loop!
3300      See <xref linkend="backdropapp"/> for a guide to writing backdrop applications.
3301    </para></listitem>
3303    <listitem><para><function>SetBackdrop</function>(<parameter>Filename</parameter>,
3304    <parameter>Style</parameter>)
3305    Set the backdrop image to a given file. If you want to regenerate the image next
3306    time the user logs in, or you want to change it automatically from time to time,
3307    use <function>SetBackdropApp</function> above instead.
3308    </para></listitem>
3310    <listitem><para><function>Run</function>(<parameter>Filename</parameter>)
3311      Run <parameter>Filename</parameter> as if it was clicked on in the filer.
3312    </para></listitem>
3314    <listitem><para><function>Show</function>(<parameter>Directory</parameter>,
3315      <parameter>Leafname</parameter>)
3316      Open <parameter>Directory</parameter> and flash the file
3317      <parameter>Leafname</parameter> inside it.
3318    </para></listitem>
3320    <listitem><para><function>FileType</function>(<parameter>Filename</parameter>)
3321      Returns the MIME-type of <parameter>Filename</parameter> (by writing the
3322      SOAP response to standard output).
3323    </para></listitem>
3324   </itemizedlist>
3326   <para>
3327    The following calls can be used to start new file actions.
3328    <parameter>Quiet</parameter> can be <userinput>true</userinput> if the
3329    operation should start immediately, instead of waiting for the user to
3330    confirm. If <userinput>false</userinput>, the user must always confirm. If
3331    not given, the default setting is used.
3332   </para>
3334   <itemizedlist>
3335    <listitem><para><function>Copy</function>(<parameter>From</parameter>,
3336      <parameter>To</parameter>, [<parameter>Leafname</parameter>,
3337      <parameter>Quiet</parameter>])
3338      Copy each file in the array <parameter>From</parameter> to the directory
3339      <parameter>To</parameter>. If <parameter>Leafname</parameter> is given
3340      then <parameter>From</parameter> should contain a single entry only;
3341      <parameter>Leafname </parameter> gives the new leafname.
3342    </para></listitem>
3344    <listitem><para><function>Move</function>(<parameter>From</parameter>,
3345      <parameter>To</parameter>, [<parameter>Leafname</parameter>,
3346      <parameter>Quiet</parameter>])
3347      Move each file in the array <parameter>From</parameter> to the directory
3348      <parameter>To</parameter>. If <parameter>Leafname</parameter> is given
3349      then <parameter>From</parameter> should contain a single entry only;
3350      <parameter>Leafname</parameter> gives the new leafname.
3351    </para></listitem>
3353    <listitem><para><function>Link</function>(<parameter>From</parameter>,
3354      <parameter>To</parameter>, [<parameter>Leafname</parameter>])
3355      Symlink each file in the array <parameter>From</parameter> to the
3356      directory <parameter>To</parameter>. If <parameter>Leafname</parameter> is
3357      given then <parameter>From</parameter> should contain a single entry only;
3358      <parameter>Leafname</parameter> gives the new leafname.
3359    </para></listitem>
3361    <listitem><para><function>Mount</function>(<parameter>MountPoints</parameter>,
3362      [<parameter>OpenDir</parameter>, <parameter>Quiet</parameter>])
3363      Mount each directory in the list <parameter>MountPoints</parameter>. If
3364      <userinput>true</userinput>, <parameter>OpenDir</parameter> causes each
3365      directory to be opened once it is mounted.
3366    </para></listitem>
3369    <listitem><para><function>Unmount</function>(<parameter>MountPoints</parameter>,
3370      [<parameter>Quiet</parameter>])
3371      Unmount each directory in the list <parameter>MountPoints</parameter>.
3372    </para></listitem>
3374   </itemizedlist>
3376  </appendix>
3378  <bibliography>
3379   <title>References</title>
3381   <bibliomixed>
3382    <abbrev>ROX</abbrev><citetitle>The ROX desktop,
3383     <ulink url="http://rox.sourceforge.net"/></citetitle>
3384   </bibliomixed>
3386   <bibliomixed>
3387    <abbrev>RISC OS</abbrev><citetitle>RISC OS,
3388     <ulink url="http://www.riscos.com"/></citetitle>
3389   </bibliomixed>
3391   <bibliomixed>
3392    <abbrev>GTK+</abbrev><citetitle>GTK+ Toolkit,
3393     <ulink url="http://www.gtk.org"/></citetitle>
3394   </bibliomixed>
3396   <bibliomixed>
3397    <abbrev>libxml</abbrev><citetitle>The XML C library for Gnome
3398     <ulink url="http://www.xmlsoft.org"/></citetitle>
3399   </bibliomixed>
3401   <bibliomixed>
3402    <abbrev>GNOME</abbrev><citetitle>The GNOME desktop,
3403     <ulink url="http://www.gnome.org"/></citetitle>
3404   </bibliomixed>
3406   <bibliomixed>
3407    <abbrev>DND</abbrev><citetitle>The Drag and Drop protocol,
3408     <ulink url="http://www.newplanetsoftware.com/xdnd/"/></citetitle>
3409   </bibliomixed>
3411   <bibliomixed>
3412    <abbrev>XDS</abbrev><citetitle>The X Direct Save protocol,
3413     <ulink url="http://www.newplanetsoftware.com/xds/"/></citetitle>
3414   </bibliomixed>
3416   <bibliomixed>
3417    <abbrev>BaseDir</abbrev><citetitle>The freedesktop.org base directory system,
3418     <ulink url="http://www.freedesktop.org/wiki/Standards_2fbasedir_2dspec"/></citetitle>
3419   </bibliomixed>
3421   <bibliomixed>
3422    <abbrev>AVFS</abbrev><citetitle>AVFS - A Virtual File System,
3423     <ulink url="http://sourceforge.net/projects/avf/"/></citetitle>
3424   </bibliomixed>
3426   <bibliomixed>
3427    <abbrev>SOAP</abbrev><citetitle>Simple Object Access Protocol (SOAP) 1.2
3428     <ulink url="http://www.w3.org/TR/SOAP/"/></citetitle>
3429   </bibliomixed>
3431   <bibliomixed>
3432    <abbrev>Thumbs</abbrev><citetitle>Thumbnail Managing Standard (Version 0.5)
3433     <ulink url="http://triq.net/~jens/thumbnail-spec/"/></citetitle>
3434   </bibliomixed>
3436   <bibliomixed>
3437    <abbrev>Wallpaper</abbrev><citetitle>Wallpaper backdrop control application
3438     <ulink url="http://rox.sourceforge.net/phpwiki/index.php/Wallpaper"/></citetitle>
3439   </bibliomixed>
3441   <bibliomixed>
3442    <abbrev>SharedMIME</abbrev><citetitle>Shared MIME-info Database (Version 0.16)
3443     <ulink url="http://www.freedesktop.org/wiki/Standards_2fshared_2dmime_2dinfo_2dspec"/></citetitle>
3444   </bibliomixed>
3446   <bibliomixed>
3447    <abbrev>IconTheme</abbrev><citetitle>The freedesktop.org Icon Theme specification
3448     <ulink url="http://www.freedesktop.org/wiki/Standards_2ficon_2dtheme_2dspec"/></citetitle>
3449   </bibliomixed>
3451  </bibliography>
3453 </book>