Add --nopdf option to build script, fixes for Automation section.

build.py

@@ -6,6 +6,8 @@
 # by James Hammons
 # (C) 2017 Underground Software
 #
+# Contributors: Ed Ward
+#
 
 # Remnants (could go into the master document as the first header)
 
@@ -83,7 +85,7 @@ def PartToLevel(s):
 
 
 #
-# Converts a integer to a roman number
+# Converts a integer to a Roman numeral
 #
 def num2roman(num):
 	num_map = [(1000, 'M'), (900, 'CM'), (500, 'D'), (400, 'CD'), (100, 'C'), (90, 'XC'), (50, 'L'), (40, 'XL'), (10, 'X'), (9, 'IX'), (5, 'V'), (4, 'IV'), (1, 'I')]
@@ -200,6 +202,7 @@ def GetParent(fs, pos):
 
 	return pos
 
+
 #
 # Change the hierarchy of titles : h1->hn, h2->hn+1, etc... n being delta-1
 #
@@ -209,6 +212,7 @@ def reheader(txt, delta):
 		txt = txt.replace('</h' + str(i),'</h' + str(i+delta))
 	return txt
 
+
 #
 # Creates the BreadCrumbs
 #
@@ -265,7 +269,6 @@ def FindInternalLinks(fs):
 			linkDict['"@@' + hdr['link'] + '"'] = '"/' + hdr['filename'] + '/"'
 			linkDict['"@@' + hdr['link'] + '#'] = '"/' + hdr['filename'] + '/index.html#'
 
-
 	return linkDict
 
 #
@@ -279,7 +282,6 @@ def FindInternalAnchors(fs):
 			linkDict['"@@' + hdr['link'] + '"'] = '"#' + hdr['link'] + '"'
 			linkDict['"@@' + hdr['link'] + '#'] = '"#' + hdr['link'] + '"'
 
-
 	return linkDict
 
 
@@ -404,10 +406,12 @@ parser = argparse.ArgumentParser(description='A build script for the Ardour Manu
 parser.add_argument('-v', '--verbose', action='store_true', help='Display the high-level structure of the manual')
 parser.add_argument('-q', '--quiet', action='store_true', help='Suppress all output (overrides -v)')
 parser.add_argument('-d', '--devmode', action='store_true', help='Add content to pages to help developers debug them')
+parser.add_argument('-n', '--nopdf', action='store_true', help='Do not automatically generate PDF from content')
 args = parser.parse_args()
 verbose = args.verbose
 quiet = args.quiet
 devmode = args.devmode
+nopdf = args.nopdf
 
 if quiet:
 	verbose = False
@@ -567,6 +571,7 @@ for header in fileStruct:
 	# but the basic fundamental organizing unit WRT content is still the
 	# chapter.
 	githubedit = ''
+
 	if level > 0:
 		if 'include' in header:
 			srcFile = open('include/' + header['include'])
@@ -589,12 +594,16 @@ for header in fileStruct:
 	# Add header information to the page if in dev mode
 	if devmode:
 		devnote ='<aside style="background-color:indigo; color:white;">'
+
 		if 'filename' in header:
 			devnote = devnote + 'filename: ' + header['filename'] + '<br>'
+
 		if 'include' in header:
 			devnote = devnote + 'include: ' + header['include'] + '<br>'
+
 		if 'link' in header:
 			devnote = devnote + 'link: ' + header['link'] + '<br>'
+
 		content = devnote + '</aside>' + content
 
 	# ----- One page and PDF version -----
@@ -664,18 +673,21 @@ onepage = onepage.replace('{{ content }}', '') # cleans up the last spaceholder
 onepageFile.write(onepage)
 onepageFile.close()
 
-if not quiet:
+if not nopdf:
+	if not quiet:
 		print('Generating the PDF...')
-# Create the PDF version of the documentation
-pdfpageFile = open(global_site_dir + 'pdf.html', 'w')
-pdfpage = pdfpage.replace('{% tree %}', opsidebar) # create the TOC
-pdfpage = pdfpage.replace('{{ content }}', '') # cleans up the last spaceholder
-pdfpageFile.write(pdfpage)
-pdfpageFile.close()
 
-from weasyprint import HTML
+	# Create the PDF version of the documentation
-doc = HTML(filename = global_site_dir + 'pdf.html') #, base_url = os.path.dirname(os.path.realpath(__file__)))
+	pdfpageFile = open(global_site_dir + 'pdf.html', 'w')
-doc.write_pdf(global_site_dir + 'manual.pdf')
+	pdfpage = pdfpage.replace('{% tree %}', opsidebar) # create the TOC
+	pdfpage = pdfpage.replace('{{ content }}', '') # cleans up the last spaceholder
+	pdfpageFile.write(pdfpage)
+	pdfpageFile.close()
+
+	from weasyprint import HTML
+	doc = HTML(filename = global_site_dir + 'pdf.html')
+	doc.write_pdf(global_site_dir + 'manual.pdf')
 
 if not quiet:
 	print('Processed ' + str(fileCount) + ' files.')
+

include/automation-curves.html

@@ -6,13 +6,27 @@
 
 <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
+  points</dfn> that typically defines a continuous line. As the curve is
-  left to right, the line defines the level of the parameter controlled by the
+  traversed from left to right, the line defines the level of the parameter
-  automation lane.
+  controlled by the automation lane.
 </p>
 
 <p>
-  The curve by itself does nothing; it will <em>only</em> control playback if
+  There are two types of automation curves: <kbd class=menu>Linear</kbd> and
-  the lane it is in is in <kbd class=menu>Play</kbd> mode.
+  <kbd class=menu>Discrete</kbd>. The most common type is <kbd
+  class=menu>Linear</kbd>, in which the space between any two contiguous
+  control points is continuously interpolated; in other words, the values
+  between any two contiguous control points at any given time is given by the
+  straight line connecting them. The second type of automation curve is <kbd
+  class=menu>Discrete</kbd>, in which no interpolation between control points
+  is done; whatever value the control point is set at is the value it will
+  yield until it reaches the next control point, at which point it will give
+  that value until the next control point, and so on until there are no more
+  control points.
+</p>
+
+<p class=note>
+  The curve by itself does nothing; it will <em>only</em> control playback if
+  the lane it resides in is in <kbd class=menu>Play</kbd> mode.
 </p>
 

include/automation-modes.html

@@ -1,27 +1,25 @@
 
-<p>
+<p class=fixme>
-  Ardour offers two modes for connecting automation control points: <kbd
+ADD IMAGES PLEASE
-  class=menu>Discrete</kbd> and <kbd class=menu>Linear</kbd>. The mode is
-  changed by a right click on the automation lane header and choosing the
-  mode from the mode menu.
 </p>
 
 <p>
-  <kbd class=menu>Discrete</kbd> mode has stair steps between each point on the
+  Ardour offers two modes for interpolating automation control points: <kbd
-  automation track. This is useful for on-off automation like mute or sustain
+  class=menu>Linear</kbd> and <kbd class=menu>Discrete</kbd>. The mode is
-  pedal (on a piano MIDI track).
+  changed by a <kbd class=mouse>Right</kbd> click on the automation lane header
+  and choosing the mode from the mode menu.
 </p>
 
 <p>
-  When recording automation via MIDI (for example a pitch bend from a keyboard),
+  <kbd class=menu>Linear</kbd> mode interpolates values between control points in a given automation curve by connecting them with straight lines; the values played back are derived from the points that lie on the lines thus defined. Typically, this is what is desired and is the default mode for all automation lanes.
-  Ardour always uses discreet mode.
 </p>
 
 <p>
-  <kbd class=menu>Linear</kbd> mode has straight lines betwen each point on the
+  <kbd class=menu>Discrete</kbd> mode does <em>no</em> interpolation between control points in a given automation curve. The values set by the control points do not change until the following control point is reached at which time the value is then set to its value; this continues on until there are no more control points. Typically this is used for parameters such as mute or sustain pedal (e.g., on a MIDI piano track).
-  automation track. This is useful for gradual shifts in automation lanes,
-  such as gradual increase in volume on the fader.
-
-  Linear is the default mode for most automation lanes created via mouse input
-  (versus recording via MIDI).
 </p>
+
+<p class=note>
+  When recording automation via MIDI (e.g., pitch bend from a MIDI keyboard),
+  Ardour always uses discrete mode.
+</p>
+

include/automation-nomenclature.html

@@ -10,10 +10,11 @@
   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
+  trim, etc. <dfn>Automation curves</dfn> typically 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> specify whether the control points are connected by lines or
+  modes</dfn> define how Ardour creates the values in between the control
-	stair steps. <dfn>Automation states</dfn> govern how a given automation lane
+  points of a given automation curve, either by connecting them with continuous
+  lines or not. <dfn>Automation states</dfn> govern how a given automation lane
   will behave during playback.
 </p>

master-doc.txt

@@ -1695,13 +1695,6 @@ link: automation-states
 part: subchapter
 ---
 
----
-title: Automation Modes
-include: automation-modes.html
-link: automation-modes
-part: subchapter
----
-
 ---
 title: Automation Lanes
 include: automation-lanes.html
@@ -1716,6 +1709,13 @@ link: automation-curves
 part: subchapter
 ---
 
+---
+title: Automation Modes
+include: automation-modes.html
+link: automation-modes
+part: subchapter
+---
+
 ---
 title: Controlling a Track with Automation
 menu_title: Track Automation