View Issue Details

Jump to NotesJump to History
IDProjectCategoryView StatusDate SubmittedLast Update
0001492ardourdocumentationpublic2007-02-13 22:352007-02-18 05:42
Reporterscrewtop Assigned To 
PrioritynormalSeveritytextReproducibilityN/A
Status acknowledgedResolutionopen 
Summary0001492: Glossary is incomplete
DescriptionThe glossary of Ardour terminology exists in skeletal form, but needs definitions to be written for most of the terms. It could also be expanded to include more terms.

Should the glossary only cover Ardour-specific terminology (regions, playlists, sends, etc.) or all digital audio recording terminology? We could have two glossaries: one for Ardour terminology, and one for general digital audio recording and computing terminology, so that new Ardour users with a recording background can easily skip the familiar terms.

Also, acronyms in the glossary currently don't show up in the HTML output.
Additional InformationI've made a start on adding more definitions to the existing glossary.
TagsNo tags attached.

Activities

timbyr

2007-02-14 06:30

developer   ~0003240

Gah, how do I reply in this bug tracking system.

> The glossary of Ardour terminology exists in skeletal form

Yeah it didn't exist before I converted the manual to docbook, I just added a few terms as they came up.

> Should the glossary only cover Ardour-specific terminology (regions,
> playlists, sends, etc.) or all digital audio recording terminology?

I think it should cover domain specific terms aswell as ardour specific terminology, although defining the ardour specific terminology is more
important initially(and probably the harder of the two).

> We could have two glossaries: one for Ardour terminology, and one for
> general digital audio recording and computing terminology, so that new
> Ardour users with a recording background can easily skip the familiar
> terms.

I'd rather not do that. The ardour specific terminology should be defined within the manual itself with the glossary acting only as a reference.

I think the Getting Started chapter started out with the intent of explaining the main concepts and elements of the interface to introduce the readers to ardour concepts but it got too big and goes a little beyond what I would call "Basics".

One option would be to create a new chapter that contains a few short sections(no more than 1 or 2 pages) for each of the major concepts and introduces the important terminology. I don't think such a chapter should actually describe how to use ardour(although it may reference other sections).

let me know what you think...

screwtop

2007-02-14 07:23

reporter   ~0003241

One glossary with everything in it sounds good to me (and I reckon a good glossary is also good for the profile of the project if it gets referenced from elsewhere). I thought the glossary might be a good place for me to start contributing because it would mean I'd be forced to get a precise understanding of the Ardour terminology to begin with. :^)

I agree that getting the concepts and architecture clear up-front is important. I'm imagining charts and diagrams! I think once users get the "what" and "why", the "how" is usually pretty obvious.

If I have updates to the docs, should I just upload patch files via the tracker for now?

timbyr

2007-02-14 14:35

developer   ~0003245

The glossary is a fairly good place to start and any help with the manual is appreciated. I'm sure there are lots of ardour specific terms in the manual that aren't yet in the glossary, is that what you intended to start with?

I also started to add comments about ardour specific terms that I knew had different meanings or names in other DAW software but then removed them because I decided that there was probably a better place for that sort of information(I'm just not sure where yet).

If you have patches then the tracker is a good place for them. I had some updates pending for the glossary section that I just committed, I'm sorry if it means you have to regenerate you patches.

Possibly one thing to keep in mind with the glossary is that even though some of us have been using DAW software and or ardour for a long time there may be differing opinions on what certain terminology actually means or refers to.

2007-02-15 11:28

 

glossary.xml.diff (14,647 bytes)    
Index: glossary.xml
===================================================================
--- glossary.xml	(revision 1460)
+++ glossary.xml	(working copy)
@@ -4,23 +4,46 @@
 
 ]>
 
+<!--
+Note:
+ - The glossary can contain general terminology from the (digital) recording domain, but should focus on Ardour-specific terms or senses.
+ 
+Questions (maybe to become notes as they are answered):
+ - Should this glossary contain only terms that are specific to Ardour, i.e. no MIDI, ALSA, etc.?
+ - Are "link" elements OK for linking to other glossary terms, or should we be using "glossterm" as an inline for these (or is this only for the first occurrence)?
+ - Why do the acronyms not appear on the HTML output? Ah, they have to be within some other element (e.g. glossterm).
+ - Capitalisation: lowercase for entries that are not acronyms or proper nouns?
+ - How will cross references be handled in the printed manual?  I guess we need to use "See Also"s and can't rely on links.  Then again, maybe a See Also is only required when the term is not actually used in the current definition (the reader could just look up an unfamiliar term when encountered).
+-->
+
 <glossary>
  <title>Ardour Glossary</title>
  <glossdiv>
   <title>A</title>
   <glossentry id="gt-alsa">
-   <glossterm><acronym>ALSA</acronym></glossterm>
+   <glossterm><acronym>ALSA</acronym> (Advanced Linux Sound Architecture)</glossterm>
    <glossdef>
     <para>
-     Abbreviation for Advanced Linux Sound Architecture. ALSA provides audio
-     and MIDI functionality to the Linux operating system.
+     ALSA provides audio and MIDI functionality to the Linux operating system.<!-- mention in-kernel parts, library, and utilities? -->
     </para>
     <para>
-     <ulink url="http://www.alsa-project.org"/>
+     Home page: <ulink url="http://www.alsa-project.org"/>
     </para>
    </glossdef>
   </glossentry>
 
+  <glossentry id="gt-api">
+   <glossterm><acronym>API</acronym> (Application Programming Interface)</glossterm>
+   <glossdef>
+    <para>
+     A set of functions exposed by a computer system (usually a library, service, or operating system) enabling it to be used by other systems.
+    </para>
+    <para>
+     An API is exposed at the level of source code, and is primarily used by programmers.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="gt-audio-track">
    <glossterm>Audio Track</glossterm>
    <glossdef>
@@ -34,7 +57,7 @@
    <glossterm>Auditioner</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A special <link linkend="gt-bus">bus</link> in Ardour that is independent of the rest of the mix, useful for auditioning specific regions by themselves.<!-- ??? -->
     </para>
    </glossdef>
   </glossentry>
@@ -46,8 +69,11 @@
    <glossterm>Bus</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A virtual track that provides mixing and effects control over an entire group of tracks.  In analog mixing terminology, buses are sometimes known as groups or subs<!-- TODO: verify this -->.
     </para>
+    <para>
+     The output from each of the tracks assigned to the bus is sent to the bus and mixed, and the output of the bus can be sent to the master output bus or (less commonly) another bus.  The master bus is an always-present bus that usually provides a mix of all buses and tracks in the session, and is used to set the overall volume of the mix.
+    </para>
    </glossdef>
   </glossentry>
 
@@ -76,12 +102,14 @@
  <glossdiv>
   <title>D</title>
   <glossentry id="gt-daw">
-   <glossterm><acronym>DAW</acronym></glossterm>
+   <glossterm><acronym>DAW</acronym> (Digital Audio Workstation)</glossterm>
    <glossdef>
     <para>
-     Abbreviation of Digital Audio Workstation. Some reasonable definition
-     here.
+     A system for sound production, focusing on the functions of multi-track recording, playback, mixing, editing, and possibly also mastering.  DAWs often consist of specialised hardware (audio <!-- TODO: link? -->I/O devices, <!-- TODO: link? -->DSPs) and software.
     </para>
+    <para>
+     Since much of the functionality of a DAW can now be run in software on general-purpose personal computers, the term DAW can be used to refer specifically to an integrated software system for sound production.
+    </para>
    </glossdef>
   </glossentry>
 
@@ -89,7 +117,7 @@
    <glossterm>Destructive Recording</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A recording mode in which any existing audio regions<!-- in a particular layer? --> in <!-- TODO: link -->armed tracks may be overwritten.  In Ardour, <link linkend="gt-tape-track">tape tracks</link> implement destructive recording.
     </para>
    </glossdef>
   </glossentry>
@@ -110,10 +138,10 @@
  <glossdiv>
   <title>H</title>
   <glossentry id="gt-hdr">
-   <glossterm><acronym>HDR</acronym></glossterm>
+   <glossterm><acronym>HDR</acronym> (Hard Disk Recorder)</glossterm>
    <glossdef>
     <para>
-     Short for Hard Disk Recorder. Some reasonable definition here.
+     Software and/or hardware for recording and playing back audio, using a hard disk drive as the storage medium.
     </para>
    </glossdef>
   </glossentry>
@@ -134,14 +162,20 @@
  <glossdiv>
   <title>J</title>
   <glossentry id="gt-jack">
-   <glossterm><acronym>JACK</acronym></glossterm>
+   <glossterm><acronym>JACK</acronym> (Jack<!-- or JACK? --> Audio Connection Kit)</glossterm>
    <glossdef>
     <para>
-     Initialism of Jack Audio Connection Kit. Some reasonable definition here.
+     A low-latency audio server for POSIX systems (including Linux and Mac OS X).
     </para>
     <para>
-     <ulink url="http://jackaudio.org"/>
+     JACK enables audio streams to be freely routed between applications and sound hardware or other applications, in real-time, and with sample-accurate synchronization.  As of version 0.102.20, JACK also supports <link linkend="gt-midi">MIDI</link> routing.
     </para>
+    <para>
+     Ardour requires that the JACK server, <command>jackd</command>, be running in order to record and play sounds.
+    </para>
+    <para>
+     Home page: <ulink url="http://jackaudio.org"/>
+    </para>
    </glossdef>
   </glossentry>
  </glossdiv>
@@ -149,30 +183,56 @@
  <glossdiv>
   <title>L</title>
   <glossentry id="gt-ladpsa">
-   <glossterm><acronym>LADSPA</acronym> </glossterm>
+   <glossterm><acronym>LADSPA</acronym> (Linux Audio Developer&apos;s Simple Plugin API)</glossterm>
    <glossdef>
     <para>
-     Abbreviation of Linux Audio Developers Simple Plugin API. Some reasonable
-     definition here.
+     A standard <link linkend="gt-api">API</link> for audio <link linkend="gt-plugin">plugins</link> on Linux.
     </para>
     <para>
-     <ulink url="http://ladspa.org"/>
+     Home page: <ulink url="http://ladspa.org"/>
     </para>
    </glossdef>
   </glossentry>
+
+  <glossentry id="gt-layer">
+   <glossterm>layer</glossterm>
+   <glossdef>
+    <para>
+     TODO
+    </para>
+   </glossdef>
+  </glossentry>
+
  </glossdiv>
 
  <glossdiv>
   <title>M</title>
   <glossentry id="gt-midi">
-   <glossterm><acronym>MIDI</acronym> </glossterm>
+   <glossterm><acronym>MIDI</acronym> (Musical Instrument Digital Interface)</glossterm>
    <glossdef>
     <para>
-     Abbreviation for Musical Instrument Digital Interface. Some reasonable
-     definition here.
+     A standard for the coding and transmission of musical performance data in digital form.
     </para>
+    <para>
+     MIDI data is akin to a musical score, in that it consists of instructions specifying what notes are to be played, by which instrument, at what time, and with what nuances (e.g. how loud the note should be).  A MIDI stream is typically much smaller than a digital reproduction of the waveform of the same performance.  MIDI also provides for the transmission of control and system data, and clock signals for synchronisation.
+    </para>
    </glossdef>
   </glossentry>
+
+  <glossentry>
+   <glossterm>mixer strip</glossterm>
+   <glossdef>
+    <para>
+     A user interface element in Ardour for controlling the flow and processing of the sound from<!-- or "for"?--> a single track.
+    </para>
+    <para>
+     A mixer strip provides controls such as a fader (for controlling the level), pan or balance<!-- does Ardour actually distinguish between these? -->, and pre- and post-fader inserts.  Mixer strips reside on the Mixer window, and a new strip is created for each new track.
+     <!-- Does Ardour distinguish between recorded and live sound as far as mixer strips are concerned? Does a mixer strip actually apply to a "channel" (or equivalent term), which may or may not have a track mapped to it (e.g. in the case of a live mix)?-->
+    </para>
+   </glossdef>
+  </glossentry>
+
+  <!-- TODO: add Mixer Window? -->
  </glossdiv>
 
  <glossdiv>
@@ -181,8 +241,11 @@
    <glossterm>Playlist</glossterm>
    <glossdef>
     <para>
-     some reasonable definition here.
+     A collection of audio <link linkend="gt-region">regions</link> in an Ardour <link linkend="gt-track">track</link>.  A track may have only one playlist at a time, and an active playlist may belong to only one track<!-- ??? is this correct? -->.  <!-- TODO: mention something about layers? -->
     </para>
+    <para>
+     Playlists are commonly used in recording multiple takes of a performance.
+    </para>
    </glossdef>
   </glossentry>
 
@@ -190,17 +253,16 @@
    <glossterm>plugin</glossterm>
    <glossdef>
     <para>
-     some reasonable definition here.
+     A reusable code library that can be used within another program (for example, to perform audio data processing).  Plugins are not standalone programs, and must be loaded and run within a host application.
     </para>
    </glossdef>
   </glossentry>
 
   <glossentry id="gt-posix">
-   <glossterm><acronym>POSIX</acronym></glossterm>
+   <glossterm><acronym>POSIX</acronym> (Portable Operating System Interface for uniX)</glossterm>
    <glossdef>
     <para>
-     POSIX stands for Portable Operating System Interface for uniX. Some
-     reasonable definition here.
+     A set of standards defining system and user interfaces for compatibility with the Unix operating system.
     </para>
    </glossdef>
   </glossentry>
@@ -208,8 +270,8 @@
 
  <glossdiv>
   <title>R</title>
-  <glossentry id="gt-region">
-   <glossterm>Region</glossterm>
+  <glossentry id="gt-redirect">
+   <glossterm>Redirect</glossterm>
    <glossdef>
     <para>
      Some reasonable definition here.
@@ -217,14 +279,15 @@
    </glossdef>
   </glossentry>
 
-  <glossentry id="gt-redirect">
-   <glossterm>Redirect</glossterm>
+  <glossentry id="gt-region">
+   <glossterm>Region</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     The basic element of editing in Ardour, representing a contiguous section of one or more audio files<!-- What does contiguous mean when applied to multiple files? -->.  A region normally resides within a <link linkend="gt-playlist">playlist</link>, which in turn normally resides within a <link linkend="gt-track">track</link>.
     </para>
    </glossdef>
   </glossentry>
+
  </glossdiv>
 
  <glossdiv>
@@ -242,8 +305,11 @@
    <glossterm>Session</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     An Ardour project; a collection of control data and audio files that form a performance.  Commonly, a session would be used for recording a single piece of music, although one session could be used to record an entire album or suite (especially in the case of a live performance).
     </para>
+    <para>
+     The Ardour user interface<!--(the Editor Window, in particular)--> is basically a tool for managing and manipulating sessions.  Each session is saved within a folder on the filesystem, with subfolders for audio files and automation data, and files for the session metadata and state, along with snapshots and backups of the session.
+    </para>
    </glossdef>
   </glossentry>
 
@@ -251,7 +317,7 @@
    <glossterm>Session Template</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A saved Ardour <link linkend="gt-session">session</link> that can be used as a convenient starting point for a new session.
     </para>
     <glossseealso otherterm="gt-session"/>
    </glossdef>
@@ -283,8 +349,14 @@
    <glossterm>Track</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     The basic unit of recording in an Ardour <link linkend="gt-session">session</link><!-- TODO: I'm not happy with this definition -->.  A track typically represents the recording of a single instrument, and has controls such as gain and pan/balance applied to it on playback.  A session typically comprises multiple tracks, which can be played back simultaneously.
     </para>
+    <para>
+     Each track has one <link linkend="gt-playlist">playlist</link> associated with it at any time, which contains the audio <link linkend="gt-region">regions</link> to be played.  A track&apos;s playlist may have multiple regions, enabling a performance to be constructed from several smaller sections, or to control the levels and effects of multiple regions with one set of track controls.
+    </para>
+    <para>
+     An Ardour track can have many channels multiplexed within it, but most commonly only one (mono) or two (stereo) are used.  Ardour&apos;s multichannel mixing is currently somewhat limited, so tracks with many channels might be better split into multiple tracks<!-- is this still true? -->.
+    </para>
    </glossdef>
   </glossentry>
  </glossdiv>
@@ -292,11 +364,14 @@
  <glossdiv>
   <title>V</title>
   <glossentry id="gt-vst">
-   <glossterm><acronym>VST</acronym></glossterm>
+   <glossterm><acronym>VST</acronym> (Virtual Studio Technology)</glossterm>
    <glossdef>
     <para>
-     Short for Virtual Studio Technology
+     An audio <link linkend="gt-plugin">plugin</link> architecture defined by <ulink url="http://www.steinberg.net">Steinberg</ulink>.  The main types of VST plugin are instruments (digital synthesizers) and effects.
     </para>
+    <para>
+     Steinberg&apos;s VST <!--TODO: link-->SDK may be freely downloaded, but the license agreement does not permit it to be redistributed.  While Ardour can be compiled to support VST plugins, the VST SDK license prevents you from redistributing the binary.  This in turn means that you cannot comply with the GPL license that applies to Ardour.
+    </para>
    </glossdef>
   </glossentry>
  </glossdiv>
glossary.xml.diff (14,647 bytes)   

screwtop

2007-02-15 11:31

reporter   ~0003297

I've just uploaded a patch for the glossary with a number of definitions fleshed out (but not everything).

Now that I think about it, "API" (which I added) is probably getting a bit on the generic side...

timbyr

2007-02-17 01:01

developer   ~0003313

Thanks, I'll have a look at your patch soon.

2007-02-18 05:39

 

glossary.xml_2.diff (21,003 bytes)    
Index: xml/glossary.xml
===================================================================
--- xml/glossary.xml	(revision 1460)
+++ xml/glossary.xml	(working copy)
@@ -4,28 +4,51 @@
 
 ]>
 
-<glossary>
+<!--
+Note:
+ - The glossary can contain general terminology from the (digital) recording domain, but should focus on Ardour-specific terms or senses.
+ - Terms that are acronyms should be marked up using the "acronym" element, and have the expanded form given in parentheses within the same "glossterm" element.
+ 
+Questions (maybe to become notes as they are answered):
+ - Should this glossary contain only terms that are specific to Ardour, i.e. no MIDI, ALSA, etc.?
+ - Are "link" elements OK for linking to other glossary terms, or should we be using "glossterm" as an inline for these (or is this only for the first occurrence)?
+ - Capitalisation: lowercase for entries that are not acronyms or proper nouns?
+ - How will cross references be handled in the printed manual?  I guess we need to use "See Also"s and can't rely on links.  Then again, maybe a See Also is only required when the term is not actually used in the current definition (the reader could just look up an unfamiliar term when encountered).
+-->
+
+<glossary status="ardour-draft">
  <title>Ardour Glossary</title>
  <glossdiv>
   <title>A</title>
   <glossentry id="gt-alsa">
-   <glossterm><acronym>ALSA</acronym></glossterm>
+   <glossterm><acronym>ALSA</acronym> (Advanced Linux Sound Architecture)</glossterm>
    <glossdef>
     <para>
-     Abbreviation for Advanced Linux Sound Architecture. ALSA provides audio
-     and MIDI functionality to the Linux operating system.
+     A collection of drivers, libraries, standards, and utilities that provide audio and MIDI functionality to the Linux operating system.
     </para>
     <para>
-     <ulink url="http://www.alsa-project.org"/>
+     Home page: <ulink url="http://www.alsa-project.org"/>
     </para>
    </glossdef>
   </glossentry>
 
+  <glossentry id="gt-api">
+   <glossterm><acronym>API</acronym> (Application Programming Interface)</glossterm>
+   <glossdef>
+    <para>
+     A set of functions exposed by a computer system (usually a library, service, or operating system) enabling it to be used by other systems.
+    </para>
+    <para>
+     An API is exposed at the level of source code, and is primarily used by programmers.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="gt-audio-track">
-   <glossterm>Audio Track</glossterm>
+   <glossterm>audio track</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A <link linkend="gt-track">track</link> that can directly contain and control recorded material in a <link linkend="gt-playlist">playlist</link>.  This is in contrast to a <link linkend="gt-bus">bus [track]</link>, which receives its input from other tracks.  <remark>[Is this an accurate definition?]</remark>
     </para>
    </glossdef>
   </glossentry>
@@ -34,7 +57,7 @@
    <glossterm>Auditioner</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A special <link linkend="gt-bus">bus</link> in Ardour that is independent of the rest of the mix, useful for auditioning specific regions by themselves.<remark>[is this accurate?]</remark>
     </para>
    </glossdef>
   </glossentry>
@@ -43,19 +66,22 @@
  <glossdiv>
   <title>B</title>
   <glossentry id="gt-bus">
-   <glossterm>Bus</glossterm>
+   <glossterm>bus</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A virtual track that provides mixing and effects control over an entire group of tracks.  In analog mixing terminology, buses are sometimes known as groups, subgroups, or subs<remark>[need to confirm this terminology]</remark>.
     </para>
+    <para>
+     <remark>[Make some reference to "submix" here?]</remark>  The output from each of the tracks assigned to the bus is sent to the bus and mixed, and the output of the bus can be sent to the master output bus or (less commonly) another bus.  The master bus is an always-present bus that usually provides a mix of all buses and tracks in the session, and is used to set the overall volume of the mix.
+    </para>
    </glossdef>
   </glossentry>
 
   <glossentry id="gt-bus-track">
-   <glossterm>Bus Track</glossterm>
+   <glossterm>bus track</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     <remark>[Some reasonable definition here. How is a bus track different from a bus, in particular.]</remark><!-- A track that appears in the Editor Window when a/the corresponding <link linkend="gt-bus">bus</link> is created. A bus track enables <TODO: link>automation</link> to be applied to a <TODO: link>submix</link>. -->
     </para>
    </glossdef>
   </glossentry>
@@ -64,10 +90,10 @@
  <glossdiv>
   <title>C</title>
   <glossentry id="gt-crossfade">
-   <glossterm>Crossfade</glossterm>
+   <glossterm>crossfade</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     An operation or effect equivalent to fading one sound out at the same time as another is faded in, leaving the overall level unchanged throughout<remark>[is this true? Are there different fade curves that could change the overall level, a la pan/balance?]</remark>.  Crossfades in Ardour can be created where there are overlapping <link linkend="gt-region">regions</link> in a <link linkend="gt-track">track</link>.  <remark>[Are layers relevant here?]</remark>
     </para>
    </glossdef>
   </glossentry>
@@ -76,20 +102,22 @@
  <glossdiv>
   <title>D</title>
   <glossentry id="gt-daw">
-   <glossterm><acronym>DAW</acronym></glossterm>
+   <glossterm><acronym>DAW</acronym> (Digital Audio Workstation)</glossterm>
    <glossdef>
     <para>
-     Abbreviation of Digital Audio Workstation. Some reasonable definition
-     here.
+     A system for sound production, focusing on the functions of multi-track recording, playback, mixing, editing, and possibly also mastering.  DAWs often consist of specialised hardware (audio <!-- TODO: link? -->I/O devices, <!-- TODO: link? -->DSPs) and software.
     </para>
+    <para>
+     Since much of the functionality of a DAW can now be run in software on general-purpose personal computers, the term DAW can be used to refer specifically to an integrated software system for sound production.
+    </para>
    </glossdef>
   </glossentry>
 
   <glossentry id="gt-destructive-recording">
-   <glossterm>Destructive Recording</glossterm>
+   <glossterm>destructive recording</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A recording mode in which existing audio <link linkend="gt-region">regions</link><remark>[in a particular layer?]</remark> in <!-- TODO: link? -->armed tracks may be overwritten.  In Ardour, <link linkend="gt-tape-track">tape tracks</link> implement destructive recording.
     </para>
    </glossdef>
   </glossentry>
@@ -98,10 +126,10 @@
  <glossdiv>
   <title>E</title>
   <glossentry id="gt-embed">
-   <glossterm>Embed</glossterm>
+   <glossterm>embed</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     To include audio data from an external file while leaving the file in its original location, rather than moving it into the directory tree for the <link linkend="gt-session">session</link>.
     </para>
    </glossdef>
   </glossentry>
@@ -110,10 +138,10 @@
  <glossdiv>
   <title>H</title>
   <glossentry id="gt-hdr">
-   <glossterm><acronym>HDR</acronym></glossterm>
+   <glossterm><acronym>HDR</acronym> (Hard Disk Recorder)</glossterm>
    <glossdef>
     <para>
-     Short for Hard Disk Recorder. Some reasonable definition here.
+     Software and/or hardware for recording and playing back audio, using a hard disk drive as the storage medium.
     </para>
    </glossdef>
   </glossentry>
@@ -122,11 +150,14 @@
  <glossdiv>
   <title>I</title>
   <glossentry id="gt-insert">
-   <glossterm>Insert</glossterm>
+   <glossterm>insert</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A <link linkend="gt-redirect">redirect</link> in which the auxiliary signal chain runs in series with the main one.
     </para>
+    <para>
+     Inserts are commonly used to apply effects that affect the overall amplitude of the signal, such as a dynamic range compressor.
+    </para>
    </glossdef>
   </glossentry>
  </glossdiv>
@@ -134,55 +165,90 @@
  <glossdiv>
   <title>J</title>
   <glossentry id="gt-jack">
-   <glossterm><acronym>JACK</acronym></glossterm>
+   <glossterm><acronym>JACK</acronym> (Jack<remark>[or JACK?]</remark> Audio Connection Kit)</glossterm>
    <glossdef>
     <para>
-     Initialism of Jack Audio Connection Kit. Some reasonable definition here.
+     A low-latency audio server for POSIX systems (including Linux and Mac OS X).
     </para>
     <para>
-     <ulink url="http://jackaudio.org"/>
+     JACK enables audio streams to be freely routed between applications and sound hardware or other applications, in real-time, and with sample-accurate synchronization.  As of version 0.102.20, JACK also supports <link linkend="gt-midi">MIDI</link> routing.
     </para>
+    <para>
+     Ardour requires that the JACK server, <command>jackd</command>, be running in order to record and play sounds.
+    </para>
+    <para>
+     Home page: <ulink url="http://jackaudio.org"/>
+    </para>
    </glossdef>
   </glossentry>
  </glossdiv>
 
  <glossdiv>
   <title>L</title>
-  <glossentry id="gt-ladpsa">
-   <glossterm><acronym>LADSPA</acronym> </glossterm>
+  <glossentry id="gt-ladspa">
+   <glossterm><acronym>LADSPA</acronym> (Linux Audio Developer&apos;s Simple Plugin API)</glossterm>
    <glossdef>
     <para>
-     Abbreviation of Linux Audio Developers Simple Plugin API. Some reasonable
-     definition here.
+     A standard <link linkend="gt-api">API</link> for audio <link linkend="gt-plugin">plugins</link> on Linux.
     </para>
     <para>
-     <ulink url="http://ladspa.org"/>
+     Home page: <ulink url="http://ladspa.org"/>
     </para>
    </glossdef>
   </glossentry>
+
+  <glossentry id="gt-layer">
+   <glossterm>layer</glossterm>
+   <glossdef>
+    <para>
+     TODO
+    </para>
+   </glossdef>
+  </glossentry>
+
  </glossdiv>
 
  <glossdiv>
   <title>M</title>
   <glossentry id="gt-midi">
-   <glossterm><acronym>MIDI</acronym> </glossterm>
+   <glossterm><acronym>MIDI</acronym> (Musical Instrument Digital Interface)</glossterm>
    <glossdef>
     <para>
-     Abbreviation for Musical Instrument Digital Interface. Some reasonable
-     definition here.
+     A standard for the coding and transmission of musical performance data in digital form.
     </para>
+    <para>
+     MIDI data is akin to a musical score, in that it consists of instructions specifying what notes are to be played, by which instrument, at what time, and with what nuances (e.g. how loud the note should be).  A MIDI stream is typically much smaller than a digital reproduction of the waveform of the same performance.  MIDI also provides for the transmission of control and system data, and clock signals for synchronisation.
+    </para>
    </glossdef>
   </glossentry>
+
+  <glossentry>
+   <glossterm>mixer strip</glossterm>
+   <glossdef>
+    <para>
+     A user interface element in Ardour for controlling the flow and processing of the sound from<!-- or "for"?--> a single track<!-- or channel? -->.
+    </para>
+    <para>
+     A mixer strip provides controls such as a fader (for controlling the level), pan or balance<remark>[does Ardour actually distinguish between these?]</remark>, and pre- and post-fader inserts.  Mixer strips reside on the Mixer window, and a new strip is created for each new track.
+     <remark>[Does Ardour distinguish between recorded and live sound as far as mixer strips are concerned? Does a mixer strip actually apply to a "channel" (or equivalent term), which may or may not have a track mapped to it (e.g. in the case of a live mix)?]</remark>
+    </para>
+   </glossdef>
+  </glossentry>
+
+  <remark>TODO: add Mixer Window?</remark>
  </glossdiv>
 
  <glossdiv>
   <title>P</title>
   <glossentry id="gt-playlist">
-   <glossterm>Playlist</glossterm>
+   <glossterm>playlist</glossterm>
    <glossdef>
     <para>
-     some reasonable definition here.
+     A collection of audio <link linkend="gt-region">regions</link> in an Ardour <link linkend="gt-track">track</link>.  A track may have only one playlist at a time, and an active playlist may belong to only one track<remark>[is this correct?]</remark>.  <remark>[TODO: mention something about layers?]</remark>
     </para>
+    <para>
+     Playlists are commonly used in recording multiple takes of a performance.
+    </para>
    </glossdef>
   </glossentry>
 
@@ -190,17 +256,19 @@
    <glossterm>plugin</glossterm>
    <glossdef>
     <para>
-     some reasonable definition here.
+     A reusable code library that can be used within another program (for example, to perform audio data processing).  Plugins are not standalone programs, and must be loaded and run within a host application.
     </para>
+    <para>
+     In Ardour, a plugin is a type of <link linkend="gt-redirect">redirect</link> that uses a <link linkend="gt-ladspa">LADSPA</link> plugin to provide effects processing for a <link linkend="gt-track">track</link>.
+    </para>
    </glossdef>
   </glossentry>
 
   <glossentry id="gt-posix">
-   <glossterm><acronym>POSIX</acronym></glossterm>
+   <glossterm><acronym>POSIX</acronym> (Portable Operating System Interface for uniX)</glossterm>
    <glossdef>
     <para>
-     POSIX stands for Portable Operating System Interface for uniX. Some
-     reasonable definition here.
+     A set of standards defining system and user interfaces for compatibility with the Unix operating system.
     </para>
    </glossdef>
   </glossentry>
@@ -208,60 +276,65 @@
 
  <glossdiv>
   <title>R</title>
-  <glossentry id="gt-region">
-   <glossterm>Region</glossterm>
+  <glossentry id="gt-redirect">
+   <glossterm>redirect <remark>["redirection"?]</remark></glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A generic type of connection available in Ardour for a track<remark>[track only?]</remark>, in which an audio signal can be routed to other processing elements besides the normal mixer strip controls.  Effects <link linkend="gt-plugin">plugins</link>, <link linkend="gt-send">sends</link>, and <link linkend="gt-insert">inserts</link> are types of redirect available in Ardour.
     </para>
    </glossdef>
   </glossentry>
 
-  <glossentry id="gt-redirect">
-   <glossterm>Redirect</glossterm>
+  <glossentry id="gt-region">
+   <glossterm>region</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     The basic element of editing in Ardour, representing a contiguous section of one or more audio files<remark>[What does contiguous mean when applied to multiple files?]</remark>.  A region normally resides within a <link linkend="gt-playlist">playlist</link>, which in turn normally resides within a <link linkend="gt-track">track</link>.
     </para>
    </glossdef>
   </glossentry>
+
  </glossdiv>
 
  <glossdiv>
   <title>S</title>
   <glossentry id="gt-send">
-   <glossterm>Send</glossterm>
+   <glossterm>send</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A <link linkend="gt-redirect">redirect</link> in which the auxiliary signal chain runs in parallel with the main one.
     </para>
+    <glossseealso otherterm="insert" />
    </glossdef>
   </glossentry>
 
   <glossentry id="gt-session">
-   <glossterm>Session</glossterm>
+   <glossterm>session</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     An Ardour project; a collection of control data and audio files that form a performance.  Commonly, a session would be used for recording a single piece of music, although one session could be used to record an entire album or suite (especially in the case of a live performance).
     </para>
+    <para>
+     The Ardour user interface<!--(the Editor Window, in particular)--> is basically a tool for managing and manipulating sessions.  Each session is saved within a folder on the filesystem, with subfolders for audio files and automation data, and files for the session metadata and state, along with snapshots and backups of the session.
+    </para>
    </glossdef>
   </glossentry>
 
   <glossentry id="gt-session-template">
-   <glossterm>Session Template</glossterm>
+   <glossterm>session template</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A saved Ardour <link linkend="gt-session">session</link> that can be used as a convenient starting point for a new session.
     </para>
-    <glossseealso otherterm="gt-session"/>
+    <!--glossseealso otherterm="gt-session"/-->
    </glossdef>
   </glossentry>
 
-  <glossentry id="gt-submixing">
-   <glossterm>Submixing</glossterm>
+  <glossentry id="gt-submix"><!-- I changed this from gt-submixing after checking that there were no references to it elsewhere in the manual -->
+   <glossterm>submix<!-- was "submixing" --></glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     A <!-- TODO: link -->mix that involves only a subset of the <link linkend="gt-track">tracks</link> <remark>["or <!-- TODO: link? -->channels"?]</remark> in a <link linkend="gt-session">session</link>.  A submix usually occurs at<remark>["in"?]</remark> a <link linkend="gt-bus">bus</link>.
     </para>
    </glossdef>
   </glossentry>
@@ -270,21 +343,27 @@
  <glossdiv>
   <title>T</title>
   <glossentry id="gt-tape-track">
-   <glossterm>Tape Track</glossterm>
+   <glossterm>tape track</glossterm>
    <glossdef>
     <para>
-     Some Reasonable definition here.
+     A type of <link linkend="gt-track"><remark>["audio"?]</remark> track</link> in Ardour that simulates<remark>[or "behaves like"?]</remark> a tape recording machine in that it uses a <link linkend="gt-destructive-recording">destructive</link> mode of recording.
     </para>
-    <glossseealso otherterm="gt-track"/>
+    <!--glossseealso otherterm="gt-track"/-->
    </glossdef>
   </glossentry>
 
   <glossentry id="gt-track">
-   <glossterm>Track</glossterm>
+   <glossterm>track</glossterm>
    <glossdef>
     <para>
-     Some reasonable definition here.
+     <remark>[I'm not entirely happy with this definition.  A track is basically a channel, correct?]</remark>The basic unit of recording <remark>[and mixing?]</remark> in an Ardour <link linkend="gt-session">session</link>.  A track typically represents the recording of a single instrument, and has controls such as gain and pan/balance applied to it on playback.  However, <link linkend="gt-bus">bus tracks</link> do not contain recorded material, and act instead to provide <link linkend="gt-submix">submixing</link> for multiple other tracks.
     </para>
+    <para>
+      <remark>[I suspect this now belongs under "audio track":]</remark>A session typically comprises multiple tracks, which can be played back simultaneously.  Each track has one <link linkend="gt-playlist">playlist</link> associated with it at any time, which contains the audio <link linkend="gt-region">regions</link> to be played.  A track&apos;s playlist may have multiple regions, enabling a performance to be constructed from several smaller sections, or to control the levels and effects of multiple regions with one set of track controls.
+    </para>
+    <para>
+     <remark>[This is perhaps more detail than necessary for a glossary:]</remark>An Ardour track can have many channels multiplexed within it, but most commonly only one (mono) or two (stereo) are used.  Ardour&apos;s multichannel mixing is currently somewhat limited, so tracks with many channels might be better split into multiple tracks<remark>[is this still true?]</remark>.
+    </para>
    </glossdef>
   </glossentry>
  </glossdiv>
@@ -292,11 +371,14 @@
  <glossdiv>
   <title>V</title>
   <glossentry id="gt-vst">
-   <glossterm><acronym>VST</acronym></glossterm>
+   <glossterm><acronym>VST</acronym> (Virtual Studio Technology)</glossterm>
    <glossdef>
     <para>
-     Short for Virtual Studio Technology
+     An audio <link linkend="gt-plugin">plugin</link> architecture defined by <ulink url="http://www.steinberg.net">Steinberg</ulink>.  The main types of VST plugin are instruments (digital synthesizers) and effects.
     </para>
+    <para>
+     Steinberg&apos;s VST <!--TODO: link-->SDK may be freely downloaded, but the license agreement does not permit it to be redistributed.  While Ardour can be compiled to support VST plugins, the VST SDK license prevents you from redistributing the binary.  This in turn means that you cannot comply with the GPL license that applies to Ardour.
+    </para>
    </glossdef>
   </glossentry>
  </glossdiv>
glossary.xml_2.diff (21,003 bytes)   

screwtop

2007-02-18 05:42

reporter   ~0003315

Just uploaded a second patch (glossary.xml_2.diff) with further updates as follows:

 - Added further definitions: crossfade, insert, redirect, send, submix, tape track.
 - Expanded definition for plugin.
 - Added some more notes and queries.
 - Added draft formatting.
 - Changed SGML comments to DocBook remarks where appropriate.
 - Switched to lowercase for terms that are not acronyms or proper nouns.
 - Promoted one or two questions to notes in the comments at the start.
 - Fixed typo in id for LADSPA entry.
 - Expanded ALSA entry.

Issue History

Date Modified Username Field Change
2007-02-13 22:35 screwtop New Issue
2007-02-14 06:30 timbyr Note Added: 0003240
2007-02-14 06:31 timbyr Status new => acknowledged
2007-02-14 07:23 screwtop Note Added: 0003241
2007-02-14 14:35 timbyr Note Added: 0003245
2007-02-15 11:28 screwtop File Added: glossary.xml.diff
2007-02-15 11:31 screwtop Note Added: 0003297
2007-02-17 01:01 timbyr Note Added: 0003313
2007-02-18 05:39 screwtop File Added: glossary.xml_2.diff
2007-02-18 05:42 screwtop Note Added: 0003315