<chapter id="intro/index">
  <title>Introduction to Director</title>
  <section id="intro/intro">
    <title>Introduction to Director</title>
    <variablelist>
      <varlistentry>
        <term>Purpose</term>
          <listitem><para>Desktop utility</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>Version</term>
          <listitem><para>0.36</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>Author</term>
          <listitem><para>The RISC OS Director developers,  2003</para></listitem>
      </varlistentry>
    </variablelist>
    <para>Director is a general purpose desktop tool. It allows you to customise your desktop by creating menus of useful commands and icons to attach the menus to. Any number of menus or icons can be created and attached in any order to each other.</para>
    <para>Director also allows an alternative and faster view onto files in the form of directory menus and allows these menus to be attached to other menus also.</para>
    <para>Director has some other useful features such as remembering the most recently used files, the ability to add key strokes into the keyboard buffer and the ability to produce directory menus over drive icons.</para>
    <para>Director is fully customizable by the user, and can do many or all of the functions of <application>Pinboard+</application>, <application>TreeMenu</application> (also known as <application>DirMenu</application>), <application>Filer-</application>, <application>QuickDir</application>, <application>DeskUtils</application>, <application>Memorizer, </application>Menon and some of the functions of <application>Filer+</application>.</para>
  </section>

  <section id="intro/download">
    <title>Downloading Director</title>
    <para>Director has a website a <ulink url="http://director.sourceforge.net">http://director.sourceforge.net</ulink>.</para>
    <para>There is a <ulink url="http://director.sourceforge.net/download.php">download page</ulink> from which you can download the latest stable and (if available) beta versions of Director.</para>
    <para>There are two archives available for download. One contains the main Director programs and associated utilities and menus. The other also contains the source code and CVS information.</para>
    <para>Director can also be retrieved via <acronym>CVS</acronym>. Details of this can be found <link linkend="intro/cvs">on the next page</link> or on the web at <ulink url="http://director.sourceforge.net/cvs.php">http://director.sourceforge.net/cvs.php</ulink></para>
  </section>

  <section id="intro/cvs">
    <title>Getting Director via CVS</title>
    <para>If you are interested in staying up to date with the most recent developments on Director then this is for you.</para>

    <section id="intro/cvsanon">
      <title>Getting Director via CVS: Anonymous CVS</title>
      <para>You first need to logon to the SourceForge servers with the command:
<programlisting>cvs -d:pserver:anonymous@cvs.director.sourceforge.net:/cvsroot/director login</programlisting>
When prompted for a password for anonymous, simply press the Enter key.</para>
     <para>Then to get the latest copy of Director issue the command:
<programlisting>cvs -z3 -d:pserver:anonymous@cvs.director.sourceforge.net:/cvsroot/director co director</programlisting></para>
     <para>To subsequently update your local copy issue the command:
<programlisting>cvs update -Pd</programlisting>
from the same directory that <filename class="directory">!Director</filename> is in.</para>
     <para>Past releases can also be downloaded this way. Yell if you want more details.</para>
    </section>

    <section id="intro/cvsdevel">
      <title>Obtaining Director via CVS: For developers</title>
      <para>SourceForge only allows developers to access the repository via <acronym>SSH</acronym>. To enable this under Linux or Unix issue the command:
<programlisting>export CVS_RSH=ssh</programlisting></para>
      <para><programlisting>cvs -z3 -d:ext:&lt;sourceforge_id&gt;@cvs.director.sourceforge.net:/cvsroot/director co director</programlisting>
Where &lt;sourceforge_id&gt; is your username on SourceForge. You will be prompted for your SourceForge password before Director will be downloaded.</para>
    </section>
  </section>

<section id="intro/install">
  <title>Installing Director</title>
  <para>Regardless of the many features that are already setup in Director, everyone (even me) customises it to a point. If you have customisations within the <filename class="directory">!Director</filename> application then it may be worth checking out the Customizing Director chapter for details.</para>
  <procedure>
    <step><para>Quit Director if it is running</para></step>
    <step><para>Rename your existing copy of <filename class="directory">!Director</filename> to <filename class="directory">!DirectorO</filename> (or something) in order to keep it safe in case there are problems whilst upgrading.</para></step>
    <step><para>Extract <filename class="directory">!Director</filename> into the directory of your choice - probably along side <filename class="directory">!DirectorO</filename></para></step>
    <step><para>Run the new copy of Director.</para></step>
  </procedure>
  <para>If you are running RISC OS 3.1 then Director requires a utility called <filename>Repeat</filename>. It can be found in <filename>3rdParty.HBazley.Repeat.!ReadMe</filename>. Versions of RISC OS 3.5 and later ship with a copy of Repeat already installed.</para>
</section>

  <section id="intro/maillist">
    <title>Director mailing list</title>
    <para>There is a mailing list for Director.</para>
    <para>To subscribe to the mailing list send an email to <email>director-users-request@lists.sourceforge.net</email> with the body of the email reading "subscribe". You will be sent a confirmation e-mail which you need to reply to in order to subscribe to the list.</para>
    <para>To post to the list send an email to <email>director-users@lists.sourceforge.net</email>. It is recommended that you are subscribed to the mailing list before posting to it so that you will see all replies to your message.</para>
  </section>

  <section id="intro/motivation">
    <title>Motivation for writing Director</title>
    <para>Director was initially conceived as a replacement for Pinboard+ (by  Thomas Olsson). For those of you who don't know, Pinboard+ is a replacement Pinboard module which allows user definable menus when clicking menu over the backdrop.</para>

    <para>The initial design of Director was in order to overcome the fact that Pinboard+ needed a replacement pinboard module loaded (which did not work fully under RISCOS 3.5) and the fact that there was no easy way of specifying that you wanted the contents of a directory as a sub menu.</para>
    
    <para>This then led on to the idea of incorporating the functions of TreeMenu  by Julian Smith) into Director. This would then enable a directory tree listing to be attached to a menu at any point.</para>
    
    <para>These ideas led onto Director being more of a general purpose program, merging several utilities into one compact package.</para>
    
    <para>Memory usage was another of the main reasons for coding Director. Here's a before and after on the memory front.</para>
    
    <table>
    <title>Memory required before Director</title>
      <tgroup cols=2>
        <thead>
          <row>
            <entry>Program</entry>
            <entry>Memory required (bytes)</entry>
          </row>
        </thead>
        <tfoot>
          <row>
            <entry>Total</entry>
            <entry>174,568</entry>
          </row>
        </tfoot>
        <tbody>
          <row>
            <entry>TreeMenu</entry>
            <entry>65,536</entry>
          </row>
          <row>
            <entry>Pinboard+ (module)</entry>
            <entry>18,812</entry>
          </row>
          <row>
            <entry>Pinboard+ (menu)</entry>
            <entry>43,324</entry>
          </row>
          <row>
            <entry>DeskUtils</entry>
            <entry>32,768</entry>
          </row>
          <row>
            <entry>Memorizer</entry>
            <entry>14,128</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
    <title>Memory required with Director</title>
      <tgroup cols=2>
        <thead>
          <row>
            <entry></entry>
            <entry>Memory required (bytes)</entry>
          </row>
        </thead>
        <tfoot>
          <row>
            <entry>Total</entry>
            <entry>66,216</entry>
          </row>
        </tfoot>
        <tbody>
          <row>
            <entry>Program code</entry>
            <entry>32,368</entry>
          </row>
          <row>
            <entry>Workspace</entry>
            <entry>3,664</entry>
          </row>
          <row>
            <entry>Heap</entry>
            <entry>30,184 (261 blocks)</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>Thus giving a saving of 108,352 bytes or 105 kBytes!</para>

    <para>Director will use a dynamic area if they are available. (This has several advantages, the main one being less RMA fragmentation.)</para>
    
    <para>Director also includes some ideas from Filer+ (by Jens H. Ovesen), Filer- (by Franz Philipps), and Memorizer (by Ben Summers).</para>
    
    <para>Director is written entirely in ObjAsm assembler for its compactness and ease of making module tasks.</para>
    
    <!-- Although not all the original ideas may have been my own, the coding is all mine (including all the bugs!) -->
  </section>

&changelog;

  <section id="intro/licence">
    <title>Licence</title>
    <para>This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.</para>
    <para>This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.</para>
    <para>You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA</para>
  </section>

  <section id="intro/thanksncw">
    <title>Nick Craig-Wood wishes to thank</title>
    <para>For interesting menu options, bug reports, comments, ideas, donations or even just telling me that they were using Director, thanks are due to :-</para>
    <para>Stefan Wiesner, Sam Kington, Paul Hedderly, Denis Howe, Kevin Bagust, Ferro Marco, Brian Howlett, Simon Hatliff, Dominic Symes, Chris Knight, Fergio Monesi, Jonathan Mist, James Freeman, Colin Hogben, Aidan Corey, Mike Brown, Julian Smith, Matthew Bloch, Andrew Garrard, Bernhard Ege, Simon Middleton, Trevor Johnson, Richard Payne, Paul Moore, Ian Hinder, Reuben Thomas, Peter Reeves-Hall, Graham Crow, John Pettigrew, Russel Thickings, Roger Darlington, Peter Jennings, Jonathan Porter, Jon Wright, Ned  Abell, Frank Foehl, Paul Clifford, Kostas Proitsakis, Stephen Williams, Kevin Rutherford, Alex Singleton, M Cadman, Malcolm Boura, D M Wells, Robin Abecasis, Liam Gretton, Stefan Wuerthner, Bill Murphy, Matthew Israelsohn, Bob Seago, Robin Moffat, Chris Manning, Simon Knott, Gareth McCaughan, Daniel Ellis, Michael Curry, Tom Tanner, Jamie Temple, Damian Leslie, Jeff Haskell, Rene Fleischer, Barry Thompson, David Thomas, Jonathan Pretty, Phil Norman, Simon Jones, Thomas Harris, Chris Parker, Graham Crockford, Dick Tanis.</para>
    <para>Thomas Olsson, Julian Smith, Ben Summers, Jens Ovesen and Franz Philipps for writing a set of excellent utilities which gave me lots of ideas for Director.</para>
    <para>Jonathan Coxhead for OSLib.</para>
    <para>Julian Smith for generously supplying the source code for auto scrolling menus (which I haven't had time to implement yet).</para>
    <para>Jens Ovesen for very kindly allowing me to distribute his excellent and indispensable SWI module with this application.</para>
    <para>Dominic Symes for Zap. No programmer should be without it.</para>
    <para>Phil Slingsby for thinking of the name.</para>
    <para>Rob Craig-Wood for various bits and brotherly encouragement.</para>
    <para>Dave Lawrence for testing, the original idea (and code) of creating Pinboard+ menus from a textual form, ExpandMenu, IfPodule, IfThereIs, DriveName and loads of other ideas and suggestions (some of which I've almost certainly credited to myself ;-)</para>
    <para>My wife Loveday.</para>
  </section>

  <section id="intro/thankspl">
    <title>Philip Ludlam wishes to thank</title>
    <para>Nick for originally writing Director and letting me take over development of it.</para>
    <para>All the contributes to the director-users and director-developers mailing lists hosted on SourceForge for their input and comments on my ideas.</para>
    <para>Harriet Bazley for Repeat and updates to Switch (and co.), Lenny for answering my RISC OS 4 questions and alpha testing some changes and Martin Dann for the free disc space code and CDVolume.</para>
    <para></para>
    <para>And everyone else on the Director-users mailing list.</para>
  </section>
</chapter>
