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

diff --git a/manual/xml/user_interface_conventions.xml b/manual/xml/user_interface_conventions.xml
new file mode 100644
index 0000000000..b79fea1e87
--- /dev/null
+++ b/manual/xml/user_interface_conventions.xml
@@ -0,0 +1,179 @@
+<?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-user-interface-conventions">
+	<title>Interface Basics</title>
+
+	<para>
+		Although Ardour has a fairly conventional graphical user interface, there
+		are a few elements that are unique to it and are probably new to you. This
+		chapter provides a guide to using these aspects of the interface.
+	</para>
+
+	<section id="interface-mouse-clicks">
+		<title>Mouse Clicks</title>
+
+		<section id="interface-click">
+			<title>Click</title>
+
+			<para>
+				When we say "click on" without specifying a mouse button, we mean use
+				<mousebutton>Button1</mousebutton> to click on a user interface element (button, fader, menu, etc).
+			</para>
+		</section>
+
+		<section id="interface-context-click">
+			<title>Context Click</title>
+
+			<para>
+				As in most graphical user interfaces today, a "context click" (<mousebutton>Button3</mousebutton>) in
+				many parts of the user interface will popup a context-specific menu,
+				allowing you to set parameters or carry out operations. There are a lot of
+				examples of this, but trying it on an audio region, a mixer mute button
+				and a mixer strip name will show the general idea.
+			</para>
+		</section>
+
+		<section id="interface-delete-edit-click">
+			<title>Delete &amp; Edit Click</title>
+
+			<para>
+				There are two additional mouse/key combinations that you should be
+				familiar and comfortable with. They are called "delete click" and "edit
+				click", and by default they consist
+				<keycombo><keycap>Shift</keycap><mousebutton>Button3</mousebutton></keycombo> click and
+				<keycombo><keycap>Ctrl</keycap><mousebutton>Button3</mousebutton></keycombo> click respectively. A delete click on most objects within
+				Ardour's editor will delete that object. This includes regions, markers,
+				curve control points and so on. An edit click on the any of the same kind
+				of objects will pop up an editor dialog for that object.
+			</para>
+		</section>
+	</section>
+
+	<section id="interface-clocks">
+		<title>Clocks</title>
+
+		<para>
+			There are several clocks in Ardour's user interface, some of them visible
+			all the time, others in windows that are only shown by request. All these
+			clocks are identical to each other in their functionality, although some
+			can be edited by the user and some are for display only.
+		</para>
+
+		<para>
+			Context clicking on a clock brings up a menu that allows you to modify the
+			display mode of that clock. The choices are:
+		</para>
+
+		<itemizedlist>
+			<listitem>
+				<para>
+					Audio Frames
+				</para>
+			</listitem>
+			<listitem>
+				<para>
+					BBT (Bars,Beats,Ticks - musical tempo &amp; meter based time)
+				</para>
+			</listitem>
+			<listitem>
+				<para>
+					SMPTE
+				</para>
+			</listitem>
+			<listitem>
+				<para>
+					Min:Sec
+				</para>
+			</listitem>
+		</itemizedlist>
+
+		<para>
+			Each clock mode has a number of different fields. For example, SMPTE has
+			hours, minutes, seconds, and video frames.
+		</para>
+
+		<para>
+			To edit the value of a particular clock, click in the leftmost field you
+			want to modify. You can then enter a new value for that field using numeric
+			keys, along with '.' where appropriate. Editing will move the next field of
+			the clock after you have entered the maximum number of digits for a field.
+			To move to the next field before this press Tab. To finish editing, either
+			press <keycap>Return</keycap> or use the <keycap>Tab</keycap> key to advance through all remaining fields.
+		</para>
+	</section>
+
+	<section id="interface-bar-controllers">
+		<title>Bar Controllers</title>
+
+		<para>
+			Bar controllers were inspired by a comment made by "Larry the O" in
+			Electronic Musician in 2001.
+		</para>
+
+		<para>
+			A bar controller is a user interface element that works rather differently
+			than any standard element found in most programs. They are used to provide
+			a combined method of displaying and modifying a parameter.
+		</para>
+
+		<para>
+			To graphically edit the value of the parameter represented by a bar
+			controller, press <mousebutton>Button1</mousebutton> and drag the controller left/right or up/down as
+			appropriate. To edit the value with greater precision, double click the
+			controller and it will transform into a data entry box. You can enter an
+			exact value for the parameter, or use arrow buttons to increment/decrement
+			the displayed value. When you are finished editing, the Enter or Tab keys
+			will transform the data entry box back into the normal version of the bar
+			controller.
+		</para>
+	</section>
+
+	<section id="interface-click-boxes">
+		<title>Click Boxes</title>
+
+		<para>
+			Click boxes were also inspired by Larry's comment.
+		</para>
+
+		<para>
+			A click box is, as its name suggests, just a part of a window you can click
+			on to change some parameter or control value.
+		</para>
+
+		<para>
+			Clicking with 3 moves the parameter to the next value, clicking with 1
+			moves to the previous value. Clicking and holding either button will
+			automatically advance through the possible values in the appropriate
+			direction.
+		</para>
+
+		<note>
+			<para>
+				we are slowly eliminating click boxes in favor of bar controllers
+			</para>
+		</note>
+	</section>
+
+	<section id="interface-panes">
+		<title>Panes</title>
+
+		<para>
+			Panes are user interface elements that allow you to adjust the relative
+			sizes of two sections of a window. The panes in Ardour work perfectly
+			normally but have one additional feature: a Delete-click on the pane
+			divider will completely hide one side of its two sections. Which section
+			depends on the pane, and is not user configurable, but is neary always
+			precisely what you'd want anyway. If the pane is already hidden, then
+			Delete-click (on the still-visible pane) will restore it to the size it had
+			before it was hidden.
+		</para>
+	</section>
+<!--
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+		href="Some_Subsection.xml" />
+	-->
+</section>