more copy-editing of chapters 1+2, update style guide to reflect lessons learned.

diff --git a/STYLE_GUIDE b/STYLE_GUIDE
index 866e86f0a167ff2860ffa3f15f0aefb27c84e0cb..f6101bbe4961e8a719b3efbb38abe8cc402ef0f6 100644 (file)
--- a/STYLE_GUIDE
+++ b/STYLE_GUIDE
@@ -105,13 +105,16 @@ default choice is <p>, the plain paragraph.
 encloses a newly introduced term that is being explained. Use for the first
 occurrence of the main concept of every manual page, or the first occurrence
 of a new concept after a sub-heading if necessary.
+Keep in mind that <dfn> tags might be used to generate an index of keywords
+- don't pollute it too much.
 
 <abbr>
 is used to explain an abbreviation such as <abbr title="Linux Audio
 Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the
-definition when the user hovers over the word, and it can easily be
-extracted via CSS for printing.
-Use only for the first occurrence of every new abbreviation.
+definition when the user hovers over the word.
+On each page, use only for the first occurrence of every abbreviation. Avoid
+a redundant explanation in the text - the expansion can easily be extracted 
+via CSS for printing.
 
 <em>
 is used to emphasize a word. Commonly rendered as italics.
@@ -176,6 +179,8 @@ class="mod1">N</kbd>. It will render as "Ctrl+N" for you, and as "Cmd+N" for
 your Mac-using friend. Nice, uh?
 
 For anything you want the user to type, use <kbd> as a block-level element.
+See above for other <kbd> classes to denote menu items, selections, mouse
+events and controller actions.
 
 <code>
 is only used for program code, or the content of configuration files etc. Do

diff --git a/_manual/01_welcome-to-ardour/02_about-ardour-documentation.html b/_manual/01_welcome-to-ardour/02_about-ardour-documentation.html
index c539e0804e84aadc0e69a97527fe54976a688377..4b0440030f0bef9e0ba48465976addbc01215be3 100644 (file)
--- a/_manual/01_welcome-to-ardour/02_about-ardour-documentation.html
+++ b/_manual/01_welcome-to-ardour/02_about-ardour-documentation.html
@@ -5,97 +5,104 @@ title: About Ardour documentation
 
 <h2>Conventions Used In This Manual</h2>
 <p>
-This section covers some of the typographical and language conventions 
-used in this manual.
+  This section covers some of the typographical and language conventions 
+  used in this manual.
 </p>
 
 <h3>Keyboards and Modifiers</h3>
 <p>
-Keyboard bindings are shown like this: <kbd>s</kbd> or <kbd class="mod1">x</kbd>. 
-<kbd>Ctrl x</kbd> means "press the <kbd>Ctrl</kbd> key, keep it pressed and then also 
-press the <kbd>x</kbd> key. You may also see key combinations such as 
-<kbd class="mod12">e</kbd>, which mean that you should press the <kbd
-class="mod1">&nbsp;</kbd> key, then while keeping it pressed also press the 
-<kbd class="mod2">&nbsp;</kbd> key and then while
-keeping them both pressed, finally press the <kbd>e</kbd> key.</p>
+  <dfn>Keyboard bindings</dfn> are shown like this: <kbd>s</kbd> or
+  <kbd class="mod1">x</kbd>.
+</p>
+<p>
+  <kbd>Ctrl x</kbd> means "press the <kbd>Ctrl</kbd> key, keep it pressed
+  and then also press the <kbd>x</kbd> key. You may also see key combinations 
+  such as <kbd class="mod12">e</kbd>, which mean that you should hold down
+  the <kbd class="mod1">&nbsp;</kbd> key <em>and</em> the
+  <kbd class="mod2">&nbsp;</kbd> key, and then while keeping them both
+  down, press the <kbd>e</kbd> key.
+</p>
 <p>
-Note that different platforms have different conventions for which modifier key
-(Control or Command) to use as the primary or most common modifier. When viewing
-this manual from a machine identifying itself as running OS X, you will see 
-<kbd>Cmd</kbd> where appropriate (for instance in the first example above).
-On other machines you will see <kbd>Ctrl</kbd> instead.
+  Note that different platforms have different conventions for which
+  modifier key (Control or Command) to use as the primary or most common
+  modifier. When viewing this manual from a machine identifying itself as
+  running OS X, you will see  <kbd>Cmd</kbd> where appropriate (for instance
+  in the first example above). On other machines you will see <kbd>Ctrl</kbd>
+  instead.
 </p>
 
 <h3>Menu Items</h3>
 <p>
-Menu items are indicated like this:<br />
-<kbd class="menu">Top &gt; Next &gt; Deeper</kbd>. Each "&gt;"-separated item
-indicates one level of a nested (sub-)menu.
+  Menu items are indicated like this:<br />
+  <kbd class="menu">Top &gt; Next &gt; Deeper</kbd>.<br />
+  Each "&gt;"-separated item indicates one level of a nested (sub-)menu.
 </p>
 
 <h3>Preference/Dialog Options</h3>
 <p>
-Choices in various dialogs, notably the Preferences and Properties dialog, are 
-indicated like this:<br />
-<kbd class="option">Edit &gt; Preferences &gt; Audio &gt; Some Option</kbd>. 
-Each successive item indicates either a (sub-) menu or a tabbed dialog
-navigation. The final item is the one to choose or select.
+  Choices in various dialogs, notably the Preferences and Properties dialog, are 
+  indicated like this:<br />
+  <kbd class="option">Edit &gt; Preferences &gt; Audio &gt; Some
+  Option</kbd>.<br />
+  Each successive item indicates either a (sub-) menu or a tabbed dialog
+  navigation. The final item is the one to choose or select.
 </p>
 <p>
-If you are requested to deselect an option, you will see something like
-this:<br />
-<kbd class="optoff">Edit &gt; Preferences &gt; Audio &gt; Some other
-Option</kbd>.
+  If you are requested to deselect an option, you will see something like
+  this:<br />
+  <kbd class="optoff">Edit &gt; Preferences &gt; Audio &gt; Some other
+  Option</kbd>.<br />
 </p>
 
 
 <h3>Notes</h3>
 <p class="note">
-Important notes about things that might not otherwise be obvious are shown in this
-format.
+  Important notes about things that might not otherwise be obvious are shown in
+  this format.
 </p>
 
 <h3>Warnings</h3>
 <p class="warning">
-Hairy issues that might cause things to go wrong, lose data, or impair sound
-quality is displayed in this way.
+  Hairy issues that might cause things to go wrong, lose data, or impair sound
+  quality is displayed in this way.
 </p>
 
 
 <h3>Mouse Buttons</h3>
 <p>
-We refer to <a href="/setting-up-your-system/the-mouse">mouse buttons</a> as 
-<kbd class="mouse">Left</kbd>, <kbd class="mouse">Middle</kbd> and
-<kbd class="mouse">Right</kbd>. Ardour can use additional buttons, but they have
-no default behaviour in the program.
+  We refer to <a href="/setting-up-your-system/the-mouse">mouse buttons</a> as 
+  <kbd class="mouse">Left</kbd>, <kbd class="mouse">Middle</kbd> and
+  <kbd class="mouse">Right</kbd>. Ardour can use additional buttons, but they have
+  no default behaviour in the program.
 </p>
 
 <h4>Mouse click modifiers</h4>
 <p>
-Many editing functions are performed by clicking the mouse while holding a
-modifier key, for example <kbd class="mouse mod1">Left</kbd>.
-
+  Many editing functions are performed by clicking the mouse while holding a
+  modifier key, for example <kbd class="mouse mod1">Left</kbd>.
 </p>
+
 <h4>"Context-click"</h4>
-<p>Many times the term <kbd class="mouse">context-click</kbd> is used to indicate 
-that you should (typically) right-click on a particular element of the graphical 
-user interface. Although right-click is the common, default way to do this, there 
-are other ways to accomplish the same thing - this term refers to any of them, 
-and the result is always that a menu specific to the item you clicked on will be
-displayed.
+<p>
+  Many times the term <kbd class="mouse">context-click</kbd> is used to indicate
+  that you should (typically) right-click on a particular element of the graphical 
+  user interface. Although right-click is the common, default way to do this, there 
+  are other ways to accomplish the same thing - this term refers to any of them, 
+  and the result is always that a menu specific to the item you clicked on will be
+  displayed.
 </p>
 
 <h3>"The Pointer"</h3>
 <p>
-When the manual refers to the "pointer", it means the on-screen representation 
-of the mouse position or the location of a touch action if you are using a touch
-interface.
+  When the manual refers to the "pointer", it means the on-screen representation 
+  of the mouse position or the location of a touch action if you are using a touch
+  interface.
 </p>
 
 <h3>Other user input</h3>
 <p>
-Ardour supports hardware controllers, such as banks of <kbd
-class="fader">faders</kbd>, <kbd class="knob">knobs</kbd>, or <kbd
-class="button">buttons</kbd>.
+  Ardour supports hardware controllers, such as banks of
+  <kbd class="fader">faders</kbd>, <kbd class="knob">knobs</kbd>, or
+  <kbd class="button">buttons</kbd>.
 </p>
 

diff --git a/_manual/01_welcome-to-ardour/03_additional-resources.html b/_manual/01_welcome-to-ardour/03_additional-resources.html
index db665df9af8119b6bd4d8884b3e6eb52bc220dc1..aaa8c6b4c5283f0abf851c951500998d3ebfaec2 100644 (file)
--- a/_manual/01_welcome-to-ardour/03_additional-resources.html
+++ b/_manual/01_welcome-to-ardour/03_additional-resources.html
@@ -4,7 +4,7 @@ title: Additional Resources
 ---                        
 
 <p>In addition to this documentation, you may check a variety of other
-resources:</p>
+<dfn>resources</dfn>:</p>
 <ul>
   <li>the <a href="https://ardour.org/whatsnew.html">Ardour release
   notes</a></li>
@@ -14,10 +14,10 @@ resources:</p>
   Support</a> via mailing lists and IRC (chat)</li>
 </ul>
 <p>
-  The IRC channels in particular are where most of the day-to-day
+  The <dfn>IRC channels</dfn> in particular are where most of the day-to-day
   development and debugging is done, and there are plenty of experienced
   users to help you if you run into problems.<br />
   Please be prepared to hang around for a few hours, the chat is usually
-  busiest from 19:00UTC to 04:00UTC. If you can, keep your chat window open,
-  so that you don't miss a belated answer.
+  busiest from 19:00&nbsp;UTC to 04:00&nbsp;UTC. If you can, keep your chat
+  window open, so that you don't miss a belated answer.
 </p>  

diff --git a/_manual/02_introducing-ardour/01_creating-music-with-ardour.html b/_manual/02_introducing-ardour/01_creating-music-with-ardour.html
index 63b9aa6efd84193b8d8f05bca2eb8e28db7e221a..54e20547bd82339428aa812166f11297899f4392 100644 (file)
--- a/_manual/02_introducing-ardour/01_creating-music-with-ardour.html
+++ b/_manual/02_introducing-ardour/01_creating-music-with-ardour.html
@@ -26,10 +26,10 @@ title: Creating Music with Ardour
   material to it, which can be done in one of 3 ways:
 </p>
 <ul>
-  <li>Record incoming audio or MIDI data, either via audio or MIDI hardware
+  <li><dfn>Record</dfn> incoming audio or MIDI data, either via audio or MIDI hardware
   connected to your computer, or from other applications.</li>
-  <li>Create new MIDI data using the mouse and/or various dialogs</li>
-  <li>Import existing media files into the session</li>
+  <li><dfn>Create</dfn> new MIDI data using the mouse and/or various dialogs</li>
+  <li><dfn>Import</dfn> existing media files into the session</li>
 </ul>
 <p>
   <dfn>MIDI recordings</dfn> consist of performance data ("play note X at 
@@ -59,7 +59,7 @@ title: Creating Music with Ardour
 </p>
 <p>
   Your audio/MIDI data appears in chunks called <dfn>regions</dfn>, which
-  are arranged into horizontal lanes called <dfn>tracks<dfn>. Tracks are 
+  are arranged into horizontal lanes called <dfn>tracks</dfn>. Tracks are 
   stacked vertically in the Editor window. You can copy, shorten, move, 
   and delete regions without changing the actual data stored in the session 
   at all &mdash; Ardour is a <dfn>non-destructive</dfn> editor. (Almost) 

diff --git a/_manual/02_introducing-ardour/02_understanding-basic-concepts-and-terminology.html b/_manual/02_introducing-ardour/02_understanding-basic-concepts-and-terminology.html
index 82189eb965381ea01c8974b1ecd2c73d427f29b3..234214714160d6437026a72d48e2ac3383f53862 100644 (file)
--- a/_manual/02_introducing-ardour/02_understanding-basic-concepts-and-terminology.html
+++ b/_manual/02_introducing-ardour/02_understanding-basic-concepts-and-terminology.html
@@ -13,7 +13,8 @@ title: Understanding Basic Concepts and Terminology
 <p>
   An <dfn>Ardour session</dfn> is a container for an entire project. A
   session may contain an arbitrary number of <dfn>tracks</dfn> and
-  <dfn>busses</dfn> consisting of audio and MIDI data, along with
+  <dfn>busses</dfn> consisting of audio and <abbr title="Musical Instrument
+  Digital Interface">MIDI</abbr> data, along with
   information on processing those tracks, a mix of levels, and everything
   else related to the project. A session might typically contain a song, or
   perhaps an entire album or a complete live recording.
@@ -26,10 +27,11 @@ title: Understanding Basic Concepts and Terminology
   other details.
 </p>
 <p>
-  Ardour's session file is kept in XML format, which is advantageous as it
-  is somewhat human-readable, and human-editable in a crisis. Sound files
-  are stored in one of a number of optional formats, and MIDI files as SMF
-  (standard MIDI format).
+  Ardour's session file is kept in 
+  <abbr title="eXtensible Markup Language">XML</abbr> format, which is
+  advantageous as it is somewhat human-readable, and human-editable in a
+  crisis. Sound files are stored in one of a number of optional formats, and
+  MIDI files as <abbr title="Standard MIDI File">SMF</abbr>.
 </p>
 <p>
   It is also possible for Ardour sessions to reference sound and MIDI files
@@ -127,15 +129,15 @@ title: Understanding Basic Concepts and Terminology
   the following plugin standards:
 </p>
 <dl class="wide-table">
-  <dt>LADSPA</dt>
+  <dt><abbr title="Linux Audio Developers' Simple Plugin API">LADSPA</abbr></dt>
   <dd>the first major plugin standard for Linux. Many LADSPA plugins are
   available, mostly free and open-source.</dd>
-  <dt>LV2</dt>
+  <dt><abbr title="LADSPA Version 2">LV2</abbr></dt>
   <dd>the successor to LADSPA. Lots of plugins have been ported from
   LADSPA to LV2, and also many new plugins written.</dd>
-  <dt>VST</dt>
+  <dt><abbr title="Virtual Studio Technology">VST</abbr></dt>
   <dd>Ardour supports VST plugins that have been compiled for Linux.</dd>
-  <dt>AudioUnit (AU)</dt>
+  <dt><abbr title="Audio Units">AU</abbr></dt>
   <dd>Mac OS X versions of Ardour support AudioUnit plugins.</dd>
 </dl>
 <p>