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

diff --git a/manual/xml/editor_window_controls.xml b/manual/xml/editor_window_controls.xml
new file mode 100644
index 0000000000..dbd152f0d1
--- /dev/null
+++ b/manual/xml/editor_window_controls.xml
@@ -0,0 +1,316 @@
+<?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="editor-window-controls">
+	<title>Editor Controls</title>
+	<para>
+		The editor controls are in a tearoff window, which you can use in the usual
+		way.
+	</para>
+
+	<section id="editor-edit-cursor-clock">
+		<title>Edit cursor clock</title>
+		<para>
+			This clock shows the current position of the edit cursor. You can edit the
+			position using the clock if you wish.
+		</para>
+	</section>
+
+	<section id="editor-zoom-buttons">
+		<title>Zoom buttons</title>
+		<para>
+			The zoom buttons allow you to see more ("zoom out") or less
+			("zoom in") of the session timeline in the track display area.
+			Click on the zoom out button to zoom out, and the zoom in button to zoom
+			in.
+		</para>
+	</section>
+
+	<section id="editor-zoom-range-clock">
+		<title>Zoom range clock</title>
+		<para>
+			The zoom range clock shows the current duration of the timeline that is
+			visible in the track display area. It does not indicate the location of the
+			visible section of the timeline, only its length. You can zoom in and out
+			by editing this clock directly, which may be useful if you want to see a
+			precise duration within the editor.
+		</para>
+	</section>
+
+	<section id="editor-zoom-selectors">
+		<title>Zoom selectors</title>
+		<para>
+			The two zoom select buttons allow you to go to the maximum and minimum zoom
+			levels with a single button click. The "1:1" button zooms all
+			the way into single sample level, where each pixel on the screen represents
+			a single sample. The "whole session button" zooms out to show
+			the entire session in the track display area.
+		</para>
+	</section>
+
+	<section id="editor-zoom-focus-control">
+		<title>Zoom focus control</title>
+		<para>
+			When zooming, there is always a change in what is displayed in the track
+			display area. However, one position in the display will continue to
+			correspond to the same point in the timeline, and there are several choices
+			of how to define that point. The default behaviour is to keep the left edge
+			of the track display area constant. If it was at a position 1:12:14 into
+			the session timeline before zooming, then it will continue to be at that
+			position after zooming. Other points in the display that you can ensure are
+			in the same position while zooming include the right edge of the track
+			display, the center of the track display, the playhead and the edit cursor.
+			Whichever of these is selected is known as the current zoom focus.
+		</para>
+
+		<para>
+			To change the current zoom focus, click on the combo box to see the list of
+			available choices. Click on the zoom focus you wish to use. The list of
+			choices will disappear, and the new zoom focus choice will be in effect.
+		</para>
+	</section>
+
+	<section id="editor-snap-control">
+		<title>Snap control</title>
+		<para>
+			When moving objects around in the track display area, you have the choice
+			of moving them freely or having their positions be limited to certain
+			points along the timeline. This applies to region, the playhead, the edit
+			cursor, curve control points and markers, among others. If you want the
+			positions of objects to be limited, then you can choose from several
+			different possibilities. We call this "snap to" because when
+			moving objects around with the mouse, they appear to "snap to"
+			various positions.
+		</para>
+
+		<para>
+			The most obvious source of "snap to" positions is the tempo
+			map, but ardour offers many different possibilities:
+		</para>
+		<table id="tbl-snap-control"><title>Snap Control</title>
+			<tgroup cols = "2">
+				<colspec colnum="1" colname="Snap Option" colwidth="1"/>
+				<colspec colnum="2" colname="Action" colwidth= "2"/>
+				<thead>
+					<row>
+						<entry>
+							Snap Option
+						</entry>
+						<entry>
+							Action
+						</entry>
+					</row>
+				</thead>
+				<tbody>
+					<row>
+						<entry>
+							BBT
+						</entry>
+						<entry>
+							you can select 64th,32nd,16th,8th,quarter and whole beat positions, as
+							well as beat triplets and whole bars (measures).
+						</entry>
+					</row>
+					<row>
+						<entry>
+							Region beginnings
+						</entry>
+					</row>
+					<row>
+						<entry>
+							Region ends
+						</entry>
+					</row>
+					<row>
+						<entry>
+							Region sync points
+						</entry>
+					</row>
+					<row>
+						<entry>
+							Region boundaries
+						</entry>
+						<entry>
+							(combines regions beginnings and ends)
+						</entry>
+					</row>
+					<row>
+						<entry>
+							Marks
+						</entry>
+					</row>
+					<row>
+						<entry>
+							Edit Cursor
+						</entry>
+						<entry>
+							a single snap-to point. This is useful when aligning several objects at
+							the same point. Set the edit cursor to the desired position, then
+							select this snap setting, and then move the objects, which will
+							immediately snap to the chosen position.
+						</entry>
+					</row>
+				</tbody>
+			</tgroup>
+		</table>
+	</section>
+
+	<section id="editor-edit-mode-control">
+		<title>Edit mode control</title>
+		<para>
+			When moving regions around in a track, it is sometimes desirable to leave
+			spaces between regions and sometimes to force regions to always be placed
+			directly next to their neighbours. Which is more appropriate depends a lot
+			on the nature of the project and the regions themselves.
+		</para>
+
+		<para>
+			By default, Ardour uses slide mode which allows you to freely place regions
+			in a track (subject to the current snap setting, of course). If you cut
+			part of region, an empty space will remain where the part you removed used
+			to be. If you move a region along the timeline, it will move independently
+			of other regions, and will stay wherever you place it.
+		</para>
+
+		<para>
+			If you are editing a session and require behaviour where regions are forced
+			to always to be directly adjacent, you can switch to splice maybe. In this
+			mode, cutting part of region will cause all later regions in the track to
+			move up (earlier) the timeline so that there is no intervening space
+			between them. Moving a region will cause other regions to move around so
+			that the moved region fits "between" them.
+		</para>
+	</section>
+
+	<section id="editor-window-nudge-buttons">
+		<title>Nudge buttons</title>
+		<para>
+			Sometimes when editing its nice to be able to move objects by predefined
+			amounts rather than just positioning them freely or using snap-to. This
+			kind of motion is called nudging. At the present time, only the playhead,
+			playlists and regions can be nudged. The distance an object is nudged is
+			set by the nudge clock (see below).
+		</para>
+
+		<para>
+			To nudge one or more regions forward by 1 second, first edit the nudge
+			clock so that it specifies that time. Then select the region(s) by clicking
+			on them, and finally click the nudge forward button.
+		</para>
+
+		<para>
+			Nudging backwards is identical to nudging forwards, except that you should
+			click on the nudge backwards button.
+		</para>
+
+		<para>
+			To nudge a playlist forward or backwards, first set the nudge clock to the
+			desired nudge distance. Then in the track that is using the playlist.
+			Choose Nudge Nudge entire track fwd or Nudge nudge entire track bwd as
+			desired.
+		</para>
+
+		<para>
+			You can also nudge all regions in the playlist positioned after (later
+			than) the edit cursor. To do this, follow the steps for nudging the
+			playlist, but choose Nudge nudge track after edit cursor fwd or Nudge nudge
+			track after edit cursor bwd, as appropriate.
+		</para>
+	</section>
+
+	<section id="editor-window-nudge-clock">
+		<title>Nudge clock</title>
+		<para>
+			You can edit the clock value to alter the distance that regions/playlists
+			will be nudged. (see <xref linkend="sn-clocks"/> for instructions).
+		</para>
+	</section>
+
+	<section id="editor-window-tool-selector">
+		<title>Tool Selector</title>
+		<para>
+			The editor tool selector is in a tearoff window, and contains a series of
+			buttons used to select what the mouse (and often the keyboard) will do when
+			editing tracks. The tools include:
+		</para>
+		<table id="tbl-editor-window-mouse-modes"><title>Snap Control</title>
+			<tgroup cols = "2">
+				<colspec colnum="1" colname="Snap Option" colwidth="1"/>
+				<colspec colnum="2" colname="Action" colwidth= "2"/>
+				<thead>
+					<row>
+						<entry>
+							Mouse Mode
+						</entry>
+						<entry>
+							Description
+						</entry>
+					</row>
+				</thead>
+				<tbody>
+					<row>
+						<entry>
+							object
+						</entry>
+						<entry>
+							<para>
+								Left-clicking Object will place the mouse in object mode. When in
+								object mode, the mouse pointer appears as a hand whenever it is over
+								the track canvas or the rulers. The mouse can now be used to select
+								and perform operations on objects such as regions, markers etc.
+							</para>
+						</entry>
+					</row>
+					<row>
+						<entry>
+							range
+						</entry>
+						<entry>
+							<para>
+								Left-clicking Range will place the mouse in range mode. When in range
+								mode, the mouse pointer appears as a vertical line whenever it is over
+								the track canvas or the rulers. The mouse will now be able to select a
+								point or range of time. Time ranges can be selected over one or
+								several tracks.
+							</para>
+						</entry>
+					</row>
+					<row>
+						<entry>
+							gain
+						</entry>
+					</row>
+					<row>
+						<entry>
+							zoom
+						</entry>
+						<entry>
+							<para>
+								Left-clicking Zoom will place the mouse in zoom mode. When in zoom
+								mode, the mouse pointer appears as a magnifying glass whenever it is
+								over the track canvas or the rulers. This mode is used to zoom the
+								display to any range that is subsequently set using the mouse.
+							</para>
+						</entry>
+					</row>
+					<row>
+						<entry>
+							timefx
+						</entry>
+						<entry>
+							<para>
+								Left-clicking Timefx will place the mouse in timefx mode. When in
+								timefx mode, the mouse pointer appears as a distinctive 'expanding'
+								illustration whenever it is over the track canvas or the rulers. This
+								mode is used to resize regions using a timestretch algorithm.
+							</para>
+						</entry>
+					</row>
+				</tbody>
+			</tgroup>
+		</table>
+	</section>
+</section>