Merged with trunk R1612.

git-svn-id: svn://localhost/ardour2/branches/midi@1614 d708f5d6-7413-0410-9779-e7cbd77b26cf

1 files changed, 645 insertions, 0 deletions

diff --git a/manual/xml/working_with_regions.xml b/manual/xml/working_with_regions.xml
new file mode 100644
index 0000000000..1c8cea8209
--- /dev/null
+++ b/manual/xml/working_with_regions.xml
@@ -0,0 +1,645 @@
+<?xml version="1.0" standalone="no"?>
+
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+]>
+
+<section id="sn-working-with-regions">
+  <title>Working with Regions</title>
+  <para>
+    Regions are the basic elements of editing and composing in Ardour. Each
+    region represents a single, contiguous section of one or more audio
+    files. Regions are defined by a fixed set of attributes:
+  </para>
+
+  <itemizedlist>
+    <listitem>
+      <para>
+        the source audio file(s) they represent
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        a starting point in the audio file(s)
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        a length
+      </para>
+    </listitem>
+  </itemizedlist>
+
+  <para>
+    When placed into a
+    <glossterm linkend="gt-playlist">playlist</glossterm>, they gain
+    additional attributes:
+  </para>
+
+  <itemizedlist>
+    <listitem>
+      <para>
+        a position along the timeline
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        a layer
+      </para>
+    </listitem>
+  </itemizedlist>
+
+  <para>
+    There are <emphasis>other attributes</emphasis> as well, but they do not
+    define the region. Things you should know about regions:
+  </para>
+
+  <variablelist>
+    <title></title>
+    <varlistentry>
+      <term>Regions are Cheap</term>
+      <listitem>
+        <para>
+          By themselves, regions do not consume hardly any of your
+          computer's resources. Each region requires a small amount of
+          memory, and represents a rather small amount of CPU work if placed
+          into an active track. So, don't worry about creating regions
+          whenever you need to.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>Regions are not audio files</term>
+      <listitem>
+        <para>
+          Although a region can represent an entire audio file, they are
+          never equivalent to an audio file. Most regions represent just
+          parts of an audio file(s) on disk, and removing a region from a
+          track has nothing to do with removing the audio file(s) from the
+          disk ((the <emphasis>Destroy</emphasis> operation, one of Ardour's
+          few destructive operations, can affect this)). Changing the length
+          of a region has no effect on the audio file(s) on disk. Splitting
+          and copying regions does not alter the audio file in anyway, nor
+          does it create new audio files ((the <emphasis>Export</emphasis> ,
+          <emphasis>Bounce</emphasis> and <emphasis>Reverse</emphasis>
+          operations do create new audio files)).
+        </para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
+  <section id="region-naming">
+    <title>Region Naming</title>
+    <para>
+      Regions are initially named using either:
+    </para>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          the name of the playlist for which they were recorded
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          the name of the embedded/imported audio file they represent
+        </para>
+      </listitem>
+    </itemizedlist>
+
+    <section id="whole-file-region-names">
+      <title>Whole File Region Names</title>
+      <para>
+        These are not audio files, but regions that represent the full
+        extent of an audio file. Every time a new recording is done, or a
+        new file is embedded/imported, a new region is created that
+        represents the entire audio file(s) This region will have the name
+        of the playlist/original file, followed by a "-" and then a number.
+      </para>
+
+      <para>
+        For recorded regions, the number will increase each time a new
+        recording is made. So, for example, if there is a playlist called
+        "Didgeridoo", the first recorded whole file region for that playlist
+        will be called "Digderidoo-1". The next one will be "Digeridoo-2"
+        and so on.
+      </para>
+
+      <para>
+        For imported/embedded files, the region name will be based on the
+        file name, but with any final suffix (e.g. ".wav" or ".aiff")
+        removed.
+      </para>
+
+      <para>
+        Normally, whole file regions are not inserted into tracks/playlists,
+        but regions derived from them are. The whole-file versions live in
+        the editor region list where they act as an organizing mechanism for
+        regions that are derived from them.
+      </para>
+    </section>
+
+    <section id="normal-region-names">
+      <title>Normal Region Names</title>
+      <para>
+        When a region is inserted into a track/playlist, its initial name
+        will end in a version number, such as ".1" or ".103". For a recorded
+        region, if the whole file region was "Hang drum-1", then the region
+        in the track will appear with the name "Hang drum-1.1". For an
+        imported/embedded region, if the whole file region was
+        "Bach:Invention3", then the region in the track will appear with the
+        name "Bach:Invention3.1".
+      </para>
+    </section>
+
+    <section id="copied-region-names">
+      <title>Copied Region Names</title>
+      <para>
+        If the region is a copy of another region, it will begin life with
+        the same name as the original. When an operation is carried out that
+        modifies one of the copies, that particular copy will be renamed by
+        incrementing the version number.
+      </para>
+    </section>
+
+    <section id="renaming-regions">
+      <title>Renaming Regions</title>
+      <para>
+        You can rename a region at any time. Use the <emphasis>region
+        context menu</emphasis> to popup the rename dialog. The new name
+        does not need to have a version number in it (in fact, it probably
+        should not). The region will retain its name until it is modified
+        after being copied.
+      </para>
+    </section>
+  </section>
+
+  <section id="selecting-regions">
+    <title>Selecting Regions</title>
+    <para>
+      In general, operations on regions apply to whichever regions are
+      currently <emphasis>selected</emphasis> .
+    </para>
+
+    <para>
+      To select a single region, click on it using
+      <mousebutton>Button1</mousebutton>.
+    </para>
+
+    <para>
+      To add an unselected region to the currently selected regions, click
+      on it using
+      <keycombo><keycap>Shift</keycap><mousebutton>Button1</mousebutton></keycombo>.
+    </para>
+
+    <para>
+      To remove a selected region from the currently selected regions, click
+      on it using
+      <keycombo><keycap>Shift</keycap><mousebutton>Button1</mousebutton></keycombo>.
+    </para>
+  </section>
+
+  <section id="removing-regions">
+    <title>Removing Regions</title>
+    <para>
+      Select the region(s) to be removed. Then press the "Delete" key or use
+      the standard key binding for "Cut" (
+      <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo> by
+      default).
+    </para>
+
+    <para>
+      Note that "removing" a region is a non-destructive operation. It has
+      no effect on the audio file(s) stored on disk. If you really want to
+      destructively remove the region, use the context menu for the region
+      which has a "Destroy" item. This is not guaranteed to remove the audio
+      file from your disk storage, but it generally will.
+    </para>
+  </section>
+
+  <section id="moving-regions">
+    <title>Moving Regions</title>
+    <para>
+      To move a region, make sure you are in <emphasis>object</emphasis>
+      mouse mode. Move the mouse pointer into the waveform display part of
+      the region, press <mousebutton>Button1</mousebutton> and drag. The
+      region will follow the mouse pointer as you move it around. By
+      default, the region can move freely along the timeline - see
+      <xref linkend="sn-snap-settings"/> for information on how to force the
+      region to align to certain kinds of points along the timeline.
+    </para>
+
+    <para>
+      To move a region from one track to another, simply start a move as
+      described above, but move the mouse pointer into the desired track.
+      The region will follow the mouse pointer. Note that if you have other
+      kinds of "tracks" visible, the region will remain where it is as the
+      mouse pointer moves across them, and will then jump to the new track.
+      This serves as a visual reminder that you cannot drag an audio region
+      into an automation track or a bus, for example.
+    </para>
+
+    <section id="moving-more-than-one-region">
+      <title>Moving more than one region</title>
+      <para>
+        To move multiple regions, select them before moving. Then click+drag
+        on one of the selected regions. All the regions will move, keeping
+        their positions relative to each other.
+      </para>
+    </section>
+
+    <section id="region-fixed-time-motion">
+      <title>Fixed-time motion</title>
+      <para>
+        Sometimes, you want to move a region to another track, but keeping
+        its position along the timeline exactly the same. To do this, use
+        <mousebutton>Button2</mousebutton> rather than
+        <mousebutton>Button1</mousebutton>.
+      </para>
+    </section>
+  </section>
+
+  <section id="copying-regions">
+    <title>Copying Regions</title>
+    <para>
+      To copy a region, make sure you are in <emphasis>object</emphasis>
+      mouse mode. Move the mouse pointer into the waveform press the
+      <keycap>Ctrl</keycap> key, keep it down while pressing
+      <mousebutton>Button1</mousebutton> and drag. A new region is created
+      and will follow the mouse pointer as it moves. See
+      <xref linkend="moving-regions"/> for more details on moving the copied
+      region around.
+    </para>
+
+    <section id="copying-more-than-one-region">
+      <title>Copying more than one region</title>
+      <para>
+        To copy multiple regions, select them before copying. Then
+        click+drag on one of the selected regions. All the regions will be
+        copied and as they move, the will keep their positions relative to
+        each other.
+      </para>
+    </section>
+
+    <section id="region-fixed-time-copying">
+      <title>Fixed-time copying</title>
+      <para>
+        If you want to copy region(s) to other track(s) but keep the copies
+        at the exact position on the timeline as the originals, simply use
+        <keycombo><keycap>Ctrl</keycap><mousebutton>Button2</mousebutton></keycombo>
+        instead of
+        <keycombo><keycap>Ctrl</keycap><mousebutton>Button1</mousebutton></keycombo>.
+      </para>
+    </section>
+  </section>
+
+  <section id="trimming-regions">
+    <title>Trimming Regions</title>
+    <para></para>
+  </section>
+
+  <section id="auditioning-regions">
+    <title>Auditioning Regions</title>
+    <para></para>
+  </section>
+
+  <section id="region-gain-envelopes">
+    <title>Region Gain Envelopes</title>
+    <para></para>
+  </section>
+
+  <section id="region-context-menu">
+<!-- needs work -->
+    <title>Region Context Menu</title>
+    <para>
+      If you context-click on a region, a popup menu will appear. At or near
+      the top of that menu is a list of all regions that exist in the
+      clicked-upon track under the mouse pointer. Each region entry (shown
+      by name) points to a submenu that contains region-specific operations:
+    </para>
+
+    <variablelist>
+      <title></title>
+      <varlistentry>
+        <term><guilabel>Popup region editor</guilabel></term>
+        <listitem>
+          <para>
+            creates and displays the editor for this region, allowing even
+            more specific control over the region than this menu
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Raise to top layer</guilabel></term>
+        <listitem>
+          <para>
+            moves the region to the top layer of this track (works only in
+            "Most recently added/moved/trimmed regions are higher"
+            <emphasis>layer mode</emphasis>
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Lower to bottom layer</guilabel></term>
+        <listitem>
+          <para>
+            moves the region to the bottom layer of this track (works only
+            in "Most recently added/moved/trimmed regions are higher"
+            <emphasis>layer mode</emphasis>
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Define sync point</guilabel></term>
+        <listitem>
+          <para>
+            if the edit cursor is within this region, defines the region
+            sync point at the edit cursor location.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Remove sync point</guilabel></term>
+        <listitem>
+          <para></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Audition</guilabel></term>
+        <listitem>
+          <para>
+            plays this region via the
+            <glossterm linkend="gt-auditioner">auditioner</glossterm>
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Export</guilabel></term>
+        <listitem>
+          <para>
+            exports this region to a new audio file, via the export dialog
+            (thus allowing resampling, dithering, format specification etc.)
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Bounce</guilabel></term>
+        <listitem>
+          <para>
+            re-records this region (with any plugins/inserts applied) to a
+            new audio file, and replaces the region with one referring to
+            the new file.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Lock</guilabel></term>
+        <listitem>
+          <para>
+            prevents the region from being moved, trimmed, or modified in
+            almost any way.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Unlock</guilabel></term>
+        <listitem>
+          <para>
+            removes the lock on region modification
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Mute</guilabel></term>
+        <listitem>
+          <para>
+            makes the region silent during playback
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Unmute</guilabel></term>
+        <listitem>
+          <para></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Toggle envelope visibility</guilabel></term>
+        <listitem>
+          <para>
+            shows/hides the region gain envelope
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Toggle envelope active</guilabel></term>
+        <listitem>
+          <para>
+            turns the region gain envelope on/off (the line is gray when the
+            envelope is off, green when it is on)
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Original position</guilabel></term>
+        <listitem>
+          <para>
+            if the region was recorded (and Broadcast WAVE was the native
+            file format) moves the region to its original capture position
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Normalize</guilabel></term>
+        <listitem>
+          <para>
+            alters the gain processing of the region so that the loudest
+            sample is at 0dBFS
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>DeNormalize</guilabel></term>
+        <listitem>
+          <para>
+            undoes the effect of a normalize
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Reverse</guilabel></term>
+        <listitem>
+          <para>
+            writes the region to a new audio file with the contents
+            reversed, and replaces the region with one referring to the new
+            file
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Nudge</guilabel></term>
+        <listitem>
+          <para>
+            moves the region in various ways
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Nudge fwd</guilabel></term>
+        <listitem>
+          <para>
+            moves the region forward by the amount shown in the nudge clock
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Nudge bwd</guilabel></term>
+        <listitem>
+          <para>
+            moves the region backward by the amount shown in the nudge clock
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Nudge fwd by capture offset</guilabel></term>
+        <listitem>
+          <para>
+            moves the region forward by the same offset that it might have
+            been (incorrectly) adjusted by when captured
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Nudge bwd by capture offset</guilabel></term>
+        <listitem>
+          <para>
+            moves the region backwards by the same offset that it might have
+            been (incorrectly) adjusted by when captured
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Trim</guilabel></term>
+        <listitem>
+          <para></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Start to edit cursor</guilabel></term>
+        <listitem>
+          <para>
+            adjusts the start of the region to the current position of the
+            edit cursor (if possible)
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Edit cursor to end</guilabel></term>
+        <listitem>
+          <para>
+            adjusts the end of the region to the current position of the
+            edit cursor (if possible)
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Split</guilabel></term>
+        <listitem>
+          <para>
+            if the edit cursor is within the region, splits the region at
+            the editor cursor location
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Make mono regions</guilabel></term>
+        <listitem>
+          <para>
+            if the region is a multi-channel one, creates new regions
+            corresponding to each channel. The new regions are added to the
+            editor's region list, not the track.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Duplicate</guilabel></term>
+        <listitem>
+          <para>
+            pops up a dialog allowing the region to be copied 1 or more
+            times. Each copy is placed directly after the original or
+            previous copy.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Fill Track</guilabel></term>
+        <listitem>
+          <para>
+            copies the region as many times as necessary to fill the track
+            to the current session end mark. Each copy is placed directly
+            after the original or previous copy.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Remove</guilabel></term>
+        <listitem>
+          <para>
+            remove the region from the track (non-destructive)
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><guilabel>Destroy</guilabel></term>
+        <listitem>
+          <para>
+            remove the region from the track and the editor region list, and
+            if no other regions are referencing it, remove the audio file
+            that the region is derived from. (
+            <emphasis>DESTRUCTIVE</emphasis> )
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+<!--
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+		href="Some_Subsection.xml" />
+	-->
+</section>