Index: generic_midi_control_surface.xml
===================================================================
--- generic_midi_control_surface.xml	(revision 4410)
+++ generic_midi_control_surface.xml	(working copy)
@@ -6,11 +6,92 @@
 
 <section id="sn-generic-midi-control-surface">
   <title>Using a Generic MIDI control surface</title>
-  <para>
-    To be completed. Applies only to Ardour 2.
-  </para>
-<!--
-	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="Some_Subsection.xml" />
-	-->
+
+  <section id="connecting-control-surface">
+    <title>Connecting the MIDI control surface</title>
+    <para>
+      In Ardour, all gain faders, panners, mute/solo/rec-enable
+      buttons and all plugin parameters can be controlled by MIDI
+      Continuous Controller (CC) (which is called MIDI Parameter Control in 
+      Ardour). Ardour can also send MIDI "feedback" whenever gain, pan or 
+      plugin state
+      changes, so that external motorized control surfaces can reflect
+      parameter changes caused by automation etc. In addition, MMC commands are 
+      supported. Generic MIDI control surfaces do not use the MCU protocol.
+    </para>
+
+    <para>
+      You need to have a MIDI port set up to deal with MMC and/or MIDI 
+      Parameter control as descibed in <xref linkend="sn-midi-configuration"/>.  
+      Your control surface (e.g. a Behringer BCF2000) has to be connected to 
+      the correct Ardour MIDI port.
+    </para>
+  </section>
+
+  <section id="set-up-control-surface">
+    <title>Setting up the MIDI control surface</title>
+
+    <para>
+      To use a generic MIDI control surface in Ardour, choose the "Options" 
+      menu, then choose the "Control Surfaces" submenu, then select "Generic 
+      Midi".
+    </para>
+
+    <para>
+      Ardour can send feedback to the control surface, allowing it to reflect 
+      changes caused by automation or by mouse interaction. You can enable 
+      feedback by choosing the "Options" menu, the "Control Surfaces" submenu, 
+      the "Controls" submenu, then selecting "Feedback".
+    </para>
+
+    <para>
+      To control e.g. a gain fader, use <mousebutton>Ctrl+Button2</mousebutton> 
+      on the fader. The message "operate controller now" should appear. Move 
+      the desired fader or knob on your control surface. The fader on the 
+      screen should start to move as you move the slider on your control 
+      surface. If you activated MIDI feedback and your control surface supports 
+      it, it should reflect changes you do with the mouse.
+    </para>
+
+    <para>
+      You can configure MIDI control for virtually all faders, plugin 
+      parameters and switches by using <mousebutton>Ctrl+Button2</mousebutton> 
+      on it, then moving the desired control on the control surface a bit.
+    </para>
+
+    <note>
+      <title>Note</title>
+      <para>
+	The assignments of the MIDI controls are saved with the Ardour project.  
+	For each new project, you have to assign every control manually. To 
+	avoud this, you can use a template, see <xref 
+	  linkend="sn-templates"/>.
+      </para>
+    </note>
+  </section>
+
+  <section id="used-midi-commands">
+    <title>MIDI commands used to control Ardour</title>
+
+    <para>
+      Controls in Ardour are controlled with Change Control (CC) MIDI commands.  
+      Those commands can be sent on arbitrary MIDI channels. 
+      Faders and other continously moved controls are controlled with CC 
+      commands with a range of 0-127.  Buttons (e.g. Mute buttons) are also 
+      controlled with CC commands, where a value of 0-63 switches the button 
+      off and a value of 64-127 switches the button on.
+    </para>
+
+    <para>
+      Ardour also receives and sends some MMC commands, such as play, stop, 
+      locate, punch in and punch out. Make sure you configured Ardour to listen 
+      for MMC commands as descibed in <xref linkend="sn-midi-configuration"/>.
+    </para>
+
+
+  </section>
+  <!--
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+    href="Some_Subsection.xml" />
+  -->
 </section>
Index: control_surfaces.xml
===================================================================
--- control_surfaces.xml	(revision 4410)
+++ control_surfaces.xml	(working copy)
@@ -7,21 +7,29 @@
 <chapter id="ch-control-surfaces">
   <title>Using Control Surfaces</title>
   <para>
-    You can use a variety of different control surfaces with Ardour. We
-    anticipate full support for a new class of control surfaces (those using
-    the Mackie Control protocol) by the mid-summer of 2006, possibly
-    earlier.
+    Ardour supports several control surfaces: generic MIDI control surfaces, 
+    MCU surfaces, the Frontier Tranzport device and others. Generic MIDI 
+    control can be used with any MIDI controller capable to send CC (Control 
+    Change) and/or MMC commands, such as the Behringer BCF2000/BCR2000.  The 
+    MCU protocol can be used with controllers supporting the Mackie MCU 
+    protocol, but the MCU protocol is not yet fully implemented and configuring 
+    an MCU device is a challenging task. Setting up the Tranzport device is 
+    also tricky.
   </para>
+
+  <para>
+    This chapter describes how to use generic MIDI control, MCU and Tranzport 
+    surfaces. Additionally, some short tutorials are included.
+    Other Surfaces are experimental and are not described in this chapter.
+  </para>
+  
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+    href="generic_midi_control_surface.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="mackie.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+    href="frontier_design_tranzport.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
 		href="behringer_ddx3216.xml" />
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
 		href="bcf2000.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="frontier_design_tranzport.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="generic_midi_control_surface.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="configuring_usb_device_access.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="mackie.xml" />
 </chapter>
Index: behringer_ddx3216.xml
===================================================================
--- behringer_ddx3216.xml	(revision 4410)
+++ behringer_ddx3216.xml	(working copy)
@@ -5,7 +5,7 @@
 ]>
 
 <section id="sn-behringer-ddx3216">
-  <title>Behringer DDX3216</title>
+  <title>Tutorial: Behringer DDX3216</title>
   <para>
     The Behringer DDX3216 isn't actually a dedicated control surface, it is
     a digital mixer. However it does have the capability to control ardour
@@ -62,9 +62,10 @@
         following steps each time. Load a new session with your desired
         amount of tracks (I used 16). Go to menu <menuchoice>
         <guimenu>Windows</guimenu> <guisubmenu>Options Editor</guisubmenu>
-        </menuchoice> and select the <guilabel>MIDI</guilabel> tab. Select
-        all the options and make sure the midi port you have connected to in
-        qjackctl is 'online'.
+	</menuchoice> and select the <guilabel>MIDI</guilabel> tab.  Configure 
+	the port you chose to connect with the DDX3216 to handle all kinds of 
+	MIDI information (see <xref linkend="sn-midi-configuration"/>). Make 
+	sure it is 'online'.
       </para>
     </listitem>
     <listitem>
@@ -91,6 +92,7 @@
       </para>
     </listitem>
     <listitem>
+      <!-- TODO: This is not up-to date and doesn't match Ardour 2.7.1 -->
       <para>
         You can also operate the ardour transport and have ardour transmit
         MTC back to your DDX3216 (it is only capable of receiving timecode,
Index: midi_configuration.xml
===================================================================
--- midi_configuration.xml	(revision 4410)
+++ midi_configuration.xml	(working copy)
@@ -5,7 +5,7 @@
 ]>
 
 <section id="sn-midi-configuration">
-  <title>Midi Configuration</title>
+  <title>MIDI Configuration</title>
   <para>
     Although at this time Ardour does not support
     <glossterm linkend="gt-midi">MIDI</glossterm> sequencing, it does
@@ -16,36 +16,40 @@
   <itemizedlist>
     <listitem>
       <para>
-        Ardour can function as MIDI Time Code (MTC) master or slave
+        Ardour can function as MIDI Time Code (MTC) master or slave. MTC is 
+        used to transfer the actual time location, so the connected MIDI 
+        devices will stay in sync (even when using fast forward and such).
       </para>
     </listitem>
 
     <listitem>
       <para>
         Ardour can control or be controlled by other devices using MIDI
-        Machine Control (MMC)
+        Machine Control (MMC). MMC commands include start, stop, punch in, 
+        punch out and others.
       </para>
     </listitem>
 
     <listitem>
       <para>
-        Ardour can bind all gain faders, panners, mute/solo/rec-enable
-        buttons and all plugin parameters to be controlled by MIDI
-        Continuous Controller (CC) or Note On/Off messages.
+        In Ardour, virtually any parameter can be controlled by MIDI
+        Continuous Controller (CC) messages (which is called MIDI Parameter 
+        Control). In addition, Ardour can send MIDI "feedback"
+        so that external motorized control surfaces can reflect parameter 
+        changes caused by automation etc. See <xref 
+          linkend="ch-control-surfaces"/> how to configure control surfaces.
       </para>
     </listitem>
-
-    <listitem>
-      <para>
-        Ardour can send MIDI "feedback" whenever gain, pan or plugin state
-        changes, so that external motorized control surfaces can reflect
-        parameter changes caused by automation etc.
-      </para>
-    </listitem>
   </itemizedlist>
 
-  <section id="specifying-midi-ports">
-    <title>Specifying MIDI ports</title>
+  <para>
+    If you need MIDI in Ardour, you have to configure it. This is described in 
+    this section. If you don't, skip this section and come back when you need 
+    it.
+  </para>
+
+  <section id="midi-ports">
+    <title>MIDI ports</title>
     <para>
       Ardour does not attempt to discover what MIDI ports exist on your
       system. This is a complex issue, and on systems like Linux and OS X
@@ -54,180 +58,214 @@
     </para>
 
     <para>
-      Instead, the MIDI ports that are available for Ardour to use are
-      defined in your <filename>ardour.rc</filename> file. These port
-      definitions are not session specific, on the assumption that your
-      system's MIDI hardware probably doesn't change much from session to
-      session. The default version of this file contains a single port that
-      can be used for inter-application MIDI routing as well as MIDI I/O to
-      whatever physical MIDI ports might be available on your computer. In
-      many cases, you will not need to change them.
+      Instead, some ports are defined which can be connected to any other MIDI 
+      port. These port	definitions are not session specific, on the assumption 
+      that your system's MIDI hardware probably doesn't change much from 
+      session to session. In many cases, you will not need to change them.
     </para>
 
-    <para>
-      When you first use Ardour, the
-<!--
-			xlink linkend="files_and_environment"
-			-->
-      <filename>ardour.rc</filename> file that you will have contains a
-      single port definition. It defines a port that is almost guaranteed to
-      be usable on your system ((Linux/ALSA users may need to ensure that
-      the <filename>snd-seq</filename> kernel module gets loaded - many
-      distributions do not do this by default)). This port is a "virtual
-      port" it isn't actually a hardware MIDI port, but instead is a
-      software port that can be connected to other software ports or to
-      whatever hardware MIDI ports you have (see
-      <xref linkend="midi-making-connections"/>).
-    </para>
   </section>
-<!--
-	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="Some_Subsection.xml" />
-	-->
-  <section id="defining-additional-midi-ports">
-    <title>Defining additional MIDI ports</title>
+
+  <section id="configuring-midi-ports">
+    <title>Configuring MIDI ports</title>
+
     <para>
-      To define additional ports, find the line in
-      <filename>ardour.rc</filename> that looks roughly like this:
+      When you first use Ardour, three MIDI ports will be available which are 
+      almost guaranteed to be usable on your system (Linux/ALSA users may need 
+      to ensure that the <filename>snd-seq</filename> kernel module gets loaded 
+      - many distributions do not do this by default). These are "virtual 
+      ports" which are not actually related to any hardware MIDI port. They can 
+      be connected to other software ports or to  whatever hardware MIDI ports 
+      you have (see <xref linkend="midi-making-connections"/>).
     </para>
-<screen>
-&lt;MIDI-port tag="hw:0" device="/dev/snd/midiC1D0" type="alsa/raw" mode="duplex"/&gt;
-		</screen>
-    <para>
-      On OSX/CoreMIDI it would look more like:
-    </para>
-<screen width="50">
-&lt;MIDI-port tag="coremidi" device="ardour" type="coremidi" mode="duplex"/&gt;
-		</screen>
-    <para>
-      You can then add another line right after it that looks similar but
-      contains a different port definition.
-    </para>
 
     <para>
-      You will see there are 4 pieces of information required to define a
-      MIDI port for use within Ardour. Your port definition
+      You can modify existing ports in the "Preferences" Window. Choose 
+      <menuchoice><guimenu>          
+          Edit</guimenu><guisubmenu>Preferences</guisubmenu></menuchoice> to 
+      show that window, then go to the <guilabel>MIDI</guilabel> tab. You 
+      should see at least the ports "control", "mcu" and "seq".  For each port 
+      you can configure the following options:
     </para>
 
-    <section id="midi-tag">
-      <title>Tag</title>
-      <para>
-        This is just a name of your own choosing. It is how the port will be
-        referred to within Ardour. You could use a name that describes what
-        is plugged into the port (e.g. "1600x", "Novation"), or a name that
-        describes the computer device/system that provides the port (e.g.
-        "HDSP", "Sequencer"), or a whimsical name of your own choice (e.g.
-        "bowtie", "merlin").
-      </para>
-    </section>
+    <variablelist>
 
-    <section id="midi-type">
-      <title>Type</title>
-      <para>
-        This is an operating system specific identifier that defines what
-        kind of port this is. It can be set to one of three values:
-      </para>
-
-      <itemizedlist>
+      <varlistentry>
+        <term>Online</term>
         <listitem>
           <para>
-            <literal>alsa/raw</literal> - the port corresponds to a physical
-            MIDI port that is accessed directly without involving the ALSA
-            MIDI routing subsystem.
+            Setting a port to offline will not cause a port to disappear; 
+            rather Ardour will simple no longer send any data on it, nor 
+            will it process data received on it. Online ports work 
+            normally.
           </para>
         </listitem>
+      </varlistentry>
 
+      <varlistentry>
+        <term>Trace Input</term>
+        <term>Trace Output</term>
         <listitem>
           <para>
-            <literal>alsa/sequencer</literal> - the port is a virtual port
-            that can send and receive MIDI data via the ALSA MIDI routing
-            subsystem.
+            When one of these buttons is checked for a port, the sent (Output) 
+            respective received (Input) MIDI data will be displayed on the 
+            console. Note that you need to run Ardour from a console to see that 
+            output.  This can be useful to check your MIDI connections.
           </para>
         </listitem>
+      </varlistentry>
 
+      <varlistentry>
+        <term>MTC</term>
+        <term>MMC</term>
+        <term>MIDI Parameter Control</term>
         <listitem>
           <para>
-            <literal>coremidi</literal> - the port is a virtual port that
-            can send and receive MIDI data via the CoreMidi
-            inter-application MIDI routing subsystem.
+            You can choose which port is used for which kind of MIDI 
+            information. For each kind - MTC, MMC and MIDI Parameter Control - 
+            one MIDI port have to be assigned. The same MIDI port can be used 
+            for several kinds of information.
           </para>
         </listitem>
-      </itemizedlist>
-    </section>
+      </varlistentry>
 
-    <section id="midi-device">
-      <title>Device</title>
+    </variablelist>
+
+    <!--
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+      href="Some_Subsection.xml" />
+    -->
+    <section id="defining-additional-midi-ports">
+      <title>Defining additional MIDI ports</title>
       <para>
-        This is an operating specific and MIDI subsystem-specific name that
-        actually identifies the device to be used for MIDI I/O.
+        You can easily define additional midi ports. Choose 
+        <menuchoice><guimenu>Edit</guimenu><guisubmenu>Preferences</guisubmenu></menuchoice> 
+        to show the "Preferences" window, then go to the 
+        <guilabel>MIDI</guilabel> tab.  Click on the <guibutton>Add new MIDI 
+          port</guibutton> button to add a new port.  Provide a name and choose 
+        one of the following options:
       </para>
 
-      <itemizedlist>
-        <listitem>
-          <para>
-            for a raw ALSA hardware port, it is the name of the device file
-            corresponding to the hardware MIDI port. A typical value might
-            be <filename>/dev/snd/midiC0D0/</filename>.
-          </para>
-        </listitem>
+      <variablelist>
 
-        <listitem>
-          <para>
-            for an ALSA sequencer port, it is an arbitrary name for the port
-            that will appear as part of the ALSA MIDI routing system
-          </para>
-        </listitem>
+        <varlistentry>
+          <term>input</term> 
+          <listitem>
+            <para>
+              The new port will be an input port.
+              This is rarely used.
+            </para>
+          </listitem>
+        </varlistentry>
 
-        <listitem>
-          <para>
-            for a CoreMIDI port, it is an arbitrary name for the port that
-            will appear as in any CoreMIDI port selection dialogs.
-          </para>
-        </listitem>
-      </itemizedlist>
+        <varlistentry>
+          <term>output</term>
+          <listitem>
+            <para>
+              The new port will be an output port.  This is rarely used.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>duplex</term>
+          <listitem>
+            <para>
+              The new port will be an input and output port.  This is what is 
+              normally needed.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        Click on the <guibutton>Add</guibutton> button to create the new port.
+      </para>
+
     </section>
 
-    <section id="midi-mode">
-      <title>Mode</title>
+    <section id="midi-removing-ports">
+      <title>Removing MIDI Ports</title>
       <para>
-        This specifies whether the port is available for input, output or
-        both:
+        To remove a MIDI port, click on the <guibutton>Remove</guibutton> button 
+        right of the port.
       </para>
 
-      <itemizedlist>
+      <note>
+        <title>Note</title>
+        <para>
+          You can not remove a port if it is configured to transfer MTC, MMC or 
+          MIDI Parameter Control data. That also means that the last port 
+          cannot be removed as it will necessarily be configured to transfer all 
+          kind of MIDI data.
+        </para>
+      </note>
+
+      <note>
+        <title>Note</title>
+        <para>
+          If you remove one of the default MIDI ports (control, seq, mcu), it 
+          will automatically be recreated next time you start Ardour. This is 
+          because these default ports are saved in 
+          <filename>/etc/ardour2/ardour_system.rc</filename> where you can't 
+          remove them. Your MIDI configuration is saved in 
+          <filename>$HOME/.ardour2/ardour.rc</filename>.
+        </para>
+      </note>
+    </section>
+  </section>
+
+  <section id="additional-configuration">
+    <title>Additional Configuration</title>
+    <para>
+      Ardour allows some more MIDI configuration:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>Inbound MMC Device ID</term>
         <listitem>
           <para>
-            <literal>read</literal> - the port is available for input only
+            Each MMC command includes a device ID. Ardour listens only for MMC 
+            commands with a specific device ID. You can configure for which 
+            device ID Ardour listens. The default of 0 should be safe.
           </para>
         </listitem>
+      </varlistentry>
 
+      <varlistentry>
+        <term>Outbound MMC Device ID</term>
         <listitem>
           <para>
-            <literal>write</literal> - the port is available for output only
+            Each MMC command includes a device ID. You can configure which 
+            Device ID Ardour uses when it sends MMC commands. The default of 
+            127 should be safe.
           </para>
         </listitem>
+      </varlistentry>
 
+      <varlistentry>
+        <term>Startup program change</term>
         <listitem>
           <para>
-            <literal>duplex</literal> - the port is available for input and
-            output
+            On startup, Ardour sends a Program Change (PC) command. A PC 
+            command includes a program number (a value between 0 and 127). You 
+            can choose which program number is sent by Ardour. A value of -1 
+            will send 127. The default is 127.
           </para>
+          <para>
+            The PC command is sent on the MIDI port which is configured to handle MIDI 
+            parameter control. It is sent right after you start a session (either a new 
+            one or an existing one). The command is also sent if you choose to load 
+            another session without closing Ardour.
+          </para>
         </listitem>
-      </itemizedlist>
+      </varlistentry>
 
-      <para>
-        You should probably always use <literal>duplex</literal> here. It is
-        rare to need to open a port for unidirectional communication only.
-      </para>
-    </section>
-  </section>
+    </variablelist>
 
-  <section id="midi-removing-ports">
-    <title>Removing Midi Ports</title>
-    <para>
-      To remove a MIDI port, simply delete the line in your
-      <filename>ardour.rc</filename> file that defines it.
-    </para>
   </section>
 
   <section id="midi-making-connections">
@@ -235,9 +273,8 @@
     <para>
       If you use actual physical hardware MIDI ports, then establishing
       connections to other MIDI equipment is simply a matter of connecting
-      cables correctly. However, if you use "virtual ports" such as those
-      offered by the ALSA router/sequencer or CoreMIDI, making connections
-      is slightly more involved.
+      cables correctly. However, if you use "virtual ports", as Ardour does, 
+      making connections is slightly more involved.
     </para>
 
     <para>
@@ -254,46 +291,34 @@
       <para>
         <application>qjackctl</application> (the same program that is
         recommended for controlling JACK) also includes an excellent MIDI
-        connection manager. You could also use command line tools such as
+        connection manager.  You could also use command line tools such as
         <application>aconnect</application>.
       </para>
+
+      <para>
+        If you use the program <application>qjackctl</application> to
+        control JACK, there's an easy way to connect Ardour to other MIDI 
+        ports.  Run <application>qjackctl</application>, and click on the 
+        <guibutton>Connect</guibutton> button in
+        the main <application>qjackctl</application> window. This will bring up 
+        the Connection window.  Go to the ALSA tab (don't use the MIDI tab!) 
+        and connect the MIDI ports as needed.
+      </para>
+
     </section>
 
     <section id="midi-connection-osx">
       <title>OSX/CoreMIDI</title>
       <para>
         On OSX/CoreMIDI you need to connect the MIDI ports with a patchbay
-        tool such as the excellent MIDI Patchbay from
-        <ulink url="http://pete.yandell.com/software/">Pete Yandell</ulink>
+        tool such as the excellent <ulink           
+          url="http://www.macmusic.org/software/view.php/lang/en/id/592/">MIDI 
+          Patchbay</ulink> from <!-- (site is currently down)
+        <ulink url="http://pete.yandell.com/software/">-->
+          Pete Yandell
+          <!--</ulink> -->.
       </para>
     </section>
   </section>
 
-  <section id="midi-using-midi-ports">
-    <title>Using MIDI ports</title>
-    <para>
-      Each port that is defined in <filename>ardour.rc</filename> can be
-      used for any of the following functions:
-    </para>
-
-    <itemizedlist>
-      <listitem>
-        <para>
-          MTC input and output
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          MMC input and output
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          MIDI CC/Note input and output
-        </para>
-      </listitem>
-    </itemizedlist>
-  </section>
 </section>
Index: introduction.xml
===================================================================
--- introduction.xml	(revision 4410)
+++ introduction.xml	(working copy)
@@ -14,10 +14,8 @@
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
 		href="formatting_conventions.xml" />
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="midi_configuration.xml" />
+    href="key_bindings.xml" />
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="key_bindings.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
 		href="user_interface_conventions.xml" />
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
 		href="what_is_different_about_ardour.xml" />
Index: ardour_basics.xml
===================================================================
--- ardour_basics.xml	(revision 4410)
+++ ardour_basics.xml	(working copy)
@@ -6,11 +6,13 @@
 
 <chapter id="ch-ardour-basics">
   <title>Ardour Basics</title>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+                href="jack.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+                href="midi_configuration.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+                href="sessions.xml" />
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="sessions.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="jack.xml" />
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
 		href="main_windows.xml" />
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
 		href="editor_window.xml" />
Index: mackie.xml
===================================================================
--- mackie.xml	(revision 4410)
+++ mackie.xml	(working copy)
@@ -10,9 +10,18 @@
     For Ardour 2, this will walk you through the process of configuring and
     using Mackie MCU, or a BCF2000 in
     <ulink url="http://www.behringerdownload.de/BCF2000/BCF2000_Emulation_modes.pdf">Logic
-    Control emulation mode</ulink>.
+      Control emulation mode</ulink>.
   </para>
 
+  <note>
+    <title>Note</title>
+    <para>
+      MCU support in Ardour is incomplete and setting up an MCU device is 
+      currently a challenging task.
+    </para>
+  </note>
+
+
   <section id="mackie-connecting-device">
     <title>Connecting Device</title>
     <para>
Index: bcf2000.xml
===================================================================
--- bcf2000.xml	(revision 4410)
+++ bcf2000.xml	(working copy)
@@ -5,251 +5,47 @@
 ]>
 
 <section id="sn-bcf2000">
-  <title>Using a BCF2000</title>
+  <title>Tutorial: Behringer BCF2000/BCR2000</title>
+
   <para>
     This will walk you through the process of configuring and using a
     <ulink url="http://www.behringer.com/BCF2000/index.cfm">Behringer
-    BCF2000 MIDI control surface</ulink> , or BCF, with Ardour. This should
-    also work with the
+      BCF2000 MIDI control surface</ulink> , or BCF, with Ardour. Most of this 
+    should also work with the
     <ulink url="http://www.behringer.com/BCR2000/index.cfm">BCR2000</ulink>,
-    but has not been tested.
+    but has not been tested. The BCF2000 and BCR2000 are able to send/receive 
+    Control Change (CC) MIDI commands, which can be used to control Ardour. MMC 
+    commands are also supported.
   </para>
 
-  <section id="bcf2000-connecting-device">
-    <title>Connecting Device</title>
-    <para>
-      It's assumed that your USB ports are functional under Linux. The
-      easiest way to tell if you've got a functional link is to simply
-      connect the BCF2000 to your computer with a USB cable, connect the
-      power, and turn it on. You should see the USB MODE light come on in
-      the upper right corner of the BCF. If that's not on, you'll need to
-      figure out how to make your <ulink url="http://www.linux-usb.org/">USB
-      port work under Linux.</ulink>
-    </para>
+  <para>
+    Possibly you want to update the firmware of the BCF2000/BCR2000 first to 
+    eliminate bugs and enable new features. Of course, it should work also 
+    without an update. See <xref linkend="updating-firmware">Firmware 
+      Updating</xref> how to perform an update.
+  </para>
 
+  <section id="setup-bcf2000">
+    <title>Setting up the BCF2000/BCR2000</title>
     <para>
-      If the USB MODE light is on, doublecheck that Linux knows of the
-      device.
+      At first you need to configure a MIDI port in Ardour to handle "MIDI 
+      Parameter Control" and MMC, and you have to connect the BCF2000 to that 
+      port. See <xref linkend="sn-midi-configuration">MIDI Configuration</xref> 
+      how to do that.
     </para>
-<screen>
-xtc:~% aconnect -o
-client 64: 'M Audio Delta 1010 MIDI - Rawmidi 0' [type=kernel]
-   0 'M Audio Delta 1010 MIDI'
-client 72: 'BCF2000 - Rawmidi 1' [type=kernel]
-   0 'BCF2000 MIDI 1  '
-</screen>
-  </section>
 
-  <section id="updating-firmware">
-    <title> Firmware Updating (v1.07) </title>
     <para>
-      The first thing you're likely to have to do is update the firmware in
-      the unit. This is a relatively painless process.
+      Secondly you have to assign controls in Ardour (such as faders and 
+      buttons) to physical controls on the BCF2000. See <xref 
+        linkend="sn-generic-midi-control-surface">Using a Generic MIDI control 
+        surface</xref> how to achieve that.
     </para>
-    <orderedlist>
-      <listitem>
-        <para>
-          Download the firmware from Behringers
-          <ulink url="http://www.behringer.com/05_support/bc_download/bc_downloads.cfm">downloads
-          page</ulink>. There will be a
-          <ulink url="http://www.behringer.com/BCF2000/bcf2000_107.zip">zip
-          file</ulink> available which should be downloaded. (This example
-          uses version 1.07 of the firmware, the latest available at the
-          time of this writing. There may be a newer version available now.)
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          Unzip the file you downloaded. You'll typically extract 2 files, a
-          PDF file with release notes and an SYX file, which is the firmware
-          update.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          Find the system device of the BCF
-        </para>
-<screen>
-xtc:~% cat /proc/asound/cards
-0 [M1010          ]: ICE1712 - M Audio Delta 1010
-                     M Audio Delta 1010 at 0xdf80, irq 
-2 [BCF2000        ]: USB-Audio - BCF2000
-                     BEHRINGER BCF2000 at usb-00:1d.1-2, full speed
-</screen>
-      </listitem>
-    </orderedlist>
-    <para>
-      In this case there are 2 devices. The number at the left indicates the
-      card number. The BCF is almost certain, then, to use the device
-      <filename>/dev/snd/midiCnD0</filename> where <emphasis>n</emphasis> is
-      the card number, in this case, 2.
-    </para>
 
-    <para>
-      Write the firmware to the BCF with the command
-    </para>
-<screen>
-cat bcf2000_1-07.syx > /dev/snd/midiC2D0	
-</screen>
-    <important>
-      <para>
-        Make sure you use the actual device you determined in the previous
-        step
-      </para>
-    </important>
-
-    <para>
-      The BCF display will show a whirling figure-8 animation and count up
-      to 18. Once the whirling stops, you should turn off the BCF, count to
-      5, then turn it on again. You should then see the version number of
-      the upgraded firmware displayed for a few seconds as the BCF starts.
-    </para>
   </section>
 
-  <section id="bcf2000-connecting-to-ardour">
-    <title> Connecting to Ardour </title>
-    <para>
-      After starting Ardour, it's important to connect the MIDI device ports
-      of Ardour and the BCF together so that they will communicate with each
-      other. There are a few ways to do this.
-    </para>
-
-    <section id="bcf2000-connecting-with-qjackctl">
-      <title> With qjackctl </title>
-      <para>
-        If you use the program <application>qjackctl</application> to
-        control JACK, there's an easy way to connect Ardour to the BCF. Run
-        qjackctl, and click on the <guibutton>Connect</guibutton> button in
-        the main qjackctl window. This will bring up the Connection window.
-        You should see at least 2 items listed, the BCF and Ardour:
-      </para>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="images/con1.jpg"/>
-        </imageobject>
-      </mediaobject>
-      <para>
-        Connect the BCF output to the Ardour input, and vice versa:
-      </para>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="images/con2.jpg"/>
-        </imageobject>
-      </mediaobject>
-      <section id="bcf2000-automating-qjackctl-connection">
-        <title> Automating the qjackctl connection </title>
-        <para>
-          You can set qjackctl to automatically make the MIDI connections
-          (and others) by using the Patchbay feature in qjackctl. Start
-          qjackctl and Ardour, and make the MIDI connections as shown above.
-          Click on the <guibutton>Patchbay</guibutton> button, then click on
-          <guibutton>New</guibutton>. Qjackctl will ask if you want to
-          create a patchbay definition as a snapshot of all actual client
-          connections. Clicking on <guibutton>Yes</guibutton> will bring in
-          a set of all ports available.
-        </para>
-        <mediaobject>
-          <imageobject>
-            <imagedata fileref="images/qjpatch.jpg"/>
-          </imageobject>
-        </mediaobject>
-        <para>
-          Make sure you've got both connections as described above, and
-          click <guibutton>Save...</guibutton> and choose a filename. Once
-          this is saved, you can close the patchbay.
-        </para>
-
-        <para>
-          Next, click on the qjackctl <guibutton>Setup</guibutton> button,
-          then click on the <guibutton>Options</guibutton> tab.
-        </para>
-        <mediaobject>
-          <imageobject>
-            <imagedata fileref="images/qjopts.jpg"/>
-          </imageobject>
-        </mediaobject>
-        <para>
-          Click on <guibutton>Activate patchbay persistence</guibutton> and
-          use the filename you used to save the patchbay above. The patchbay
-          connections will now be made after qjackctl starts up the clients.
-        </para>
-      </section>
-    </section>
-
-    <section id="bcf2000-connecting-from-command-line">
-      <title> From the command line </title>
-      <para>
-        The command <command>aconnect</command>, which is the ALSA sequencer
-        connection manager, can do the job of connecting the BCF to Ardour.
-        First find the numbers of the MIDI device ports for the two:
-      </para>
-<screen>
-xtc:~% aconnect -o
-client 64: 'M Audio Delta 1010 MIDI - Rawmidi 0' [type=kernel]
-    0 'M Audio Delta 1010 MIDI'
-client 80: 'BCF2000 - Rawmidi 2' [type=kernel]
-    0 'BCF2000 MIDI 1  '
-client 129: 'ardour' [type=user]
-    0 'seq             '
-</screen>
-      <para>
-        Here, the BCF is 80, and Ardour is 129. The proper connections can
-        be made between the two with two commands:
-      </para>
-<screen>
-xtc:~% aconnect 80:0 129:0
-xtc:~% aconnect 129:0 80:0
-</screen>
-    </section>
-
-    <section id="bcf2000-automatic-midi-connection">
-      <title> Automating the MIDI connection from the command line </title>
-      <para>
-        It's sometimes handy to start Ardour from the command line. I found
-        it irritating to have Ardour come up, and then have to manually make
-        the connections for the BCF. This was quickly solved by the
-        following script, which starts Ardour, finds the proper MIDI device
-        ports, and connects them:
-      </para>
-<screen>
-#!/bin/ksh
-# /usr/local/bin/start_ardour.sh
-#
-# April 17, 2005 - Joe Hartley (jh@brainiac.com)
-# A quick script to start Ardour and then make the MIDI connections between
-# the BCF2000 and Ardour.
-
-# start Ardour and give it a little time before setting the MIDI connections
-nohup /usr/bin/ardour &amp;
-sleep 3
   
-# Set the IDs - note that they'll both end with a colon
-BCF_ID=$(aconnect -o | grep BCF2000 | grep client | awk '{print $2}')
-ARD_ID=$(aconnect -o | grep ardour | awk '{print $2}')
-  
-aconnect "$BCF_ID"0 "$ARD_ID"0
-aconnect "$ARD_ID"0 "$BCF_ID"0 
-</screen>
-      <para>
-        As an alternative to the patchbay in qjackctl, you could have it run
-        this script to start Ardour and make the MIDI connections. Click the
-        <guibutton>Setup</guibutton> button and choose the
-        <guibutton>Options</guibutton> tab. Enable the <guibutton>Execute
-        script after Startup</guibutton> option, and change the line to call
-        the <filename>start_ardour.sh</filename> script. In this example, I
-        change directories to the drive I record to so new sessions will
-        open there by default before I run the script.
-      </para>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="images/qjopt.jpg"/>
-        </imageobject>
-      </mediaobject>
-    </section>
-  </section>
-
-  <section id="bcf2000-programming">
-    <title> Programming the BCF2000 for effective use </title>
+  <section id="bcf2000-finetuning">
+    <title>Finetuning for BCF2000</title>
     <para>
       One problem that I ran into with the BCF2000 was that none of the
       factory presets really did what I needed to control Ardour. I had a
@@ -287,9 +83,16 @@
       the mute, solo and rec-enable controls in Ardour to a pushbutton on
       the BCF. This was because in P2, the buttons sent a Program Change
       signal, but Ardour expects a Control Change signal. This required
-      re-programming the BCF a bit. Here's a list of the controls and what I
-      mapped them to send:
+      re-programming the BCF a bit. Note that there is a <ulink 
+        url="http://zappa.brainiac.com/preset1.syx">saved
+        preset file</ulink>, which has the definitions  described below. See 
+      <xref linkend="bcf2000-loading-a-preset">Loading a Preset</xref> how to 
+      load it into the BCF2000.
     </para>
+    
+    <para>
+      Here's a list of the controls and what I mapped them to send:
+    </para>
 
     <itemizedlist>
       <listitem>
@@ -376,8 +179,7 @@
         </listitem>
         <listitem>
           <para>
-            Press STORE again to write the settings to an empty preset. If
-            you want to overwrite an existing preset, press STORE twice. You
+            Press STORE again to write the settings to an empty preset. You
             can cancel the store at any time by pressing EXIT.
           </para>
         </listitem>
@@ -388,113 +190,23 @@
       Your BCF2000 is now ready to control Ardour!
     </para>
 
-    <section id="bcf2000-preconfigured-preset-file">
-      <title> Preconfigured Preset File </title>
-      <para>
-        Here is a <ulink url="http://zappa.brainiac.com/preset1.syx">saved
-        preset file</ulink>, which has the definitions described above. You
-        can use <command>amidi</command> to load this into the BCF as
-        <xref linkend="bcf2000-loading-a-preset"/>.
-      </para>
-    </section>
   </section>
 
-  <section id="bcf2000-mapping-ardour-controls">
-    <title> Mapping Ardour controls to the BCF2000 </title>
-    <para>
-      The final step to control surface Nirvana is to map the controls in
-      Ardour to the knobs, buttons and faders on the BCF.
-    </para>
 
+  <section id="bcf2000-saving-and-loading-presets">
+    <title>Saving and Loading Presets</title>
     <para>
-      Before you can map things properly, you'll need to set the MIDI
-      options within Ardour. In the Editor window of Ardour, choose
-      <menuchoice> <guimenu>Windows</guimenu> <guisubmenu>Options
-      Editor</guisubmenu> </menuchoice>. Make sure the seq device is online,
-      and make sure <guibutton>MTC</guibutton>, <guibutton>MMC</guibutton>
-      and <guibutton>MIDI Parameter Control</guibutton> is set for the seq
-      device. Also make sure that the 4 boxes below are checked:
+      The BCF2000/BCR2000 supports sending the configuration of a Preset to a 
+      MIDI device. Thus, it is possible to store the configuration on a 
+      computer. Of course, it is also possible to load a configuration back 
+      into the BCF2000. There is a <ulink 
+        url="http://zappa.brainiac.com/preset1.syx">saved
+        preset file</ulink>, which has the definitions described above. See 
+      <xref linkend="bcf2000-loading-a-preset">Loading a Preset</xref> how to 
+      load it into the BCF2000.
     </para>
 
-    <itemizedlist>
-      <listitem>
-        <para>
-          <guibutton>MMC control</guibutton>
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <guibutton>MIDI parameter control</guibutton>
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <guibutton>Send MMC</guibutton>
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          <guibutton>Send MIDI parameter feedback</guibutton>
-        </para>
-      </listitem>
-    </itemizedlist>
-    <mediaobject>
-      <imageobject>
-        <imagedata fileref="images/midiopts.jpg"/>
-      </imageobject>
-    </mediaobject>
     <para>
-      Now you're ready to do the actual mapping. This is a pretty simple
-      process, all controlled with a <keycombo><keycap>Ctrl</keycap>
-      <mousebutton>Button2</mousebutton> </keycombo> click. This will pop up
-      a little window which says <guilabel>operate MIDI controller
-      now</guilabel>. Simply press the BCF button (or move the slider) that
-      you want to have control the Ardour function.
-    </para>
-
-    <section id="bcf2000-example">
-      <title>Example</title>
-      <para>
-        We want to map the Master fader in Ardour to the first slider on the
-        BCF. Hold down the <keycap>Ctrl</keycap> key on your keyboard, and
-        click with <mousebutton>Button2</mousebutton> on the Master fader in
-        Ardour. You should see the <guilabel>operate MIDI controller
-        now</guilabel>. Move the first slider on the BCF up or down a bit.
-        The window should disappear, and you should see the master fader
-        move up and down as you move the slider on the BCF. If that works,
-        move the fader in Ardour with your mouse. You should see the slider
-        on the BCF move up and down in tandem with the Master fader!
-      </para>
-
-      <para>
-        If the "operate MIDI controller now" window does not go away, there
-        is no connection between Ardour and the BCF. Make sure you've
-        properly connected the two as outlined in the Connecting to Ardour
-        section.
-      </para>
-    </section>
-
-    <section id="bcf2000-transport-controls">
-      <title> Transport Controls </title>
-      <para>
-        The 4 buttons in the lower right corner are already mapped in Preset
-        2 to the MMC transport controls Home (or rewind to the beginning of
-        the session), Fast Forward, Stop and Play, as shown here.
-      </para>
-      <mediaobject>
-        <imageobject>
-          <imagedata fileref="images/transctls.jpg"/>
-        </imageobject>
-      </mediaobject>
-    </section>
-  </section>
-
-  <section id="bcf2000-saving-and-loading-presets">
-    <title> Saving and Loading Presets </title>
-    <para>
       After beating my head against a wall trying to get various programs
       that handle SysEx messages to do what I wanted, I realized that once
       again, the simplest way for me to do this the first time through is
@@ -515,18 +227,18 @@
     <para>
       There's the BCF, at port hw:2 (we can ignore everything after the
       first number after the colon). We'll tell amidi to use this port with
-      the -p option
+      the -p option.
     </para>
 
     <section id="bcf2000-saving-a-preset">
-      <title> Saving a Preset </title>
+      <title>Saving a Preset</title>
       <para>
         There's 2 parts to saving a preset: telling the BCF to send the
         data, and telling the computer to accept it.
       </para>
 
       <section id="bcf2000-recieving-the-data">
-        <title> Receiving the Data </title>
+        <title>Receiving the Data</title>
         <para>
           Run <command>amidi</command>, using the <option>-p</option> option
           to specify the port, and the <option>-r</option> option to receive
@@ -544,7 +256,7 @@
       </section>
 
       <section id="bcf2000-sending-the-data">
-        <title> Sending the Data </title>
+        <title>Sending the Data</title>
         <para>
           To send the MIDI data for the current preset to the computer, hold
           down the Edit key on the BCF and press the Store button. They
@@ -552,7 +264,7 @@
 <screen>
 	EG
 </screen>
-          . This is the Global Edit mode.
+          This is the Global Edit mode.
         </para>
 
         <para>
@@ -566,7 +278,7 @@
 <screen>
 	SnGl
 </screen>
-          . When ready to send the data, press knob 6. The display on the
+          When ready to send the data, press knob 6. The display on the
           BCF will circle around while it's sending data, and return to
 <screen>
 	EG
@@ -591,11 +303,10 @@
     </section>
 
     <section id="bcf2000-loading-a-preset">
-      <title> Loading a Preset </title>
+      <title>Loading a Preset</title>
       <para>
         Loading a .syx file, such as the one saved above, is very simple.
-        First, select the preset on the BCF to choose the preset to
-        overwrite. Then call <command>amidi</command> using the
+        Call <command>amidi</command> using the
         <option>-s</option> option instead of <option>-r</option> to send a
         file.
       </para>
@@ -609,8 +320,8 @@
       </para>
 
       <para>
-        The preset is now loaded with the settings from the file. They are
-        only active as long as the preset is not changed. If you go to
+        The preset is now loaded with the settings from the file, but they are
+        not yet saved into the preset. If you go to
         another preset and back to the one you loaded, all the changes will
         have disappeared. To save the settings,
       </para>
@@ -628,8 +339,7 @@
         </listitem>
         <listitem>
           <para>
-            Press STORE again to write the settings to an empty preset. If
-            you want to overwrite an existing preset, press STORE twice. You
+            Press STORE again to write the settings to an empty preset. You
             can cancel the store at any time by pressing EXIT.
           </para>
         </listitem>
@@ -637,8 +347,10 @@
     </section>
   </section>
 
+  <!-- ## Commented out, because I don't know whether it is up-to-date -->
+  <!--
   <section id="bcf2000-bcedit">
-    <title> Using BCEdit </title>
+    <title>Using BCEdit</title>
     <para>
       The tool provided by Behringer to manage presets and other things on
       the BCF is the Java program
@@ -664,8 +376,80 @@
       be fully usable under Linux yet.
     </para>
   </section>
-<!--
-	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-		href="Some_Subsection.xml" />
-	-->
+  -->
+
+  <section id="updating-firmware">
+    <title>Firmware Updating</title>
+    <para>
+      Updating the firmware in the unit is a relatively painless process:
+    </para>
+    <orderedlist>
+      <listitem>
+        <para>
+          Download the firmware from Behringers
+          <ulink url="http://www.behringer.com/EN/Support/B-Control-Downloads.aspx">downloads
+          page</ulink>. There will be a
+          <ulink url="http://www.behringerdownload.de/B-Control_download/bcf2000_1-10.zip">zip
+            file</ulink> available for the BCF2000 which should be downloaded.  
+          For the BCR2000, the corresponding file is <ulink 
+            url="http://www.behringerdownload.de/B-Control_download/bcr2000_1-10.zip">here</ulink>.
+        </para>
+        <note>
+          <title>Note</title>
+          <para>
+            There may be newer firmware files available than the ones linked 
+            here.
+          </para>
+        </note>
+        
+      </listitem>
+      <listitem>
+        <para>
+          Unzip the file you downloaded. You'll typically extract 2 files, a
+          PDF file with release notes and an SYX file, which is the firmware
+          update.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Find the system device of the BCF
+        </para>
+<screen>
+xtc:~% cat /proc/asound/cards
+0 [M1010          ]: ICE1712 - M Audio Delta 1010
+                     M Audio Delta 1010 at 0xdf80, irq 
+2 [BCF2000        ]: USB-Audio - BCF2000
+                     BEHRINGER BCF2000 at usb-00:1d.1-2, full speed
+</screen>
+      </listitem>
+    </orderedlist>
+    <para>
+      In this case there are 2 devices. The number at the left indicates the
+      card number. The BCF is almost certain, then, to use the device
+      <filename>/dev/snd/midiCnD0</filename> where <emphasis>n</emphasis> is
+      the card number, in this case, 2.
+    </para>
+
+    <para>
+      Write the firmware to the BCF with the command
+    </para>
+<screen>
+cat bcf2000_1-07.syx > /dev/snd/midiC2D0	
+</screen>
+    <important>
+      <para>
+        Make sure you use the actual device you determined in the previous
+        step.
+      </para>
+    </important>
+
+    <para>
+      The BCF display will show a whirling figure-8 animation and count up
+      to 18. Once the whirling stops, you should turn off the BCF, count to
+      5, then turn it on again. You should then see the version number of
+      the upgraded firmware displayed for a few seconds as the BCF starts.
+    </para>
+  </section>
+
 </section>
+
Index: frontier_design_tranzport.xml
===================================================================
--- frontier_design_tranzport.xml	(revision 4410)
+++ frontier_design_tranzport.xml	(working copy)
@@ -11,13 +11,57 @@
     <para>
       Ardour 2.0 can currently use a single Tranzport controller. Ensure
       that the device is plugged into a functional USB port. On Linux you
-      will need to <link linkend="sn-configuring-usb-device-access">take
-      steps</link> to ensure that non-administrative users can access the
-      device. Note that this feature is <emphasis>not</emphasis> available
-      in Ardour 0.99.x.
+      will need to take steps to ensure that non-administrative users can 
+      access the device. Note that this feature is <emphasis>not</emphasis> 
+      available in Ardour 0.99.x.
     </para>
+    <!-- TODO: what about MAC? Will it work without further config? -->
 
+    <!-- TODO: the following text is out-of-date. These days, one would use 
+    udev, but this must be rewritten by someone who has a tranzport. -->
+    <important>
+      <title>Important</title>
+      <para>
+        The following instructions are out-of-date and may not work for you.  
+        These days, one would use udev instead of the old-fashion hotplug 
+        system.
+      </para>
+    </important>
+    
     <para>
+      First, you need to login as the administrative user ("root"). Then put
+      the following into a new file called
+      <filename>/etc/hotplug/usb/tranzport</filename>
+    </para>
+<screen>
+#!/bin/sh
+
+if [ $ACTION = "add" ] &amp;&amp; [ -f $DEVICE ] ; then
+    chmod 0666 $DEVICE
+fi
+exit 0
+</screen>
+    <para>
+      Then make sure that the file is executable by running
+    </para>
+<screen>
+chmod +x /etc/hotplug/usb/tranzport
+</screen>
+    <para>
+      Second, edit the file <filename>/etc/hotplug/usb.usermap</filename> by
+      adding the following 2 lines to the end of it (make sure that the 2nd
+      line is not split across multiple lines, even though it is very long):
+    </para>
+<screen>
+# Frontier Design Tranzport
+tranzport            0x0000      0x165b   0x8101    0x0000       0x0000      0x00         0x00            0x00            0x00          0x00               0x00               0x00000000
+</screen>
+    <para>
+      After doing these steps, the next time you plugin your Tranzport it
+      will be accessible to you as a regular user.
+    </para>
+
+    <para>
       In the Options menu, navigate into the Control Surfaces submenu. Click
       on the "Tranzport" option to enable use of the control surface within
       Ardour. To disable it, click on this item a second time.
