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, 220 insertions, 0 deletions

diff --git a/manual/xml/working_with_crossfades.xml b/manual/xml/working_with_crossfades.xml
new file mode 100644
index 0000000000..c82d6d7f27
--- /dev/null
+++ b/manual/xml/working_with_crossfades.xml
@@ -0,0 +1,220 @@
+<?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-crossfades">
+	<title>Working with Crossfades</title>
+	<para>
+		Whenever you arrange any two audio regions so that they overlap in any way,
+		you create the potential for a <link linkend="gt-crossfade">crossfade</link> between them:
+		a smooth transition from one region to the other. Crossfades in Ardour are
+		generated in realtime, and are not stored on disk. They are objects within a
+		playlist just like regions, except that the only way to create a crossfade
+		is by overlapping two regions, and the only way to remove a crossfade is to
+		move one or both of the regions so that they no longer overlap. Note that
+		crossfades are not always audible (they can be muted and unmuted at will),
+		and can be edited in a variety of ways. We think of a crossfade as
+		consisting of an overlap between two regions, plus two gain control curves
+		that control the volume of the incoming and outgoing regions during the
+		crossfade.
+	</para>
+
+	<section id="crossfade-types">
+		<title>Types of crossfades</title>
+		<para>
+			Ardour comes with two basic kinds of crossfades, termed <emphasis>short
+			crossfades</emphasis> and <emphasis>full crossfades</emphasis> . A full
+			crossfade is a transition between two regions that spans the entire overlap
+			between them. If the overlap is 2 seconds long, then the crossfade is 2
+			seconds long. A short crossfade is a transition between two regions that
+			lasts a fixed amount of time and serves simply to avoid audio glitches at
+			the boundary of the two regions. The length of a short crossfade is a
+			session-wide parameter than can be set via the <emphasis>option
+			editor</emphasis> . The default is 15ms, and the length can vary from 1
+			milliseconds to 0.5 seconds. In the current version of Ardour, it is not
+			possible to change the length of a short becrossfade after it has been
+			created, but it is possible to change most short crossfades to a full
+			crossfade and vice versa. Full crossfades can have their length altered by
+			changing the extent of the overlap between the two regions.
+		</para>
+
+		<para>
+			Note that even though the absolute length of the crossfade is fixed,
+			crossfades can be <emphasis>edited</emphasis> with complete freedom,
+			allowing you change the effective length of a crossfade by altering the
+			shapes of the fade in and fade out curves.
+		</para>
+	</section>
+
+	<section id="crossfade-overlaps">
+		<title>Overlaps</title>
+		<para>
+			There are several different ways to overlap two regions, and they result in
+			different kinds of crossfades being placed at the boundaries of the two
+			regions:
+		</para>
+
+		<section id="external-overlaps">
+			<title>External overlaps</title>
+			<para>
+				An "external" overlap occurs when a region starts within another region,
+				but extends beyond the other's end.
+			</para>
+			<mediaobject>
+				<imageobject>
+					<imagedata fileref="images/overlaplaterhigher.png"/>
+				</imageobject>
+			</mediaobject>
+
+			<para>
+				Overlaps like this will cause an xfade to be placed at the start of the
+				later region. Whether it is a full or short crossfade is controlled by the
+				current crossfade type preference. If short crossfades have been chosen,
+				the crossfade will last for the current short crossfade duration;
+				otherwise the full crossfade will last for the entire overlap. The mute
+				status of the crossfade will depend on the current state of the "New
+				crossfades are muted" setting.
+			</para>
+
+			<para>
+				In the example above, the later region is above the earlier one. It is
+				also possible to create an overlap where the earlier region is in a higher
+				layer:
+			</para>
+			<mediaobject>
+				<imageobject>
+					<imagedata fileref="images/overlapearlyhigher.png"/>
+				</imageobject>
+			</mediaobject>
+			<para>
+				For an overlap of this type, the current crossfade type preference affects
+				the placement of the crossfade. If full crossfades have been chosen, the
+				crossfade will be placed at the start of the later region and will last
+				for the entire overlap. If short crossfades have been chosen, the
+				crossfade will start just before the end of the earlier region and will
+				last for the chosen short crossfade duration. The mute status of the
+				crossfade will depend on the current state of the "New crossfades are
+				muted" setting.
+			</para>
+		</section>
+
+		<section id="internal-overlaps">
+			<title>Internal overlaps</title>
+			<para>
+				An "internal" overlap occurs when the start and end of one region both
+				occur within the duration of another.
+			</para>
+			<mediaobject>
+				<imageobject>
+					<imagedata fileref="images/internalhigheroverlap.png"/>
+				</imageobject>
+			</mediaobject>
+
+			<para>
+				Overlaps of this type will cause two short crossfades to be place at the
+				start of the later region and close to its end. Both crossfades will last
+				for the current short crossfade duration, and are created in an un-muted
+				state. These crossfades <emphasis>cannot</emphasis> be converted to full
+				crossfades. It is important to realize that the purpose of these two
+				crossfades is a little different than those created for the single-ended
+				overlap cases above. They are created solely to avoid audio glitches at
+				the transitions between the two regions, and are not intended to
+				facilitate interesting crossfades between the upper and lower region.
+			</para>
+
+			<para>
+				Notice that in the example above, the shorter region is above the longer
+				one. It is also possible to create the following type of overlap, where
+				the shorter region is below the longer one:
+			</para>
+			<mediaobject>
+				<imageobject>
+					<imagedata fileref="images/internalloweroverlap.png"/>
+				</imageobject>
+			</mediaobject>
+
+			<para>
+				Overlaps of this type will not cause any crossfades to be created. The
+				uppermost region will be audible throughout its duration; the lowermost
+				region will not be audible at all.
+			</para>
+		</section>
+	</section>
+
+	<section id="creating-crossfades">
+		<title>Creating Crossfades</title>
+		<para>
+			To create a crossfade between two regions, move them so that they overlap.
+			A crossfade is automatically created within the overlap (possibly two,
+			dependening on the type of overlap, as explained above). Whether the
+			crossfade is muted or not depends on two things:
+		</para>
+
+		<itemizedlist>
+			<listitem>
+				<para>
+					if the current crossfade type is set to "Short", the new crossfade will
+					be created in an un-muted state
+				</para>
+			</listitem>
+			<listitem>
+				<para>
+					if the current crossfade type is set to "Full", the mute status of the
+					new crossfade is controlled from the <emphasis>option editor</emphasis>
+					on the "Layers&amp;Fades" control panel. If "New crossfades are unmuted",
+					the new crossfade will be unmuted.
+				</para>
+			</listitem>
+		</itemizedlist>
+
+		<para>
+			A muted crossfade is not directly visible in the editor window, but can be
+			accessed by context clicking within the overlap that it relates to. An
+			unmuted crossfade has a yellow background that covers the entire overlap
+			(to make its presence obvious at all times), and a pair of visible curves
+			that show the gain control curves for the fade. These curves may not be
+			visible at a particular zoom level, especially for short crossfades.
+		</para>
+	</section>
+
+	<section id="editing-crossfades">
+		<title>Editing Crossfades</title>
+		<para>
+			To carry out operations on a crossfade, context click anywhere in the
+			overlap. For the short crossfades in the "internal" overlap case, you will
+			need to zoom in until the crossfade becomes visible, and then context click
+			on it. Each crossfade under the mouse pointer (there is normally only one)
+			will appear in the context menu, and will lead to a submenu offering the
+			following options:
+		</para>
+
+		<itemizedlist>
+			<listitem>
+				<para>
+					Mute/Unmute the crossfade
+				</para>
+			</listitem>
+			<listitem>
+				<para>
+					Edit the crossfade
+				</para>
+			</listitem>
+			<listitem>
+				<para>
+					change the crossfade from short to full or vice versa
+				</para>
+			</listitem>
+		</itemizedlist>
+
+		<para>
+			The last option is not available for the short crossfades in the "internal"
+			overlap case.
+		</para>
+	</section>
+<!--
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+		href="Some_Subsection.xml" />
+	-->
+</section>