Add the ardour manual converted to docbook format with only a few minor

additions.

Add dbhelper.vim key stroke mappings I use for working with docbook source.

There are no xsl or css files for customizing the html output so it will 
look really boring...this will only be temporary.

Support for content localization and generation of pdf's is planned.



git-svn-id: svn://localhost/ardour2/trunk@1405 d708f5d6-7413-0410-9779-e7cbd77b26cf

1 files changed, 148 insertions, 0 deletions

diff --git a/manual/xml/working_with_layers.xml b/manual/xml/working_with_layers.xml
new file mode 100644
index 0000000000..4f6d248d55
--- /dev/null
+++ b/manual/xml/working_with_layers.xml
@@ -0,0 +1,148 @@
+<?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-layers">
+	<title>Working with layers</title>
+	<para>
+		It is possible to arrange regions in a playlist (track) so that they overlap
+		- one starts before another finishes, for example. Because of this, its
+		important that there is a clear and understandable rule for what you will
+		hear when playing back these kinds of region arrangements.
+	</para>
+
+	<para>
+		Every region in a playlist is assigned to a layer. There can only ever be
+		one region on a given layer, although rearranging the playlist (track) may
+		change which region is on which layer. At any given point along the
+		timeline, you will hear the uppermost region at that point.
+	</para>
+
+	<para>
+		Of course, nothing in digital audio is ever quite that simple, and so of
+		course there are some complications:
+	</para>
+
+	<section id="layers-crossfades">
+		<title> Crossfades </title>
+		<para>
+			Whenever two regions overlap, there is the potential for a
+			<link linkend="sn-working-with-crossfades">crossfade</link> between them.
+			If the crossfade is not muted, then you will hear the contents of the
+			crossfade during the overlap, not just the uppermost region.
+		</para>
+	</section>
+
+	<section id="region-opacity">
+		<title> Region Opacity </title>
+		<para>
+			In a perverse nod to image manipulation programs, Ardour allows you to make
+			regions transparent. By default, all regions are created opaque, which
+			means that when they are playing, no region below them are audible.
+			However, if you change the region to be transparent, the region will be
+			audible together with any regions below it. This capability should probably
+			not be abused - if you really want to mix sounds together in this way, they
+			should probably live in their own tracks. Occasionally though, this can be
+			useful trick.
+		</para>
+
+		<para>
+			To change the opacity of a region, popup the region's editor, accessible by
+			context clicking on the region. Then click on the "opaque" button, turning
+			it on or off as desired.
+		</para>
+	</section>
+
+	<section id="layering-styles">
+		<title> Layering Styles </title>
+		<para>
+			When you are recording new material for a track, its typical to want to new
+			material recorded "over" existing material in the track to be what you hear
+			on playback. For example, if you overdub part of a guitar solo, you
+			normally want the overdub to be audible, not hidden by the old version that
+			was already there. By contrast, when editing using
+			splitting/trimming/moving of regions to create a particular arrangement
+			along the timeline, many people find that they want regions that start
+			later on the timeline to be the ones that are audible.
+		</para>
+
+		<para>
+			To facilitate these two contradictory desires, Ardour features three
+			different styles for assigning regions to layers.
+		</para>
+
+		<variablelist>
+			<title></title>
+			<varlistentry>
+				<term>Most recently added regions are higher</term>
+				<listitem>
+					<para>
+						Use this style when recording/overdubbing new material. Edits of any
+						kind do not modify the layering.
+					</para>
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term>Most recently added/moved/trimmed regions are higher</term>
+				<listitem>
+					<para>
+						Use this style when recording/overdubbing new material, but you want
+						basic edits to cause regions to rise to the top.
+					</para>
+				</listitem>
+			</varlistentry>
+
+			<varlistentry>
+				<term>Later regions are higher</term>
+				<listitem>
+					<para>
+						Use this style when rearranging and editing regions.
+					</para>
+				</listitem>
+			</varlistentry>
+		</variablelist>
+
+		<para>
+			A new session has the layering style set to "Most recently
+			added/moved/trimmed regions are higher". To change the layering style, open
+			the <emphasis>options editor</emphasis> and select the "Layers&amp;Fades"
+			page. There is an option there to select the style you want. Layering style
+			may be changed at any time. The existing layering of all playlists is not
+			changed when changing the layering model.
+		</para>
+	</section>
+
+	<section id="modifying-layering-by-hand">
+		<title> Modifying Layering By Hand </title>
+		<para>
+			If you want a particular region to be the uppermost when the current
+			layering style has put it on a lower layer, context click on the region.
+			Select the region from the menu that pops up, and in the submenu that
+			appears, choose one of "Move region to lowest layer" or "Move region to
+			upper layer". The layering for the playlist will be recalculated to ensure
+			that the region is on the layer you chose. Note: these operations only have
+			any effect if using one of the "Most recently .." layer models.
+		</para>
+
+		<para>
+			You can see the precise layer a region is assigned in the popup region
+			editor, accessible by context clicking on the region.
+		</para>
+
+		<note>
+			<para>
+				At one time, Ardour offered more explicit control over the layering,
+				allowing you to move regions up or down to specific layers. This was found
+				to be problematic, confusing, and generally rendered unnecessary by both
+				of the layering styles the program now offers.
+			</para>
+		</note>
+	</section>
+<!--
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+		href="Some_Subsection.xml" />
+	-->
+</section>