Added chapter on track automation.

Author: Shamus397

build.py

@@ -259,7 +259,8 @@ def BuildList(lst, fs, pagePos, cList):
 		nextPos = lst[i + 1] if i + 1 < len(lst)  else len(fs)
 
 		active = ' class=active' if curPos == pagePos else ''
-		content = content + '<dt' + active + '><a href="/' + fs[curPos]['filename'] + '/">' + fs[curPos]['title'] + '</a></dt><dd' + active + '>'
+		menuTitle = fs[curPos]['menu_title'] if 'menu_title' in fs[curPos] else fs[curPos]['title']
+		content = content + '<dt' + active + '><a href="/' + fs[curPos]['filename'] + '/">' + menuTitle + '</a></dt><dd' + active + '>'
 
 		# If the current page is our page, and it has children, enumerate them
 		if curPos == pagePos:

explode.py

@@ -111,9 +111,6 @@ def ParseHeader(fileObj):
 			if 'menu_title' in header:
 				explode.write('menu_title: ' + header['menu_title'] + '\n')
 
-			if 'link' in header:
-				explode.write('link: ' + header['link'] + '\n')
-
 			if 'style' in header:
 				explode.write('style: ' + header['style'] + '\n')
 
@@ -126,6 +123,9 @@ def ParseHeader(fileObj):
 				explode.write('include: ' + inclFile + '\n')
 				filenames.append(inclFile)
 
+		if 'link' in header:
+			explode.write('link: ' + header['link'] + '\n')
+
 		if 'uri' in header:
 			explode.write('uri: ' + header['uri'] + '\n')
 

implode.py

@@ -91,9 +91,6 @@ def CheckForHeader(fn):
 			if 'menu_title' in header:
 				implode.write('menu_title: ' + header['menu_title'] + '\n')
 
-			if 'link' in header:
-				implode.write('link: ' + header['link'] + '\n')
-
 			if 'style' in header:
 				implode.write('style: ' + header['style'] + '\n')
 
@@ -104,6 +101,9 @@ def CheckForHeader(fn):
 				implode.write('include: ' + header['include'] + '\n')
 				implode.write('exclude: yes\n')
 
+		if 'link' in header:
+			implode.write('link: ' + header['link'] + '\n')
+
 		if 'uri' in header:
 			implode.write('uri: ' + header['uri'] + '\n')
 

include/about-ardours-documentation.html

@@ -132,3 +132,4 @@ <h3>Warnings</h3>
   Hairy issues that might cause things to go wrong, lose data, impair sound
   quality, or eat your proverbial goldfish, are displayed in this way.
 </p>
+

include/automation-curves.html

@@ -0,0 +1,18 @@
+
+<figure class=right>
+<img src="/images/automation-curve1.png">
+<figcaption class=center>A typical automation curve.</figcaption>
+</figure>
+
+<p>
+  An <dfn>automation curve</dfn> is a series of lines connected by <dfn>control
+  points</dfn> that defines a continuous line. As the curve is traversed from
+  left to right, the line defines the level of the parameter controlled by the
+  automation lane.
+</p>
+
+<p>
+  The curve by itself does nothing; it will <em>only</em> control playback if
+  the lane it is in is in <kbd class=menu>Play</kbd> mode.
+</p>
+

include/automation-lanes.html

@@ -0,0 +1,53 @@
+
+<figure class=right>
+<img src="/images/automation-lane1.png">
+<figcaption class=center>A typical automation lane.</figcaption>
+</figure>
+
+<p>
+  An <dfn>automation lane</dfn> is similar to a track in that it holds data
+  that can be played back; however, unlike a track, it is not an independent
+  entity&mdash;it is always attached to the track that it controls. Automation
+  lanes also contain zero to one <dfn>automation curves</dfn>. Each lane
+  controls one and only one parameter of the track it is attached to.
+</p>
+
+<p>
+  Every track will have at least five automation lanes associated with it:
+  trim, fader, mute, and pan (which consists of two lanes: L/R and Width); it
+  can possibly have many more if there are any processors associated with it.
+  All these lanes are automatically attached to the track but hidden, and
+  initially they are all empty (have no automation curves in them).
+</p>
+
+<figure class=center>
+<img src="/images/automation-multi-lane1.png">
+<figcaption class=center>An example of a track with three lanes of automation (fader &amp; pan).</figcaption>
+</figure>
+
+<p>
+  Automation lanes typically have the following controls:
+</p>
+
+<ul>
+  <li>A hide button (square button with an "X" inside)</li>
+  <li>A horizontal fader</li>
+  <li>An <dfn>automation mode</dfn> selector</li>
+</ul>
+
+<p>
+  The hide button, as the name implies, hides the automation lane. The
+  horizontal fader controls the level of the parameter that the lane controls;
+  manipulating this while in <kbd class=menu>Write</kbd> or <kbd
+  class=menu>Touch</kbd> mode during playback will make changes to the lane's
+  automation curve. The automation mode selector selects which mode the lane is
+  in (<kbd class=menu>Manual</kbd>, <kbd class=menu>Play</kbd>, <kbd
+  class=menu>Write</kbd>, or <kbd class=menu>Touch</kbd>).
+</p>
+
+<p class=note>
+  The hide button will only hide the lane; it does not remove it from the
+  track. The automation lane never really goes away&mdash;the closest one can
+  get to that is to clear the automation curve and hide the lane.
+</p>
+

include/automation-modes.html

@@ -0,0 +1,49 @@
+
+<p>
+  In order to understand how automation in Ardour works, it is necessary to
+  understand the four modes of automation. They are: <kbd
+  class=menu>Manual</kbd>, <kbd class=menu>Play</kbd>, <kbd
+  class=menu>Write</kbd>, and <kbd class=menu>Touch</kbd>.
+</p>
+
+<figure class=right>
+<img src="/images/automation-modes1.png">
+<figcaption class=center>The automation mode menu.</figcaption>
+</figure>
+
+<p>
+  <kbd class=menu>Manual</kbd> mode is basically analogous to a processor's
+  bypass switch. Whenever an automation lane is in this mode, it is inactive
+  and any level that is manually set for controlling the lane's parameter will
+  persist during playback like normal.
+</p>
+
+<p class=note>
+  In Ardour, every track and processor parameter is initially set to <kbd
+  class=menu>Manual</kbd> mode.
+</p>
+
+<p>
+  <kbd class=menu>Play</kbd> mode tells Ardour to use the automation curve in
+  the automation lane to control the level of the parameter controlled by the
+  lane <em>during playback</em>. The control that normally sets the parameter
+  will be <em>unresponsive to manual input</em> and will move automatically in
+  accord with the lane's automation curve during playback.
+</p>
+
+<p>
+  <kbd class=menu>Write</kbd> mode allows continuous, dynamic setting of a
+  control during playback; all such settings are written to the lane the
+  control is in. This defines the lane's automation curve in the interval being
+  played, and overwrites any existing automation curve in the lane being
+  manipulated.
+</p>
+
+<p>
+  <kbd class=menu>Touch</kbd> mode is similar to <kbd class=menu>Write</kbd>
+  mode, except it only overwrites sections of a lane's automation curve when
+  the control is changed in some way. This allows for changing only the parts
+  of an automation curve that are desired to be changed, while leaving the rest
+  unchanged.
+</p>
+

include/automation-nomenclature.html

@@ -0,0 +1,17 @@
+
+<figure class=right>
+<img src="/images/automation-fader1.png">
+<figcaption class=center>An example of a fader automation lane (below) with its associated track (above).</figcaption>
+</figure>
+
+<p>
+  Track automation occurs in one or more <dfn>lanes</dfn>. Each lane has a
+  control that allows setting the amount or position of a certain
+  <dfn>parameter</dfn> associated with the lane. Parameters are things that can
+  be controlled on a track's automation lane, such as volume, panning, muting,
+  trim, etc. <dfn>Automation curves</dfn> consist of lines connected by
+  <dfn>control points</dfn>, that live within the confines of a lane; these
+  tell Ardour how to change a given parameter over time. <dfn>Automation
+  modes</dfn> govern how a given automation lane will behave during playback.
+</p>
+