[musicians-guide] Finished review of code tags; replaced with emphasis tags; formatted bibliography in Solfege
crantila
crantila at fedoraproject.org
Mon Aug 9 06:59:45 UTC 2010
commit 57d00d9a5b481a4ace817efea9532c61dabe55b4
Author: Christopher Antila <crantila at fedoraproject.org>
Date: Mon Aug 9 02:59:19 2010 -0400
Finished review of code tags; replaced with emphasis tags; formatted bibliography in Solfege
en-US/Ardour.xml | 32 ++--
en-US/Audio_Vocabulary.xml | 26 +-
en-US/Digital_Audio_Workstations.xml | 48 ++--
en-US/FluidSynth.xml | 90 ++++----
en-US/LilyPond/LilyPond-counterpoint.xml | 2 +-
en-US/LilyPond/LilyPond-orchestra.xml | 6 +-
en-US/LilyPond/LilyPond-piano.xml | 58 +++---
en-US/LilyPond/LilyPond-syntax.xml | 8 +-
en-US/LilyPond/LilyPond.xml | 2 +-
en-US/Planet_CCRMA_at_Home.xml | 2 +-
en-US/Qtractor.xml | 42 ++--
en-US/Real_Time_and_Low_Latency.xml | 12 +-
en-US/Revision_History.xml | 24 ++-
en-US/Solfege.xml | 82 +++++--
en-US/Sound_Cards.xml | 8 +-
en-US/Sound_Servers.xml | 2 +-
.../SuperCollider-Basic_Programming.xml | 252 ++++++++++----------
en-US/SuperCollider/SuperCollider-Composing.xml | 14 +-
en-US/SuperCollider/SuperCollider-Exporting.xml | 29 +--
en-US/SuperCollider/SuperCollider.xml | 182 +++++++-------
20 files changed, 490 insertions(+), 431 deletions(-)
---
diff --git a/en-US/Ardour.xml b/en-US/Ardour.xml
index 8d192f6..389c3d2 100644
--- a/en-US/Ardour.xml
+++ b/en-US/Ardour.xml
@@ -588,10 +588,10 @@
<listitem><para>If the channels aren't synchronized, you'll need to adjust their placement in the timeline. Use the yellow clock that appears when you drag regions - it's set to the same units as the secondary clock, and shows you the time of the beginning of the file. It's important to get it synchronized before the next step!</para></listitem>
<listitem><para>Choose either the "L" or "R" region. If you're using edit groups, it doesn't matter which you choose, because <application>Ardour</application> will realize that the regions in both tracks are "group equivalent" (that is, they're basically the same, so they probably belong together).</para></listitem>
<listitem><para>Use the mouse to click in the coloured bar of the region, close to where the clarinet starts.</para></listitem>
- <listitem><para><application>Ardour</application> will automatically move the start of the region ''in both tracks''.</para></listitem>
+ <listitem><para><application>Ardour</application> will automatically move the start of the region in <emphasis>both tracks</emphasis>.</para></listitem>
<listitem><para>Move the playhead by clicking in the rulers at the point where you want the playhead to be, so that you can listen to the regions to ensure that you didn't cut out any of the useful audio.</para></listitem>
<listitem><para>If you want to adjust the beginning of the region, carefully move the mouse cursor to the start of the region, in the coloured bar. The cursor should turn into a double-ended left-and-right arrow. If you happened to accidentally remove some of the useful clarinet sound, you'll notice that it's still there. In fact, the beauty of trimming regions in this way is that it's "non-destructive," meaning that the entire original region is still there!</para></listitem>
- <listitem><para>Notice that when you made the first adjustment, <application>Ardour</application> put an arrow beside the region name in the region list of the session sidebar. If you click on the arrow, you will see that there is another copy of the same region underneath, but it's white. <application>Ardour</application> wants you to know that the white-coloured region is a modification of the blue-coloured region. If you drag the white-coloured region into the canvas area, you'll notice that it starts at the same time as the region you just modified. It can ''also'' be dragged out to the full size of the original region, which would create another modified version of the original. While it seems like <application>Ardour</application> stores multiple copies of the region, it actually just stores one copy, and the information required to make it seem like there are many.</para></listitem>
+ <listitem><para>Notice that when you made the first adjustment, <application>Ardour</application> put an arrow beside the region name in the region list of the session sidebar. If you click on the arrow, you will see that there is another copy of the same region underneath, but it's white. <application>Ardour</application> wants you to know that the white-coloured region is a modification of the blue-coloured region. If you drag the white-coloured region into the canvas area, you'll notice that it starts at the same time as the region you just modified. It can also be dragged out to the full size of the original region, which would create another modified version of the original. While it seems like <application>Ardour</application> stores multiple copies of the region, it actually just stores one copy, and the information required to make it seem like there are many.</para></listitem>
<listitem><para>Adjust the end of the region so that there isn't too much silence after the clarinet. Be extra careful with this, so that you don't cut out any of the clarinet, which gets very quiet at the end of the region. There isn't much to cut off! Note that you cannot click in the coloured bar when adjusting the end of a region, so you'll have to click-and-drag.</para></listitem>
</orderedlist>
</para>
@@ -845,16 +845,16 @@
<orderedlist>
<listitem><para>Enable "solo" mode on the "voice" bus, so that you can hear it as well as the marimba busses.</para></listitem>
<listitem><para>Slide the "Voice_1" regions so that the singer starts at about the same time as the higher marimba.</para></listitem>
- <listitem><para>Slide the "Voice_2" regions so that the singer starts at about 00:00:48.00</para></listitem>
- <listitem><para>Slide the "ens-Here_Is_How-1" regions so that they start singing at about 00:01:33.300</para></listitem>
- <listitem><para>Slide the "ens-Here_Is_How-2" (and the adjoined "ens-Here_Is_How-3") regions so that they start singing at about 00:02:11.500</para></listitem>
- <listitem><para>After playing closer attention to "Voice_3" and "Voice_4," you realize that the singer misses a word ("plan '''in''' you spider's ear") in "Voice_4." Because "Voice_3" doesn't contain the second part of "Voice_4," we'll need to trim the "Voice_4" region, and use both.
+ <listitem><para>Slide the "Voice_2" regions so that the singer starts at about <literal>00:00:48.00</literal></para></listitem>
+ <listitem><para>Slide the "ens-Here_Is_How-1" regions so that they start singing at about <literal>00:01:33.300</literal></para></listitem>
+ <listitem><para>Slide the "ens-Here_Is_How-2" (and the adjoined "ens-Here_Is_How-3") regions so that they start singing at about <literal>00:02:11.500</literal></para></listitem>
+ <listitem><para>After playing closer attention to "Voice_3" and "Voice_4," you realize that the singer misses a word ("plan <emphasis>in</emphasis> you spider's ear") in "Voice_4." Because "Voice_3" doesn't contain the second part of "Voice_4," we'll need to trim the "Voice_4" region, and use both.
<orderedlist>
- <listitem><para>The singer should start singing in "Voice_3" at about 00:02:24.500</para></listitem>
- <listitem><para>The signer should start singing "and here is how" in "Voice_4" at about 00:02:43.000</para></listitem>
+ <listitem><para>The singer should start singing in "Voice_3" at about <literal>00:02:24.500</literal></para></listitem>
+ <listitem><para>The signer should start singing "and here is how" in "Voice_4" at about <literal>00:02:43.000</literal></para></listitem>
</orderedlist>
</para></listitem>
- <listitem><para>Slide the "ens-Create_the_Inconceivable" regions so that they start singing at about 00:02:59.000</para></listitem>
+ <listitem><para>Slide the "ens-Create_the_Inconceivable" regions so that they start singing at about <literal>00:02:59.000</literal></para></listitem>
</orderedlist>
</para>
</section>
@@ -910,7 +910,7 @@
In terms of producing a recording of a live musical performance, it is the mixing stage where the audio engineer (in this case, you) has the most creative influence. Careful adjustment and tuning of the tracks will greatly affect the listeners' experience.
</para>
<para>
- Finally, it should be noted that, moreso than in the editing stage, the mixing stage should ''not'' be understood as progressing in a linear manner. This means you should not be following the tutorial from start to finish, but jumping between sections are desired. You should set up the tracks for stereo output first, and then read through all the sections and follow their advice as you wish, but sometimes returning to previous activities to re-tune those settings. When one setting is changed, it tends to have an effect on other settings, so if you set the level of a track once, then change its panning, you should check that the levels you set are still desirable - they'll probably need some tweaking, however minor it may be.
+ Finally, it should be noted that, moreso than in the editing stage, the mixing stage should <emphasis>not</emphasis> be understood as progressing in a linear manner. This means you should not be following the tutorial from start to finish, but jumping between sections are desired. You should set up the tracks for stereo output first, and then read through all the sections and follow their advice as you wish, but sometimes returning to previous activities to re-tune those settings. When one setting is changed, it tends to have an effect on other settings, so if you set the level of a track once, then change its panning, you should check that the levels you set are still desirable - they'll probably need some tweaking, however minor it may be.
</para>
<section id="sect-Musicians_Guide-Ardour-Mixing-Enabling_Stereo_Output">
<title>Setting the Session for Stereo Output and Disabling Edit Groups</title>
@@ -918,7 +918,7 @@
Part of the reason that the session sounds so bad is that all of the audio has been routed through both the left and right channels equally, making it a "mono" recording, even though we have the material of a "stereo" recording. This could easily have been done sooner, but it wouldn't have made much of a difference until now. Whereas mixing was focussed on getting the regions assembled so that they are like the song, mixing is about fine-tuning the regions and tracks so that they make the song sound great.
</para>
<para>
- Disabling the edit groups is also a good idea, because leaving them enabled actually ''reduces'' functionality in this stage of production. With edit groups enabled, any change that we make to one of the tracks will automatically be made to the other track, too. We want to be able to adjust the tracks independently; for cases where both tracks need the same adjustment, we will use the sub-master bus to which they're attached.
+ Disabling the edit groups is also a good idea, because leaving them enabled actually <emphasis>reduces</emphasis> functionality in this stage of production. With edit groups enabled, any change that we make to one of the tracks will automatically be made to the other track, too. We want to be able to adjust the tracks independently; for cases where both tracks need the same adjustment, we will use the sub-master bus to which they're attached.
</para>
<para>
These steps will disable the edit groups, and re-configure this session's tracks for stereo output.
@@ -945,9 +945,9 @@
<orderedlist>
<listitem><para>Open the mixer window with the menu, by choosing 'Window > Mixer'. As mentioned earlier, it can be convenient to put the mixer window on another monitor or virtual desktop.</para></listitem>
<listitem><para>Set all of the faders to 0 dB. They are probably already set to this level, unless you changed them earlier.</para></listitem>
- <listitem><para>Take the quietest track, when set to 0 dB, as the limiting factor on how loud the other tracks should be. Since it's generally safer to avoid amplifying audio signals, if we use the quietest track as the "base-line," then we'll have to adjust the level of the other tracks ''down'' to suit. In this case, the voice tracks are the quietest.</para></listitem>
+ <listitem><para>Take the quietest track, when set to 0 dB, as the limiting factor on how loud the other tracks should be. Since it's generally safer to avoid amplifying audio signals, if we use the quietest track as the "base-line," then we'll have to adjust the level of the other tracks <emphasis>down</emphasis> to suit. In this case, the voice tracks are the quietest.</para></listitem>
<listitem><para>At this point, it's best to stick with adjusting the busses' faders. If you adjust the faders on the tracks, this will affect the panning, and could lead to confusing problems later.</para></listitem>
- <listitem><para>Play through the session, and adjust the faders of the busses so that all of the tracks can be heard equally well. Remember that you're just aiming for ''most'' of the session to be balanced at this point; a single fader setting is unlikely to be acceptable for the entire session.</para></listitem>
+ <listitem><para>Play through the session, and adjust the faders of the busses so that all of the tracks can be heard equally well. Remember that you're just aiming for <emphasis>most</emphasis> of the session to be balanced at this point; a single fader setting is unlikely to be acceptable for the entire session.</para></listitem>
<listitem><para>You can adjust the fader setting in two ways:
<orderedlist>
<listitem><para>Click-and-drag the vertical, dotted control strip to the left of the level meter (which lights up as a track is playing).</para></listitem>
@@ -989,7 +989,7 @@
<itemizedlist>
<listitem><para>Establish two rows of performers, surrounding the listener in a semi-circle.</para></listitem>
<listitem><para>The strings will be in the closer row, to the north-west. This requires moving them to the left a bit.</para></listitem>
- <listitem><para>The vocal soloist will be in the closer row, just east of north (the middle). This requires moving her to the left ''just'' a little bit.</para></listitem>
+ <listitem><para>The vocal soloist will be in the closer row, just east of north (the middle). This requires moving her to the left <emphasis>just</emphasis> a little bit.</para></listitem>
<listitem><para>The vocal ensemble will be in the closer row, spread from north to north-east, allowing the soloist to remain in the same place. This will mostly require fader adjustment, to make the ensemble seem closer.</para></listitem>
<listitem><para>The lower marimba will be in the outer row, to the north-west. This may not require any adjustment, but perhaps a slight move to the left.</para></listitem>
<listitem><para>The higher marimba will be in the outer row, to the north-east. This requires a slight move to the left.</para></listitem>
@@ -1146,10 +1146,10 @@
</itemizedlist> -->
</para>
<para>
- '''Convesion quality''' and '''dither type''' are not available options for the file formats offered in Fedora Linux.
+ "Convesion quality" and "dither type" are not available options for the file formats offered in Fedora Linux.
</para>
<para>
- The '''CD Marker File Type''' allows you to export a CUE- or TOC-format list of CD tracks in the exported file. This is most useful when exporting a whole session, which contains a whole CD, that would be subsequently burned to disc.
+ The "CD Marker File Type" allows you to export a CUE- or TOC-format list of CD tracks in the exported file. This is most useful when exporting a whole session, which contains a whole CD, that would be subsequently burned to disc.
</para>
</section>
</section>
diff --git a/en-US/Audio_Vocabulary.xml b/en-US/Audio_Vocabulary.xml
index ef8da51..4c7e21f 100644
--- a/en-US/Audio_Vocabulary.xml
+++ b/en-US/Audio_Vocabulary.xml
@@ -13,7 +13,7 @@
<section id="sect-Musicians_Guide-Vocabulary-MIDI_Sequencer">
<title>MIDI Sequencer</title>
<para>
- A '''sequencer''' is a device or software program that produces signals that a synthesizer turns into sound. You can also use a sequencer to arrange MIDI signals into music. The Musicians' Guide covers two digital audio workstations (DAWs) that are primarily MIDI sequencers, Qtractor and Rosegarden. All three DAWs in this guide use MIDI signals to control other devices or effects.
+ A <firstterm>sequencer</firstterm> is a device or software program that produces signals that a synthesizer turns into sound. You can also use a sequencer to arrange MIDI signals into music. The Musicians' Guide covers two digital audio workstations (DAWs) that are primarily MIDI sequencers, Qtractor and Rosegarden. All three DAWs in this guide use MIDI signals to control other devices or effects.
</para>
</section>
@@ -32,13 +32,13 @@
</imageobject></inlinemediaobject>
</para>
<para>
- An '''audio bus''' sends audio signals from one place to another. Many different signals can be inputted to a bus simultaneously, and many different devices or applications can read from a bus simultaneously. Signals inputted to a bus are mixed together, and cannot be separated after entering a bus. All devices or applications reading from a bus receive the same signal.
+ An <firstterm>audio bus</firstterm> sends audio signals from one place to another. Many different signals can be inputted to a bus simultaneously, and many different devices or applications can read from a bus simultaneously. Signals inputted to a bus are mixed together, and cannot be separated after entering a bus. All devices or applications reading from a bus receive the same signal.
</para>
<para>
- All audio routed out of a program passes through the master bus. The '''master bus''' combines all audio tracks, allowing for final level adjustments and simpler mastering. The primary purpose of the master bus is to mix all of the tracks into two channels.
+ All audio routed out of a program passes through the master bus. The <firstterm>master bus</firstterm> combines all audio tracks, allowing for final level adjustments and simpler mastering. The primary purpose of the master bus is to mix all of the tracks into two channels.
</para>
<para>
- A '''sub-master bus''' combines audio signals before they reach the master bus. Using a sub-master bus is optional. They allow you to adjust more than one track in the same way, without affecting all the tracks.
+ A <firstterm>sub-master bus</firstterm> combines audio signals before they reach the master bus. Using a sub-master bus is optional. They allow you to adjust more than one track in the same way, without affecting all the tracks.
</para>
<para>
Audio busses are also used to send audio into effects processors.
@@ -48,7 +48,7 @@
<section id="sect-Musicians_Guide-Vocabulary-Level">
<title>Level (Volume/Loudness)</title>
<para>
- The perceived '''volume''' or '''loudness''' of sound is a complex phenomenon, not entirely understood by experts. One widely-agreed method of assessing loudness is by measuring the sound pressure level (SPL), which is measured in decibels (dB) or bels (B, equal to ten decibels). In audio production communities, this is called "level." The '''level''' of an audio signal is one way of measuring the signal's perceived loudness. The level is part of the information stored in an audio file.
+ The perceived <firstterm>volume</firstterm> or <firstterm>loudness</firstterm> of sound is a complex phenomenon, not entirely understood by experts. One widely-agreed method of assessing loudness is by measuring the sound pressure level (SPL), which is measured in decibels (dB) or bels (B, equal to ten decibels). In audio production communities, this is called level. The <firstterm>level</firstterm> of an audio signal is one way of measuring the signal's perceived loudness. The level is part of the information stored in an audio file.
</para>
<para>
There are many different ways to monitor and adjust the level of an audio signal, and there is no widely-agreed practice. One reason for this situation is the technical limitations of recorded audio. Most level meters are designed so that the average level is -6 dB on the meter, and the maximum level is 0 dB. This practice was developed for analog audio. We recommend using an external meter and the "K-system," described in a link below. The K-system for level metering was developed for digital audio.
@@ -78,13 +78,13 @@
<imagedata fileref="./images/FMG-Balance_and_Panning.png" format="PNG" />
</imageobject></mediaobject>
<para>
- '''Panning''' adjusts the portion of a channel's signal that is sent to each output channel. In a stereophonic (two-channel) setup, the two channels represent the "left" and the "right" speakers. Two channels of recorded audio are available in the DAW, and the default setup sends all of the "left" recorded channel to the "left" output channel, and all of the "right" recorded channel to the "right" output channel. Panning sends some of the left recorded channel's level to the right output channel, or some of the right recorded channel's level to the left output channel. Each recorded channel has a constant total output level, which is divided between the two output channels.
+ <firstterm>Panning</firstterm> adjusts the portion of a channel's signal that is sent to each output channel. In a stereophonic (two-channel) setup, the two channels represent the "left" and the "right" speakers. Two channels of recorded audio are available in the DAW, and the default setup sends all of the "left" recorded channel to the "left" output channel, and all of the "right" recorded channel to the "right" output channel. Panning sends some of the left recorded channel's level to the right output channel, or some of the right recorded channel's level to the left output channel. Each recorded channel has a constant total output level, which is divided between the two output channels.
</para>
<para>
The default setup for a left recorded channel is for "full left" panning, meaning that 100% of the output level is output to the left output channel. An audio engineer might adjust this so that 80% of the recorded channel's level is output to the left output channel, and 20% of the level is output to the right output channel. An audio engineer might make the left recorded channel sound like it is in front of the listener by setting the panner to "center," meaning that 50% of the output level is output to both the left and right output channels.
</para>
<para>
- Balance is sometimes confused with panning, even on commercially-available audio equipment. Adjusting the '''balance''' changes the volume level of the output channels, without redirecting the recorded signal. The default setting for balance is "center," meaning 0% change to the volume level. As you adjust the dial from "center" toward the "full left" setting, the volume level of the right output channel is decreased, and the volume level of the left output channel remains constant. As you adjust the dial from "center" toward the "full right" setting, the volume level of the left output channel is decreased, and the volume level of the right output channel remains constant. If you set the dial to "20% left," the audio equipment would reduce the volume level of the right output channel by 20%, increasing the perceived loudness of the left output channel by approximately 20%.
+ Balance is sometimes confused with panning, even on commercially-available audio equipment. Adjusting the <firstterm>balance</firstterm> changes the volume level of the output channels, without redirecting the recorded signal. The default setting for balance is "center," meaning 0% change to the volume level. As you adjust the dial from "center" toward the "full left" setting, the volume level of the right output channel is decreased, and the volume level of the left output channel remains constant. As you adjust the dial from "center" toward the "full right" setting, the volume level of the left output channel is decreased, and the volume level of the right output channel remains constant. If you set the dial to "20% left," the audio equipment would reduce the volume level of the right output channel by 20%, increasing the perceived loudness of the left output channel by approximately 20%.
</para>
<para>
You should adjust the balance so that you perceive both speakers as equally loud. Balance compensates for poorly set up listening environments, where the speakers are not equal distances from the listener. If the left speaker is closer to you than the right speaker, you can adjust the balance to the right, which decreases the volume level of the left speaker. This is not an ideal solution, but sometimes it is impossible or impractical to set up your speakers correctly. You should adjust the balance only at final playback.
@@ -103,7 +103,7 @@
</itemizedlist>
</para>
<para>
- Most audio software, particularly digital audio workstations (DAWs), allow the user to choose which scale they prefer. DAWs use a '''timeline''' to display the progression of time in a session, allowing you to do '''time-shifting'''; that is, adjust the time in the timeline when a region starts to be played.
+ Most audio software, particularly digital audio workstations (DAWs), allow the user to choose which scale they prefer. DAWs use a <firstterm>timeline</firstterm> to display the progression of time in a session, allowing you to do <firstterm>time-shifting</firstterm>; that is, adjust the time in the timeline when a region starts to be played.
</para>
<para>
Time is represented horizontally, where the leftmost point is the beginning of the session (zero, regardless of the unit of measurement), and the rightmost point is some distance after the end of the session.
@@ -113,7 +113,7 @@
<section id="sect-Musicians_Guide-Vocabulary-Synchronization">
<title>Synchronization</title>
<para>
- '''Synchronization''' is synchronizing the operation of multiple tools, frequently the movement of the transport. Synchronization also controls automation across applications and devices. MIDI signals are usually used for synchronization.
+ <firstterm>Synchronization</firstterm> coordinates the operation of multiple tools, most often the movement of the transport. Synchronization also controls automation across applications and devices. MIDI signals are usually used for synchronization.
</para>
</section>
@@ -121,21 +121,21 @@
<title>Routing and Multiplexing</title>
<para>
<inlinemediaobject><imageobject>
- <!-- [[File:FMG-routing_and_multiplexing.png|200px|left|Illustration of routing and multiplexing in the "Connections" window of the QjackCtl interface.]] -->
+ <!-- [[File:FMG-routing_and_multiplexing.png|200px|left|Illustration of routing and multiplexing in the "Connections" window of the <application>QjackCtl</application> interface.]] -->
<!-- [[FMG-routing_and_multiplexing.xcf]] -->
<imagedata fileref="./images/FMG-routing_and_multiplexing.png" format="PNG" />
</imageobject></inlinemediaobject>
- '''Routing''' audio transmits a signal from one place to another - between applications, between parts of applications, or between devices. On Linux systems, the JACK Audio Connection Kit is used for audio routing. JACK-aware applications (and PulseAudio ones, if so configured) provide inputs and outputs to the JACK server, depending on their configuration. The QjackCtl application can adjust the default connections. You can easily reroute the output of a program like FluidSynth so that it can be recorded by Ardour, for example, by using QjackCtl.
+ <firstterm>Routing</firstterm> audio transmits a signal from one place to another - between applications, between parts of applications, or between devices. On Linux systems, the <systemitem>JACK Audio Connection Kit</systemitem> is used for audio routing. <systemitem>JACK</systemitem>-aware applications (and <systemitem>PulseAudio</systemitem> ones, if so configured) provide inputs and outputs to the <systemitem>JACK</systemitem> server, depending on their configuration. The <application>QjackCtl</application> application can adjust the default connections. You can easily reroute the output of a program like FluidSynth so that it can be recorded by <application>Ardour</application>, for example, by using <application>QjackCtl</application>.
</para>
<para>
- '''Multiplexing''' allows you to connect multiple devices and applications to a single input or output. QjackCtl allows you to easily perform multiplexing. This may not seem important, but remember that only one connection is possible with a physical device like an audio interface. Before computers were used for music production, multiplexing required physical devices to split or combine the signals.
+ <firstterm>Multiplexing</firstterm> allows you to connect multiple devices and applications to a single input or output. <application>QjackCtl</application> allows you to easily perform multiplexing. This may not seem important, but remember that only one connection is possible with a physical device like an audio interface. Before computers were used for music production, multiplexing required physical devices to split or combine the signals.
</para>
</section>
<section id="sect-Musicians_Guide-Multichannel_Audio">
<title>Multichannel Audio</title>
<para>
- An '''audio channel''' is a single path of audio data. '''Multichannel audio''' is any audio which uses more than one channel simultaneously, allowing the transmission of more audio data than single-channel audio.
+ An <firstterm>audio channel</firstterm> is a single path of audio data. <firstterm>Multichannel audio</firstterm> is any audio which uses more than one channel simultaneously, allowing the transmission of more audio data than single-channel audio.
</para>
<para>
Audio was originally recorded with only one channel, producing "monophonic," or "mono" recordings. Beginning in the 1950s, stereophonic recordings, with two independent channels, began replacing monophonic recordings. Since humans have two independent ears, it makes sense to record and reproduce audio with two independent channels, involving two speakers. Most sound recordings available today are stereophonic, and people have found this mostly satisfying.
diff --git a/en-US/Digital_Audio_Workstations.xml b/en-US/Digital_Audio_Workstations.xml
index 64f6c40..59cb503 100644
--- a/en-US/Digital_Audio_Workstations.xml
+++ b/en-US/Digital_Audio_Workstations.xml
@@ -7,7 +7,7 @@
<chapter id="chap-Musicians_Guide-Digital_Audio_Workstations">
<title>Digital Audio Workstations</title>
<para>
- The term '''Digital Audio Workstation''' (henceforth '''DAW''') refers to the entire hardware and software setup used for professional (or professional-quality) audio recording, manipulation, synthesis, and production. It originally referred to devices purpose-built for the task, but as personal computers have become more powerful and wide-spread, certain specially-designed personal computers can also be thought of as DAWs. The software running on these computers, especially software capable of multi-track recording, playback, and synthesis, is simply called "DAW software," which is often shortened to "DAW." So, the term "DAW" and its usage are moderately ambiguous, but generally refer to one of the things mentioned.
+ The term <firstterm>Digital Audio Workstation</firstterm> (henceforth <firstterm>DAW</firstterm>) refers to the entire hardware and software setup used for professional (or professional-quality) audio recording, manipulation, synthesis, and production. It originally referred to devices purpose-built for the task, but as personal computers have become more powerful and wide-spread, certain specially-designed personal computers can also be thought of as DAWs. The software running on these computers, especially software capable of multi-track recording, playback, and synthesis, is simply called "DAW software," which is often shortened to "DAW." So, the term "DAW" and its usage are moderately ambiguous, but generally refer to one of the things mentioned.
</para>
<para>
For other terms related to digital audio, see <xref linkend="chap-Musicians_Guide-Sound_Cards" />.
@@ -16,19 +16,19 @@
<section id="sect-Musicians_Guide-Knowing_Which_DAW_to_Use">
<title>Knowing Which DAW to Use</title>
<para>
- The Musicians' Guide covers three widely-used DAWs: Ardour, Qtractor, and Rosegarden. All three use JACK extensively, are highly configurable, share a similar user interface, and allow users to work with both audio and MIDI signals. Many other DAWs exist, including a wide selection of commercially-available solutions. Here is a brief description of the programs documented in this Guide:
+ The Musicians' Guide covers three widely-used DAWs: <application>Ardour</application>, <application>Qtractor</application>, and <application>Rosegarden</application>. All three use <systemitem>JACK</systemitem> extensively, are highly configurable, share a similar user interface, and allow users to work with both audio and MIDI signals. Many other DAWs exist, including a wide selection of commercially-available solutions. Here is a brief description of the programs documented in the Musicians' Guide:
<itemizedlist>
- <listitem><para>Ardour: the open-source standard for audio manipulation. Flexible and extensible.</para></listitem>
- <listitem><para>Qtractor: a relative new-comer, but easy to use; a "lean and mean," MIDI-focused DAW. Available from Planet CCRMA at Home or RPM Fusion.</para></listitem>
- <listitem><para>Rosegarden: a well-tested, feature-packed workhorse of Linux audio, especially MIDI. Includes a visual score editor for creating MIDI tracks.</para></listitem>
+ <listitem><para><application>Ardour</application> is the open-source standard for audio manipulation. Flexible and extensible.</para></listitem>
+ <listitem><para><application>Qtractor</application> is a relative new-comer, but easy to use; a "lean and mean," MIDI-focused DAW. Available from Planet CCRMA at Home or RPM Fusion.</para></listitem>
+ <listitem><para><application>Rosegarden</application> is a well-tested, feature-packed workhorse of Linux audio, especially MIDI. Includes a visual score editor for creating MIDI tracks.</para></listitem>
</itemizedlist>
</para>
<para>
If you are unsure of where to start, then you may not need a DAW at all:
<itemizedlist>
- <listitem><para>If you are looking for a high-quality recording application, or a tool for manipulating one audio file at a time, then you would probably be better off with Audacity. This will be the choice of most computer users, especially those new to computer audio, or looking for a quick solution requiring little specialized knowledge. Audacity is also a good way to get your first computer audio experiences, specifically because it is easier to use than most other audio software.</para></listitem>
- <listitem><para>To take full advantage of the features offered by Ardour, Qtractor, and Rosegarden, your computer should be equipped with professional-quality audio equipment, including an after-market audio interface and input devices like microphones. If you do not have access to such equipment, then Audacity may be a better choice for you.</para></listitem>
- <listitem><para>If you are simply hoping to create a "MIDI recording" of some sheet music, you are probably better off using LilyPond. This program is designed primarily to create printable sheet music, but it will produce a MIDI-format version of a score if you include the following command in the "score" section of your LilyPond source file: <code>\midi { }</code>. There are a selection of options that can be put in the "midi" section; refer to the LilyPond help files for a listing.</para></listitem>
+ <listitem><para>If you are looking for a high-quality recording application, or a tool for manipulating one audio file at a time, then you would probably be better off with <application>Audacity</application>. This will be the choice of most computer users, especially those new to computer audio, or looking for a quick solution requiring little specialized knowledge. <application>Audacity</application> is also a good way to get your first computer audio experiences, specifically because it is easier to use than most other audio software.</para></listitem>
+ <listitem><para>To take full advantage of the features offered by <application>Ardour</application>, <application>Qtractor</application>, and <application>Rosegarden</application>, your computer should be equipped with professional-quality audio equipment, including an after-market audio interface and input devices like microphones. If you do not have access to such equipment, then Audacity may be a better choice for you.</para></listitem>
+ <listitem><para>If you are simply hoping to create a "MIDI recording" of some sheet music, you are probably better off using <application>LilyPond</application>. This program is designed primarily to create printable sheet music, but it will produce a MIDI-format version of a score if you include the following command in the <literal>score</literal> section of your <application>LilyPond</application> source file: <code>\midi { }</code>. There are a selection of options that can be put in the <literal>midi</literal> section; refer to the <application>LilyPond</application> help files for a listing.</para></listitem>
</itemizedlist>
</para>
</section>
@@ -41,7 +41,7 @@
<section id="sect-Musicians_Guide-Recording">
<title>Recording</title>
<para>
- Recording is the process of capturing audio regions (also called "clips" or "segments") into the DAW software, for later processing. Recording is a complex process, involving a microphone that captures sound energy, translates it into electrical energy, and transmits it to an audio interface. The audio interface converts the electrical energy into digital signals, and sends it through the operating system to the DAW software. The DAW stores regions in memory and on the hard drive as required. Every time the musicians perform some (or all) of the performance to be recorded, while the DAW is recording, it is considered to be a '''take'''. A successful recording usually requires several takes, due to the inconsistencies of musical performance and of the related technological aspects.
+ Recording is the process of capturing audio regions (also called "clips" or "segments") into the DAW software, for later processing. Recording is a complex process, involving a microphone that captures sound energy, translates it into electrical energy, and transmits it to an audio interface. The audio interface converts the electrical energy into digital signals, and sends it through the operating system to the DAW software. The DAW stores regions in memory and on the hard drive as required. Every time the musicians perform some (or all) of the performance to be recorded, while the DAW is recording, it is considered to be a <firstterm>take</firstterm>. A successful recording usually requires several takes, due to the inconsistencies of musical performance and of the related technological aspects.
</para>
</section>
<section id="sect-Musicians_Guide-Mixing">
@@ -61,7 +61,7 @@
</itemizedlist>
</para>
<para>
- When the person performing the mixing decides that they have finished, their finalized production is called the '''final mix'''.
+ When the person performing the mixing decides that they have finished, their finalized production is called the <firstterm>final mix</firstterm>.
</para>
</section>
<section id="sect-Musicians_Guide-Mastering">
@@ -98,7 +98,7 @@
<section id="sect-Musicians_Guide-Session">
<title>Session</title>
<para>
- A '''session''' is all of the tracks, regions, automation settings, and everything else that goes along with one "file" saved by the DAW software. Some software DAWs manage to hide the entire session within one file, but others instead create a new directory to hold the regions and other data.
+ A <firstterm>session</firstterm> is all of the tracks, regions, automation settings, and everything else that goes along with one "file" saved by the DAW software. Some software DAWs manage to hide the entire session within one file, but others instead create a new directory to hold the regions and other data.
</para>
<para>
Typically, one session is used to hold an entire recording session; it is broken up into individual songs or movements after recording. Sometimes, as in the tutorial examples with the Musicians' Guide, one session holds only one song or movement. There is no strict rule as to how much music should be held within one session, so your personal preference can determine what you do here.
@@ -108,21 +108,21 @@
<section id="sect-Musicians_Guide-Track_and_Multitrack">
<title>Track and Multitrack</title>
<para>
- A '''track''' represents one channel, or a predetermined collection of simultaneous, inseparable channels (as is often the case with stereo audio). In the DAW's main window, tracks are usually represented as rows, whereas time is represented by columns. A track may hold multiple regions, but usually only one of those regions can be heard at a time. The '''multitrack''' capability of modern software-based DAWs is one of the reasons for their success. Although each individual track can play only one region at a time, the use of multiple tracks allows the DAW's outputted audio to contain a virtually unlimited number of simultaneous regions. The most powerful aspect of this is that audio does not have to be recorded simultaneously in order to be played back simultaneously; you could sing a duet with yourself, for example.
+ A <firstterm>track</firstterm> represents one channel, or a predetermined collection of simultaneous, inseparable channels (as is often the case with stereo audio). In the DAW's main window, tracks are usually represented as rows, whereas time is represented by columns. A track may hold multiple regions, but usually only one of those regions can be heard at a time. The <firstterm>multitrack</firstterm> capability of modern software-based DAWs is one of the reasons for their success. Although each individual track can play only one region at a time, the use of multiple tracks allows the DAW's outputted audio to contain a virtually unlimited number of simultaneous regions. The most powerful aspect of this is that audio does not have to be recorded simultaneously in order to be played back simultaneously; you could sing a duet with yourself, for example.
</para>
</section>
<section id="sect-Musicians_Guide-Region_Clip_Segment">
<title>Region, Clip, or Segment</title>
<para>
- Region, clip, and segment are synonyms: different software uses a different word to refer to the same thing. A '''region''' (or '''clip''' or '''segment''') is the portion of audio recorded into one track during one take. Regions are represented in the main DAW interface window as a rectangle, usually coloured, and always contained in only one track. Regions containing audio signal data usually display a spectrographic representation of that data. Regions containing MIDI signal data usually displayed as matrix-based representation of that data.
+ Region, clip, and segment are synonyms: different software uses a different word to refer to the same thing. A x<firstterm>multitrack</firstterm> (or <firstterm>clip</firstterm> or <firstterm>segment</firstterm>) is the portion of audio recorded into one track during one take. Regions are represented in the main DAW interface window as a rectangle, usually coloured, and always contained in only one track. Regions containing audio signal data usually display a spectrographic representation of that data. Regions containing MIDI signal data usually displayed as matrix-based representation of that data.
</para>
<para>
For the three DAW applications in the Musicians' Guide:
<itemizedlist>
- <listitem><para>Ardour calls them "regions,"</para></listitem>
- <listitem><para>Qtractor calls them "clips," and,</para></listitem>
- <listitem><para>Rosegarden calls them "segments."</para></listitem>
+ <listitem><para><application>Ardour</application> calls them "regions,"</para></listitem>
+ <listitem><para><application>Qtractor</application> calls them "clips," and,</para></listitem>
+ <listitem><para><application>Rosegarden</application> calls them "segments."</para></listitem>
</itemizedlist>
</para>
</section>
@@ -139,17 +139,17 @@
<section id="sect-Musicians_Guide-Transport_and_Playhead">
<title>Transport and Playhead</title>
<para>
- The '''transport''' is responsible for managing the current time in a session, and with it the playhead. The '''playhead''' marks the point on the timeline from where audio audio would be played, or to where audio would be recorded. The transport controls the playhead, and whether it is set for recording or only playback. The transport can move the playhead forward or backward, in slow motion, fast motion, or real time. In most computer-based DAWs, the playhead can also be moved with the cursor. The playhead is represented on the DAW interface as a vertical line through all tracks. The transport's buttons and displays are usually located in a toolbar at the top of the DAW window, but some people prefer to have the transport controls detached from the main interface, and this is how they appear by default in Rosegarden.
+ The <firstterm>transport</firstterm> is responsible for managing the current time in a session, and with it the playhead. The <firstterm>playhead</firstterm> marks the point on the timeline from where audio audio would be played, or to where audio would be recorded. The transport controls the playhead, and whether it is set for recording or only playback. The transport can move the playhead forward or backward, in slow motion, fast motion, or real time. In most computer-based DAWs, the playhead can also be moved with the cursor. The playhead is represented on the DAW interface as a vertical line through all tracks. The transport's buttons and displays are usually located in a toolbar at the top of the DAW window, but some people prefer to have the transport controls detached from the main interface, and this is how they appear by default in Rosegarden.
</para>
</section>
<section id="sect-Musicians_Guide-Automation">
<title>Automation</title>
<para>
- Automation of the DAW sounds like it might be an advanced topic, or something used to replace decisions made by a human. This is absolutely not the case - '''automation''' allows the user to automatically make the same adjustments every time a session is played. This is superior to manual-only control because it allows very precise, gradual, and consistent adjustments, because it relieves you of having to remember the adjustments, and because it allows many more adjustments to be made simultaneously than you could make manually. The reality is that automation allows super-human control of a session. Most settings can be adjusted by means of automation; the most common are the fader and the panner.
+ Automation of the DAW sounds like it might be an advanced topic, or something used to replace decisions made by a human. This is absolutely not the case - <firstterm>automation</firstterm> allows the user to automatically make the same adjustments every time a session is played. This is superior to manual-only control because it allows very precise, gradual, and consistent adjustments, because it relieves you of having to remember the adjustments, and because it allows many more adjustments to be made simultaneously than you could make manually. The reality is that automation allows super-human control of a session. Most settings can be adjusted by means of automation; the most common are the fader and the panner.
</para>
<para>
- The most common method of automating a setting is with a two-dimensional graph called an '''envelope''', which is drawn on top of an audio track, or underneath it in an '''automation track'''. The user adds adjustment points by adding and moving points on the graph. This method allows for complex, gradual changes of the setting, as well as simple, one-time changes. Automation is often controlled by means of MIDI signals, for both audio and MIDI tracks. This allows for external devices to adjust settings in the DAW, and vice-versa - you can actually automate your own hardware from within a software-based DAW! Of course, not all hardware supports this, so refer to your device's user manual.
+ The most common method of automating a setting is with a two-dimensional graph called an <firstterm>envelope</firstterm>, which is drawn on top of an audio track, or underneath it in an <firstterm>automation track</firstterm>. The user adds adjustment points by adding and moving points on the graph. This method allows for complex, gradual changes of the setting, as well as simple, one-time changes. Automation is often controlled by means of MIDI signals, for both audio and MIDI tracks. This allows for external devices to adjust settings in the DAW, and vice-versa - you can actually automate your own hardware from within a software-based DAW! Of course, not all hardware supports this, so refer to your device's user manual.
</para>
</section>
</section>
@@ -165,7 +165,7 @@
File:Qtractor-interface-track_info.png
File:Qtractor-interface-transport.png
-->
- This section describes various components of software-based DAW interfaces. Although the Qtractor application is visible in the images, both Ardour and Rosegarden (along with most other DAW software) have an interface that differs only in details, such as which buttons are located where.
+ This section describes various components of software-based DAW interfaces. Although the <application>Qtractor</application> application is visible in the images, both <application>Ardour</application> and <application>Rosegarden</application> (along with most other DAW software) have an interface that differs only in details, such as which buttons are located where.
</para>
<section id="sect-Musicians_Guide-Messages_Pane">
@@ -177,7 +177,7 @@
</imageobject></inlinemediaobject>
</para>
<para>
- The "messages" pane, shown in the above diagram, contains messages produced by the DAW, and sometimes messages produced by software used by the DAW, such as JACK. If an error occurs, or if the DAW does not perform as expected, you should check the "messages" pane for information that may help you to get the desired results. The "messages" pane can also be used to determine whether JACK and the DAW were started successfully, with the options you prefer.
+ The "messages" pane, shown in the above diagram, contains messages produced by the DAW, and sometimes messages produced by software used by the DAW, such as <systemitem>JACK</systemitem>. If an error occurs, or if the DAW does not perform as expected, you should check the "messages" pane for information that may help you to get the desired results. The "messages" pane can also be used to determine whether <systemitem>JACK</systemitem> and the DAW were started successfully, with the options you prefer.
</para>
</section>
@@ -244,19 +244,19 @@
The transport controls allow you to manipulate the transport in various ways. The shape of the buttons is somewhat standardized; a similar-looking button will usually perform the same function in all DAWs, as well as in consumer electronic devices like CD players and DVD players.
</para>
<para>
- The single, left-pointing arrow with a vertical line will move the transport to the start of the session, without playing or recording any material. In "Qtractor," if there is a blue place-marker between the transport and the start of the session, the transport will skip to the blue place-marker. You can press the button again if you wish to skip to the next blue place-marker or the beginning of the session.
+ The single, left-pointing arrow with a vertical line will move the transport to the start of the session, without playing or recording any material. In <application>Qtractor</application>, if there is a blue place-marker between the transport and the start of the session, the transport will skip to the blue place-marker. You can press the button again if you wish to skip to the next blue place-marker or the beginning of the session.
</para>
<para>
The double left-pointing arrows move the transport in fast motion, towards the start of the session. The double right-pointing arrows move the transport in fast motion, towards the end of the session.
</para>
<para>
- The single, right-pointing arrow with a vertical line will move the transport to the end of the last region currently in a session. In "Qtractor," if there is a blue place-marker between the transport and the end of the last region in the session, the transport will skip to the blue place-marker. You can press the button again if you wish to skip to the next blue place-marker or the end of the last region in the session.
+ The single, right-pointing arrow with a vertical line will move the transport to the end of the last region currently in a session. In <application>Qtractor</application>, if there is a blue place-marker between the transport and the end of the last region in the session, the transport will skip to the blue place-marker. You can press the button again if you wish to skip to the next blue place-marker or the end of the last region in the session.
</para>
<para>
The single, right-pointing arrow is commonly called "play," but it actually moves the transport forward in real-time. When it does this, if the transport is armed for recording, any armed tracks will record. Whether or not the transport is armed, pressing the "play" button causes all un-armed tracks to play all existing regions.
</para>
<para>
- The circular button arms the transport for recording. It is conventionally red in colour. In "Qtractor," the transport can only be armed ''after'' at least one track has been armed; to show this, the transport's "arm" button only turns red if a track is armed.
+ The circular button arms the transport for recording. It is conventionally red in colour. In <application>Qtractor</application>, the transport can only be armed <emphasis>after</emphasis> at least one track has been armed; to show this, the transport's "arm" button only turns red if a track is armed.
</para>
</section>
</section>
diff --git a/en-US/FluidSynth.xml b/en-US/FluidSynth.xml
index a4c19e0..41e1c16 100644
--- a/en-US/FluidSynth.xml
+++ b/en-US/FluidSynth.xml
@@ -7,7 +7,7 @@
<chapter id="chap-Musicians_Guide-FluidSynth">
<title>FluidSynth</title>
<para>
- <application>FluidSynth</application> is a software-based MIDI synthesizer. <application>FluidSynth</application> accepts MIDI input from programs like Qtractor and Rosegarden, and uses SoundFont technology to create audio signals. This makes <application>FluidSynth</application> a very flexible tool; it can be used even on low-power computers, doesn't require specialized hardware, and can take advantage of a wide selection of high-quality MIDI instruments. When used with the Qsynth graphical interface, <application>FluidSynth</application> becomes even more powerful: users can easily control basic effects like chorus and reverb, and they can start multiple <application>FluidSynth</application> synthesizers, each with their own settings and MIDI instrument assignments. Finally, because Qsynth was created and is maintained by the same developers as Qtractor and QjackCtl, it provides a familiar interface, and integrates well with these other applications.
+ <application>FluidSynth</application> is a software-based MIDI synthesizer. <application>FluidSynth</application> accepts MIDI input from programs like Qtractor and Rosegarden, and uses SoundFont technology to create audio signals. This makes <application>FluidSynth</application> a very flexible tool; it can be used even on low-power computers, doesn't require specialized hardware, and can take advantage of a wide selection of high-quality MIDI instruments. When used with the <application>Qsynth</application> graphical interface, <application>FluidSynth</application> becomes even more powerful: users can easily control basic effects like chorus and reverb, and they can start multiple <application>FluidSynth</application> synthesizers, each with their own settings and MIDI instrument assignments. Finally, because <application>Qsynth</application> was created and is maintained by the same developers as Qtractor and QjackCtl, it provides a familiar interface, and integrat
es well with these other applications.
</para>
<section id="sect-Musicians_Guide-FluidSynth-SoundFont_Technology_and_MIDI">
@@ -68,20 +68,20 @@
<section id="sect-Musicians_Guide-FluidSynth-Req_and_Inst-Software_Requirements">
<title>Software Requirements</title>
<para>
- <application>FluidSynth</application> requires the JACK Audio Connection Kit. If you have not already installed the JACK packages from the Planet CCRMA at Home repository, then it is recommended that you do so ''before'' installing <application>FluidSynth</application>. See <xref linkend="sect-Musicians_Guide-Install_and_Configure_JACK" /> for instructions.
+ <application>FluidSynth</application> requires the <systemitem><application>JACK</application> Audio Connection Kit</systemitem>. If you have not already installed the <application>JACK</application> packages from the Planet CCRMA at Home repository, then it is recommended that you do so <emphasis>before</emphasis> installing <application>FluidSynth</application>. See <xref linkend="sect-Musicians_Guide-Install_and_Configure_JACK" /> for instructions.
</para>
</section>
<section id="sect-Musicians_Guide-FluidSynth-Req_and_Inst-Installation">
<title>Thare Are Two Ways to Install <application>FluidSynth</application></title>
<para>
- There are two ways to install <application>FluidSynth</application>. The first, to install <application>FluidSynth</application> with Qsynth, allows <application>FluidSynth</application> to be used with the Qsynth graphical interface. It also installs a default SoundFont, which can be used by any SoundFont-aware application (like <application>timidity++</application>). This installation method does not - by default - allow <application>FluidSynth</application> to be used from a terminal, although this ability can be easily added later. This is the installation method recommended for most users.
+ There are two ways to install <application>FluidSynth</application>. The first, to install <application>FluidSynth</application> with <application>Qsynth</application>, allows <application>FluidSynth</application> to be used with the <application>Qsynth</application> graphical interface. It also installs a default SoundFont, which can be used by any SoundFont-aware application (like <application>timidity++</application>). This installation method does not - by default - allow <application>FluidSynth</application> to be used from a terminal, although this ability can be easily added later. This is the installation method recommended for most users.
</para>
<para>
- The second way to install <application>FluidSynth</application> is without the Qsynth graphical interface. This method allows <application>FluidSynth</application> to be run from a terminal, and does not install a default SoundFont. This installation is recommended only for advanced users.
+ The second way to install <application>FluidSynth</application> is without the <application>Qsynth</application> graphical interface. This method allows <application>FluidSynth</application> to be run from a terminal, and does not install a default SoundFont. This installation is recommended only for advanced users.
</para>
</section>
<section id="sect-Musicians_Guide-FluidSynth-Req_and_Inst-Installation_with_Qsynth">
- <title>Installation with Qsynth</title>
+ <title>Installation with <application>Qsynth</application></title>
<para>
This installation method is recommended for most users, and will install everything you need to start using <application>FluidSynth</application>.
</para>
@@ -89,17 +89,17 @@
<step><para>Use "PackageKit" or "KPackageKit" to install the "qsynth" package.</para></step>
<step><para>Review and approve the proposed installation:
<itemizedlist>
- <listitem><para><!-- this was another warning to install JACK but I don't want it any more --></para></listitem>
+ <listitem><para><!-- this was another warning to install <application>JACK</application> but I don't want it any more --></para></listitem>
<listitem><para>The installation may include the "fluid-soundfont-gm" package, which is quite large.</para></listitem>
</itemizedlist>
</para></step>
</procedure>
<para>
- If you wish to use <application>FluidSynth</application> from a terminal, without the Qsynth graphical interface, you can enable this capability by installing the "fluidsynth" package. This package is not needed if you only intend to run <application>FluidSynth</application> with Qsynth, because Qsynth only uses files in the "fluidsynth-libs" package, which is automatically installed with Qsynth. If you are unsure of whether you should install the "fluidsynth" package, you can safely install it, even if you never use it. It only uses a small amount of hard drive space.
+ If you wish to use <application>FluidSynth</application> from a terminal, without the <application>Qsynth</application> graphical interface, you can enable this capability by installing the <package>fluidsynth</package> package. This package is not needed if you only intend to run <application>FluidSynth</application> with <application>Qsynth</application>, because <application>Qsynth</application> only uses files in the <package>fluidsynth-libs</package> package, which is automatically installed with <application>Qsynth</application>. If you are unsure of whether you should install the <package>fluidsynth</package> package, you can safely install it, even if you never use it. It only uses a small amount of hard drive space.
</para>
</section>
<section id="sect-Musicians_Guide-FluidSynth-Req_and_Inst-Installation_without_Qsynth">
- <title>Installation without Qsynth</title>
+ <title>Installation without <application>Qsynth</application></title>
<para>
This installation method is recommended only for advanced users. You will have to use <application>FluidSynth</application> from a terminal. You will also have to install a SoundFont file before using <application>FluidSynth</application>.
</para>
@@ -110,9 +110,10 @@
<section id="sect-Musicians_Guide-FluidSynth-Req_and_Inst">
<title>Installation of SoundFont Files</title>
<para>
- Qsynth automatically installs a SoundFont for use with <application>FluidSynth</application>, but if you did not install Qsynth, or if you want to add additional SoundFont files with additional programs, you will need to install them separately. The Fedora package repositories offer a small selection of SoundFont files, which you can find by searching for "soundfont" with PackageKit, KPackageKit, or yum. These files will automatically be installed correctly. If you wish to install additional SoundFont files, it is recommended that you install them in the same location - and with the same security settings - as the ones available from the Fedora repositories. If you do this, then you enable all users of the computer system to access the files, you will not "lose" them if you forget where they are stored, and you help to minimize the potential security risk of using software downloaded from the internet.
-
- The following steps will move a SoundFont file called "myFont.sf2" to the default folder (<filename>/usr/share/soundfonts</filename>), and correctly set the security settings. Note that you will need the system administrator's password (belonging to the "root" account) to complete this operation. If you do not have this password, it is best to ask the system administrator to install the files for you. Alternately, you may simply use the SoundFont file from your a sub-folder in your home folder.
+ <application>Qsynth</application> automatically installs a SoundFont for use with <application>FluidSynth</application>, but if you did not install <application>Qsynth</application>, or if you want to add additional SoundFont files with additional programs, you will need to install them separately. The Fedora package repositories offer a small selection of SoundFont files, which you can find by searching for "soundfont" with PackageKit, KPackageKit, or yum. These files will automatically be installed correctly. If you wish to install additional SoundFont files, it is recommended that you install them in the same location - and with the same security settings - as the ones available from the Fedora repositories. If you do this, then you enable all users of the computer system to access the files, you will not "lose" them if you forget where they are stored, and you help to minimize the potential security risk of using software downloaded from the internet.
+ </para>
+ <para>
+ The following steps move a SoundFont file called <filename>myFont.sf2</filename> to the default folder (<filename>/usr/share/soundfonts</filename>), and correctly set the security settings. Note that you will need the system administrator's password (belonging to the "root" account) to complete this operation. If you do not have this password, it is best to ask the system administrator to install the files for you. Alternately, you may simply use the SoundFont file from your a sub-folder in your home folder.
</para>
<procedure>
<step><para>Start a shell or terminal and navigate to the folder where the SoundFont file is currently stored.</para></step>
@@ -131,7 +132,8 @@
<substeps><step><para>Modify the command as necessary to refer to your SoundFont file, rather than <filename>myFont.sf2</filename>.</para></step>
<step><para>The output should resemble this: <programlisting><![CDATA[-rw-r--r--. 1 root root 9 2010-06-23 02:28 myFont.sf2]]></programlisting> but with a different date, time, and filename.</para></step>
</substeps></step>
- <step><para>Highly-observant users may notice that the SELinux context of the new file is different from that of any Fedora-installed SoundFont file. As long as the type is <literal>usr_t</literal>, which it should be by default, then there is no practical difference (no difference in enforcement) between this and a Fedora-installed SoundFont file. If you don't know what this means, or if you hadn't noticed it, then it means that this additional SoundFont file should not create a new potential security problem.</para></step>
+ <!-- They'll have no idea what SELinux is, so I should explain that, or not mention it at all -->
+ <step><para>Highly-observant users may notice that the SELinux<!-- CRA: Is SELinux a <systemcomponent?> --> context of the new file is different from that of any Fedora-installed SoundFont file. As long as the type is <literal>usr_t</literal>, which it should be by default, then there is no practical difference (no difference in enforcement) between this and a Fedora-installed SoundFont file. If you don't know what this means, or if you hadn't noticed it, then it means that this additional SoundFont file should not create a new potential security problem.</para></step>
</procedure>
</section>
</section> <!-- Ends "Requirements and Installation" Section --> <!-- <application>FluidSynth</application>-Req_and_Inst- -->
@@ -139,10 +141,10 @@
<section id="sect-Musicians_Guide-FluidSynth-In_a_Terminal">
<title>Using <application>FluidSynth</application> in a Terminal</title>
<para>
- This is not the recommended way to use <application>FluidSynth</application>, because the Qsynth graphical interface is much easier to use. Qsynth automatically configures most of <application>FluidSynth</application>'s settings by default, allowing you to avoid focus on how you want to use <application>FluidSynth</application>, rather than on how to use <application>FluidSynth</application>.
+ This is not the recommended way to use <application>FluidSynth</application>, because the <application>Qsynth</application> graphical interface is much easier to use. <application>Qsynth</application> automatically configures most of <application>FluidSynth</application>'s settings by default, allowing you to avoid focus on how you want to use <application>FluidSynth</application>, rather than on how to use <application>FluidSynth</application>.
</para>
<para>
- If you want to use <application>FluidSynth</application> in a terminal, you can use the <command>fluidsynth</command> command. The default sample-rate is 44.1 kHz, so if you want to use JACK at a different sample rate, you need to use the <command>-r</command> flag, like this: <command>fluidsynth -r 48000</command>
+ If you want to use <application>FluidSynth</application> in a terminal, you can use the <command>fluidsynth</command> command. The default sample-rate is 44.1 kHz, so if you want to use <application>JACK</application> at a different sample rate, you need to use the <command>-r</command> flag, like this: <command>fluidsynth -r 48000</command>
</para>
<para>
When you start <application>FluidSynth</application> from a terminal, it will normally start a shell of its own. How to use this shell is beyond the scope of the Musicians' Guide, but you can get basic help by running the "help" command from the <application>FluidSynth</application> command line.
@@ -150,23 +152,23 @@
</section>
<section id="sect-Musicians_Guide-FluidSynth-Configuring">
- <title>Configuring Qsynth</title>
+ <title>Configuring <application>Qsynth</application></title>
<para>
- When you quit Qsynth, all settings are preserved, and re-used when Qsynth is re-started. This includes settings for additional instances of Qsynth (described below), which are also re-created when Qsynth is re-started.
+ When you quit <application>Qsynth</application>, all settings are preserved, and re-used when <application>Qsynth</application> is re-started. This includes settings for additional instances of <application>Qsynth</application> (described below), which are also re-created when <application>Qsynth</application> is re-started.
</para>
<section id="sect-Musicians_Guide-FluidSynth-Configuring-Starting_FluidSynth">
<title>Starting <application>FluidSynth</application></title>
<procedure>
- <step><para>Start Qsynth from the Applications menu, or the K Menu</para></step>
+ <step><para>Start <application>Qsynth</application> from the Applications menu, or the K Menu</para></step>
<step><para>The <application>FluidSynth</application> engine will be started automatically.</para></step>
- <step><para>The row of buttons at the right of the Qsynth window control Qsynth. The other settings control <application>FluidSynth</application>.</para></step>
+ <step><para>The row of buttons at the right of the <application>Qsynth</application> window control <application>Qsynth</application>. The other settings control <application>FluidSynth</application>.</para></step>
<step><para>You can use the "Messages" button to display a window containing <application>FluidSynth</application>'s output. If <application>FluidSynth</application> doesn't work as expected, you can use this window to view any error message that might have been produced.</para></step>
</procedure>
</section>
<section id="sect-Musicians_Guide-FluidSynth-Configuring-SoundFont">
<title>SoundFont Configuration</title>
<para>
- The default "FluidR3" SoundFont, installed with Qsynth, is automatically configured.
+ The default "FluidR3" SoundFont, installed with <application>Qsynth</application>, is automatically configured.
</para>
<para>
To configure an additional Soundfount:
@@ -178,17 +180,17 @@
</procedure>
</section>
<section id="sect-Musicians_Guide-FluidSynth-Configuring-JACK_Output">
- <title>JACK Output Configuration</title>
+ <title><application>JACK</application> Output Configuration</title>
<para>
- It is possible to configure <application>FluidSynth</application> to output synthesized audio either to JACK or to ALSA. The default, and recommended, method is to output synthesized audio to JACK. This allows the greatest control over audio quality, and the greatest flexibility in terms of routing and multiplexing (for definition see <xref linkend="sect-Musicians_Guide-Vocabulary-Routing_and_Multiplexing" />), which allows you to simultaneously record the synthesized audio signal and listen to it.
+ It is possible to configure <application>FluidSynth</application> to output synthesized audio either to <application>JACK</application> or to ALSA. The default, and recommended, method is to output synthesized audio to <application>JACK</application>. This allows the greatest control over audio quality, and the greatest flexibility in terms of routing and multiplexing (for definition see <xref linkend="sect-Musicians_Guide-Vocabulary-Routing_and_Multiplexing" />), which allows you to simultaneously record the synthesized audio signal and listen to it.
</para>
<para>
- If you are having problems, you may wish to confirm that Qsynth is configured correctly to use JACK.
+ If you are having problems, you may wish to confirm that <application>Qsynth</application> is configured correctly to use <application>JACK</application>.
</para>
<procedure>
- <step><para>Open Qsynth's "Setup" window.</para></step>
+ <step><para>Open <application>Qsynth</application>'s "Setup" window.</para></step>
<step><para>Select the 'Audio' tab, and ensure that "Audio Driver" is set to "jack".</para></step>
- <step><para>You should also ensure that the other settings are correct - especially that the "sample rate" is set to the same sample rate as JACK (through QjackCtl).</para></step>
+ <step><para>You should also ensure that the other settings are correct - especially that the "sample rate" is set to the same sample rate as <application>JACK</application> (through <application>QjackCtl</application>).</para></step>
<step><para>The default settings for most things should work. If you changed a default setting, they are these:
<itemizedlist>
<listitem><para>Buffer Size: 1024</para></listitem>
@@ -209,12 +211,12 @@
<application>FluidSynth</application> will only produce sound as instructed by a connected (software- or hardware-based) MIDI device. If you are having problems configuring <application>FluidSynth</application> to accept MIDI input, verify the following options.
</para>
<procedure>
- <step><para>Open Qsynth's "Setup" window.</para></step>
+ <step><para>Open <application>Qsynth</application>'s "Setup" window.</para></step>
<step><para>The "Enable MIDI Input" setting must be enabled.</para></step>
<step><para>There are two settings for "MIDI Driver" that you would likely want.
<itemizedlist>
- <listitem><para>When set to "alsa_seq", the input will appear on QjackCtl's "ALSA" tab in the "Connect" window. This is useful if the MIDI generator device that you are using, such as a MIDI-enabled keyboard, is connected directly to ALSA.</para></listitem>
- <listitem><para>When set to "jack", the input will appear on QjackCtl's "MIDI" tab in the "Connect" window. This is useful if the MIDI generator device that you are using, such as Rosegarden, is connected directly to JACK.</para></listitem>
+ <listitem><para>When set to "alsa_seq", the input will appear on <application>QjackCtl</application>'s "ALSA" tab in the "Connect" window. This is useful if the MIDI generator device that you are using, such as a MIDI-enabled keyboard, is connected directly to ALSA.</para></listitem>
+ <listitem><para>When set to "jack", the input will appear on <application>QjackCtl</application>'s "MIDI" tab in the "Connect" window. This is useful if the MIDI generator device that you are using, such as <application>Rosegarden</application>, is connected directly to <application>JACK</application>.</para></listitem>
</itemizedlist>
</para></step>
<step><para>You can set the number of MIDI input channels provided by <application>FluidSynth</application>. Refer to <xref linkend="sect-Musicians_Guide-FluidSynth-Changing_Number_of_Input_Channels" /> below.</para></step>
@@ -232,12 +234,12 @@
</section>
<section id="sect-Musicians_Guide-FluidSynth-Assigning_Programs_to_Channels">
- <title>Assigning Programs to Channels with Qsynth</title>
+ <title>Assigning Programs to Channels with <application>Qsynth</application></title>
<para>
- The best way to do this is through your MIDI sequencer, like Qtractor or Rosegarden. If you are using an application which doesn't allow you to send program-change messages, or if you need to configure programs for another reason, you can follow these instructions.
+ The best way to do this is through your MIDI sequencer, like <application>Qtractor</application> or <application>Rosegarden</application>. If you are using an application which doesn't allow you to send program-change messages, or if you need to configure programs for another reason, you can follow these instructions.
</para>
<procedure>
- <step><para>In the main Qsynth window, click "Channels" to open the "Channels" window.</para></step>
+ <step><para>In the main <application>Qsynth</application> window, click "Channels" to open the "Channels" window.</para></step>
<step><para>In the Channels window, each channel will, by default, look like <programlisting><![CDATA[1 - - -]]></programlisting></para></step>
<step><para>To assign a program to a channel, click on the row of the channel that you want to assign.</para></step>
<step><para>Select the bank and program number that you want, using the name, SFID, and Soundfont columns to guide you.</para></step>
@@ -248,13 +250,13 @@
<section id="sect-Musicians_Guide-FluidSynth-Changing_Number_of_Input_Channels">
<title>Changing the Number of MIDI Input Channels</title>
<para>
- You can increase the number of MIDI input channels offered by <application>FluidSynth</application>. Although QSynth will let you set any number between 1 and 256, channels will be added and removed only in sets of 16. Qsynth will automatically create the lowest number of channels that will allow as many channels as you need. Each set of 16 channels will be indicated in JACK with an additional MIDI input device. The name of the device indicates which channels are listening: channels 1 through 16 listen to the device ending in 0; channels 17 through 32 listen to the device ending in 1; channels 33 through 58 listen to the device ending in 2; and so on.
+ You can increase the number of MIDI input channels offered by <application>FluidSynth</application>. Although <application>QSynth</application> will let you set any number between 1 and 256, channels will be added and removed only in sets of 16. <application>Qsynth</application> will automatically create the lowest number of channels that will allow as many channels as you need. Each set of 16 channels will be indicated in <application>JACK</application> with an additional MIDI input device. The name of the device indicates which channels are listening: channels 1 through 16 listen to the device ending in 0; channels 17 through 32 listen to the device ending in 1; channels 33 through 58 listen to the device ending in 2; and so on.
</para>
<para>
To change the number of MIDI input channels, follow these instructions.
</para>
<procedure>
- <step><para>Open Qsynth's "Setup" window.</para></step>
+ <step><para>Open the <application>Qsynth</application> "Setup" window.</para></step>
<step><para>The "Enable MIDI Input" setting must be enabled.</para></step>
<step><para>Input the number of channels that you wish to use, between 1 and 256.</para></step>
</procedure>
@@ -268,15 +270,15 @@
To save the settings for later:
</para>
<procedure>
- <step><para>Ensure that Qsynth is correctly configured, and working with the program assignments as desired.</para></step>
- <step><para>In Qsynth's "Channels" window, erase the contents of the "Preset Name" text field, and replace it with whatever name you would like.</para></step>
+ <step><para>Ensure that <application>Qsynth</application> is correctly configured, and working with the program assignments as desired.</para></step>
+ <step><para>In <application>Qsynth</application>'s "Channels" window, erase the contents of the "Preset Name" text field, and replace it with whatever name you would like.</para></step>
<step><para>Click "Save" to preserve the settings under that name.</para></step>
</procedure>
<para>
To restore settings from earlier:
</para>
<procedure>
- <step><para>Open Qsynth's "Channels" window.</para></step>
+ <step><para>Open <application>Qsynth</application>'s "Channels" window.</para></step>
<step><para>Search through the "Preset Name" drop-down box to find the name of the preset that you wish to restore.</para></step>
<step><para>Select it, and verify that the correct channel assignments were restored.</para></step>
</procedure>
@@ -284,14 +286,14 @@
</section>
<section id="sect-Musicians_Guide-FluidSynth-Reverb_and_Chorus">
- <title>Using Reverb and Chorus with Qsynth</title>
+ <title>Using Reverb and Chorus with <application>Qsynth</application></title>
<para>
- While "reverb" (meaning "reverberation") and "chorus" effects are not part of the General MIDI standard, they are offered by most MIDI synthesizers. <application>FluidSynth</application> is no exception, and the Qsynth interface provides a convenient and easy way to adjust settings of the reverb and chorus effect-generators. Experimentation is the only way to know whether you have chosen the right settings, and they will probably change depending on the music you are working on, and even during a piece. Most MIDI sequencers and players (including Qtractor and Rosegarden) allow you to send MIDI messages changing the reverb and chorus settings while a session is playing.
+ While "reverb" (meaning "reverberation") and "chorus" effects are not part of the General MIDI standard, they are offered by most MIDI synthesizers. <application>FluidSynth</application> is no exception, and the <application>Qsynth</application> interface provides a convenient and easy way to adjust settings of the reverb and chorus effect-generators. Experimentation is the only way to know whether you have chosen the right settings, and they will probably change depending on the music you are working on, and even during a piece. Most MIDI sequencers and players (including Qtractor and Rosegarden) allow you to send MIDI messages changing the reverb and chorus settings while a session is playing.
</para>
<para>
- The reverb and chorus effects can be turned off temporarily if you do not plan to use them. To do this in Qsynth, uncheck the "Active" check-box underneath the respective effect generator's settings dials.
+ The reverb and chorus effects can be turned off temporarily if you do not plan to use them. To do this in <application>Qsynth</application>, uncheck the "Active" check-box underneath the respective effect generator's settings dials.
</para><para>
- The '''reverb''' effect generator creates artificial reverberation (like an "echo," but more complex), which occurs naturally in almost all performing environments. The effect generator works by creating a virtual room, and pretending that the user is listening within it. These are the settings offered by Qsynth:
+ The <firstterm>reverb</firstterm> effect generator creates artificial reverberation (like an "echo," but more complex), which occurs naturally in almost all performing environments. The effect generator works by creating a virtual room, and pretending that the user is listening within it. These are the settings offered by <application>Qsynth</application>:
<itemizedlist>
<listitem><para>Room: Adjusts the size of the virtual room. Settings higher than 100 can cause a situation that escalates in volume to dangerously high levels, even with the lowest possible "level" settings. This is an interesting effect, but caution is advised so that listener do not incur accidental hearing damage. Remember also that the reverb effect can accumulate as time goes on, so it may even take many minutes for the volume level to build to a dangerously high level, depending on the settings.</para></listitem>
<listitem><para>Damp: Adjusts the amount of "sound damping" in the virtual room, affecting not only the time it takes for the sound to die, but the frequencies which are most affected. The greater the damping, the shorter the higher frequencies last.</para></listitem>
@@ -301,7 +303,7 @@
All of the settings interact in ways that make it difficult to describe any sort of recommended settings. Users are strongly encouraged to experiment with the various settings to find ones that suit their needs. A wide variety of listening environments can be simulated, and the settings required do not always reflect the most logical choice - it is possible to emulate a concert hall with a relatively small "room" setting, for example. Effective use of the reverb effect can greatly enhance the MIDI listening experience.
</para>
<para>
- The '''chorus''' effect generator creates the impression that more than one real-world instrument is playing each MIDI line. The effect generator works by slightly responding to each MIDI note several times, with slightly inaccuracies in pitch and time in each response. Although it may seem overly negative to say so, humans intuitively recognize that this inaccuracy is part of real-world, acoustic music, so the chorus effect helps to add a realistic sound to some performances. These are the settings offered by Qsynth:
+ The <firstterm>chorus</firstterm> effect generator creates the impression that more than one real-world instrument is playing each MIDI line. The effect generator works by slightly responding to each MIDI note several times, with slightly inaccuracies in pitch and time in each response. Although it may seem overly negative to say so, humans intuitively recognize that this inaccuracy is part of real-world, acoustic music, so the chorus effect helps to add a realistic sound to some performances. These are the settings offered by <application>Qsynth</application>:
<itemizedlist>
<listitem><para>N: Adjusts the number of effect "stages," which allows you to control the approximate number of discrete instruments perceived.</para></listitem>
<listitem><para>Level: Adjusts the volume level of the effect.</para></listitem>
@@ -312,24 +314,24 @@
</section>
<section id="sect-Musicians_Guide-FluidSynth-Multiple_Instances">
- <title>Multiple <application>FluidSynth</application> Instances with Qsynth</title>
+ <title>Multiple <application>FluidSynth</application> Instances with <application>Qsynth</application></title>
<para>
Rarely will you need more than one instance of <application>FluidSynth</application>, because QSynth/<application>FluidSynth</application> together offer up to 256 independent input channels, and the ability to control the reverb and chorus effects independently by channel. The most common use of multiple <application>FluidSynth</application> instances is if you want to use multiple MIDI instruments. In other words, if you want to use multiple SoundFonts at the same time, you will need to use one instance of <application>FluidSynth</application> for each SoundFont.
</para>
<para>
- Thankfully, Qsynth allows us to do this almost effortlessly! Each "instance" of <application>FluidSynth</application> is created and controlled by, in effect, running the <application>FluidSynth</application> synthesis application multiple times. The reality is that, since Qsynth controls the <application>FluidSynth</application> engine directly, it simply starts the synthesis engine directly, creating multiple instance of that engine. This is much more efficient than actually running Qsynth multiple time, or even than running <application>FluidSynth</application> directly from a terminal. Each such instance is represented in Qsynth by a "tab," displayed at the bottom of the Qsynth window.
+ Thankfully, <application>Qsynth</application> allows us to do this almost effortlessly! Each "instance" of <application>FluidSynth</application> is created and controlled by, in effect, running the <application>FluidSynth</application> synthesis application multiple times. The reality is that, since <application>Qsynth</application> controls the <application>FluidSynth</application> engine directly, it simply starts the synthesis engine directly, creating multiple instance of that engine. This is much more efficient than actually running <application>Qsynth</application> multiple time, or even than running <application>FluidSynth</application> directly from a terminal. Each such instance is represented in <application>Qsynth</application> by a "tab," displayed at the bottom of the <application>Qsynth</application> window.
</para>
<para>
To create an additional instance of <application>FluidSynth</application>:
</para>
<procedure>
- <step><para>Press the green "+" button in the bottom-left corner of Qsynth's main window</para></step>
+ <step><para>Press the green "+" button in the bottom-left corner of <application>Qsynth</application>'s main window</para></step>
<step><para>Adjust the settings as desired, by using the Setup window that pops up.</para></step>
<step><para>Press "OK" to start the additional instance.</para></step>
<step><para>To close an additional instance, use the red "X" near the lower-right corner.</para></step>
</procedure>
<para>
- Each instance of the <application>FluidSynth</application> engine has its own settings in the "Setup" window. Qsynth supports a theoretically unlimited number of <application>FluidSynth</application> instances, but your computer's memory will probably not allow many more than ten, depending on the SoundFonts used.
+ Each instance of the <application>FluidSynth</application> engine has its own settings in the "Setup" window. <application>Qsynth</application> supports a theoretically unlimited number of <application>FluidSynth</application> instances, but your computer's memory will probably not allow many more than ten, depending on the SoundFonts used.
</para>
</section>
diff --git a/en-US/LilyPond/LilyPond-counterpoint.xml b/en-US/LilyPond/LilyPond-counterpoint.xml
index d00e317..3c3d17d 100644
--- a/en-US/LilyPond/LilyPond-counterpoint.xml
+++ b/en-US/LilyPond/LilyPond-counterpoint.xml
@@ -52,7 +52,7 @@
<title>Inputting</title>
<procedure>
<step><para>Look over the template. It's not important to understand what any of this means, but it's good if you can figure it out.</para></step>
- <step><para>The piano's upper staff will contain the notes between the { and } following the " right = \relative c'' " portion</para></step>
+ <step><para>The piano's upper staff will contain the notes between the <literal>{</literal> and <literal>}</literal> following the <code>right = \relative c''</code> portion</para></step>
<step><para>The piano's lower ... left</para></step>
<step><para>The figured bass will say what you put in figBass</para></step>
<step><para>start with the piano's upper part. Input "f1 g a f d e f c a f g f" (explain)</para></step>
diff --git a/en-US/LilyPond/LilyPond-orchestra.xml b/en-US/LilyPond/LilyPond-orchestra.xml
index fa728f8..5559b55 100644
--- a/en-US/LilyPond/LilyPond-orchestra.xml
+++ b/en-US/LilyPond/LilyPond-orchestra.xml
@@ -183,7 +183,7 @@
<step><para>When you preview this, you'll notice that the result is thoroughly underwhelming. It looks quite unlike a "forte" marking, and people reading the score would probably be confused, if just momentarily.</para></step>
<step><para>Thankfully, LilyPond provides a very easy and elegant way to input well-formatted dynamic markings. Change the eighth-rest to this: <code>r8\f <replaceable>and so on</replaceable></code></para></step>
<step><para>When you preview this, you will see that it now looks exactly like a typical "forte" marking. Not all dynamic markings have these short-forms, but most do.</para></step>
- <step><para>The "a 2" marking, meaning "to be played by two players," does need the text-in-quotes format, however. Put that marking ''above'' the d following the eighth rest.</para></step>
+ <step><para>The "a 2" marking, meaning "to be played by two players," does need the text-in-quotes format, however. Put that marking <emphasis>above</emphasis> the d following the eighth rest.</para></step>
<step><para>Those two measures should now look like this:
<literallayout>r8\f d-.^"a 2" g-. bes-. d-. bes-. |
g8( cis) cis4 r |</literallayout>
@@ -197,7 +197,7 @@
<itemizedlist>
<listitem><para>You will need to adjust the range of the flute and oboe, to read <code>flute = \relative c'''</code> and <code>oboeI = \relative c'''</code></para></listitem>
<listitem><para>You may want to use [ and ] to control eighth-note beaming in the Oboe I and Flauto parts. You may not</para></listitem>
- <listitem><para>The Flauto will need more multi-measure rests with R, ''after'' some of the notes are inputted.</para></listitem>
+ <listitem><para>The Flauto will need more multi-measure rests with R, <emphasis>after</emphasis> some of the notes are inputted.</para></listitem>
<listitem><para>All of the parts will end with the same three-quarter-note-rests-with-fermata measure.</para></listitem>
</itemizedlist>
</para></step>
@@ -236,7 +236,7 @@
<listitem><para>Grace Notes: These take up no logical time, and are smaller than ordinary notes. Any notes appearing <code>\grace { in here }</code> would be considered grace notes.</para></listitem>
<listitem><para>Crescendo and Diminuendo Markings:
<itemizedlist>
- <listitem><para>These are added like other dynamic markings, attached with a backslash to the note where they begin. A crescendo is triggered with literal><![CDATA[\<]]></literal> and a diminuendo with <literal><![CDATA[\>]]></literal>.</para></listitem>
+ <listitem><para>These are added like other dynamic markings, attached with a backslash to the note where they begin. A crescendo is triggered with <literal><![CDATA[\<]]></literal> and a diminuendo with <literal><![CDATA[\>]]></literal>.</para></listitem>
<listitem><para>The left-most point of the marking (its beginning) is indicated by where you put <literal><![CDATA[\<]]></literal> or <literal><![CDATA[\>]]></literal></para></listitem>
<listitem><para>The right-most (or end-)point is indicated by either another dynamic marking of any sort, or the special cancellation character <literal><![CDATA[\!]]></literal></para></listitem>
</itemizedlist></para></listitem>
diff --git a/en-US/LilyPond/LilyPond-piano.xml b/en-US/LilyPond/LilyPond-piano.xml
index 1a2227e..261feb0 100644
--- a/en-US/LilyPond/LilyPond-piano.xml
+++ b/en-US/LilyPond/LilyPond-piano.xml
@@ -7,10 +7,10 @@
<section id="sect-Musicians_Guide-LilyPond-Piano">
<title>Working on a Piano Score (Tutorial)</title>
<para>
- Scenario: At a used music store, you encounter a 60-year-old, hand-engraved copy of a Schubert ''Impromptu'', but it's been badly damaged by a flood. The store's owner says that, if you can use the score, you can keep it for free. The score is barely legible, so you decide to prepare a copy with a computer notation program.
+ Scenario: At a used music store, you encounter a 60-year-old, hand-engraved copy of a Schubert "Impromptu," but it's been badly damaged by a flood. The store's owner says that, if you can use the score, you can keep it for free. The score is barely legible, so you decide to prepare a copy with a computer notation program.
</para>
<para>
- I'm using Schubert's ''Impromptu'' Op.90 (D.899) Nr.4, in A-flat major. Published by Edition Peters: 10463, ed. Walter Niemann. We'll be setting the A section (from the beginning to the Trio).
+ I'm using Schubert's "Impromptu" Op.90 (D.899) Nr.4, in A-flat major. Published by Edition Peters: 10463, edited by Walter Niemann. We'll be setting the "A" section (from the beginning to the "Trio").
</para>
<para>
When following this tutorial, it is recommended that the reader follows along, creating their replica of this tutorial's PDF.
@@ -19,8 +19,8 @@
<section id="sect-Musicians_Guide-LilyPond-Piano-Tutorial_Files">
<title>Files for the Tutorial</title>
<para>
- You do not need the LilyPond input file to do the tutorial. You should use the input file if you encounter problems, and to compare your completion. You do need the PDF output file to do the tutorial.
- <citetitle>LilyPond Input File</citetitle> at <ulink url="https://fedoraproject.org/wiki/User:Crantila/FSC/Typesetting/LilyPond/Piano" />.
+ You do not need the <application>LilyPond</application> input file to do the tutorial. You should use the input file if you encounter problems, and to compare your completion. You do need the PDF output file to do the tutorial.
+ <citetitle><application>LilyPond</application> Input File</citetitle> at <ulink url="https://fedoraproject.org/wiki/User:Crantila/FSC/Typesetting/LilyPond/Piano" />.
<citetitle>PDF Output File</citetitle> at <ulink url="https://fedoraproject.org/wiki/File:FSC-piano.pdf" />.
</para>
</section>
@@ -29,7 +29,7 @@
<title>Starting the Score</title>
<procedure>
<step><para>Open Frescobaldi with a new document.</para></step>
- <step><para>Start the "Setup New Score" tool, by clicking 'LilyPond > Setup New Score' in the menu.</para></step>
+ <step><para>Start the "Setup New Score" tool, by clicking '<application>LilyPond</application> > Setup New Score' in the menu.</para></step>
<step><para>Fill in the following fields on the "Titles and Headers" tab:
<itemizedlist>
<listitem><para>Title: Impromptu</para></listitem>
@@ -61,7 +61,7 @@
<title>Adjusting Frescobaldi's Output</title>
<!-- This section is shared with the orchestral example -->
<para>
- These steps are useful in establishing a consistent input style for LilyPond. The things suggested here are also useful for getting used to working with large scores, which can be a challenge in any text editor. Thankfully, careful (and consistent!) code organization goes a long way in helping you to quickly find your way around your files. Setting up files the right way to begin with makes this much easier in the end.
+ These steps are useful in establishing a consistent input style for <application>LilyPond</application>. The things suggested here are also useful for getting used to working with large scores, which can be a challenge in any text editor. Thankfully, careful (and consistent!) code organization goes a long way in helping you to quickly find your way around your files. Setting up files the right way to begin with makes this much easier in the end.
</para>
<para>
When you first setup the score, Frescobaldi will have created many sections for you by default. The program avoids making too many stylistic choices for you, which allows you to create your own style. It also sets up the default sections in a logical way:
@@ -72,7 +72,7 @@
<listitem><para>individual parts</para></listitem>
<listitem><para>score formatting</para></listitem>
</orderedlist>
- The specific ordering will become more obvious to you as you get used to LilyPond.
+ The specific ordering will become more obvious to you as you get used to <application>LilyPond</application>.
</para>
<para>
Here are some of the things that I do before inputting notes:
@@ -105,7 +105,7 @@
<section id="sect-Musicians_Guide-LilyPond-Piano-Inputting">
<title>Inputting</title>
<para>
- Piano scores present some unique challenges with LilyPond, but they're easy to overcome with some careful thought. This tutorial will avoid step-by-step instructions on how to input particular notes, instead focussing on those unique piano challenges presented in this particular composition. The LilyPond "Notation Reference" provides a section dedicated to keyboard and piano music. Most of the situations described there are not present or discussed in this score, which gives this tutorial unique material.
+ Piano scores present some unique challenges with <application>LilyPond</application>, but they're easy to overcome with some careful thought. This tutorial will avoid step-by-step instructions on how to input particular notes, instead focussing on those unique piano challenges presented in this particular composition. The <application>LilyPond</application> "Notation Reference" provides a section dedicated to keyboard and piano music. Most of the situations described there are not present or discussed in this score, which gives this tutorial unique material.
</para>
<section id="sect-Musicians_Guide-LilyPond-Piano-Inputting-Order_of_Inputting">
<title>Order of Inputting</title>
@@ -135,19 +135,19 @@
There are two ways to input chords, but one will be used much more often.
</para>
<para>
- This style of chord notation is more common: <literal><![CDATA[<as ces>4-_]]></literal> Notice how only the pitches are notated inside the <literal><![CDATA[< >]]></literal> brackets, and everything else attached to the end. There is one exception to this: fingering should be indicated on the pitch associated with that finger: <literal><![CDATA[<as-1 ces-3>4-_]]></literal> Not only does this help you to sort out what was probably intended, but it allows LilyPond to stack the fingering in the right order. When using "relative" entry mode, it is the lowest note of the chord that is taken into consideration when placing the next note.
+ This style of chord notation is more common: <literal><![CDATA[<as ces>4-_]]></literal> Notice how only the pitches are notated inside the <literal><![CDATA[< >]]></literal> brackets, and everything else attached to the end. There is one exception to this: fingering should be indicated on the pitch associated with that finger: <literal><![CDATA[<as-1 ces-3>4-_]]></literal> Not only does this help you to sort out what was probably intended, but it allows <application>LilyPond</application> to stack the fingering in the right order. When using "relative" entry mode, it is the lowest note of the chord that is taken into consideration when placing the next note.
</para>
<para>
- This style of chord notation is less common: <literal><![CDATA[<<as4-> ces>>]]></literal> Notice how everything must be notated inside the <literal><![CDATA[<< >>]]></literal> brackets. This can make it more difficult to read the chord in the source file, but it also allows much greater flexibility: only some chord members can have ties; certain chord members can last for longer than others; certain chord members can "break out" into or out of polyphonic passages. This notation is rarely ''needed'', but you may be inclined to over-use it if you are trying to exactly copy the look of a hand-engraved score. Like the "times" command for tuplets, this is one of LilyPond's deceptively powerful techniques. When using "relative" entry mode, it is the last note of the chord that is taken into consideration when placing the next note.
+ This style of chord notation is less common: <literal><![CDATA[<<as4-> ces>>]]></literal> Notice how everything must be notated inside the <literal><![CDATA[<< >>]]></literal> brackets. This can make it more difficult to read the chord in the source file, but it also allows much greater flexibility: only some chord members can have ties; certain chord members can last for longer than others; certain chord members can "break out" into or out of polyphonic passages. This notation is rarely <emphasis>needed</emphasis>, but you may be inclined to over-use it if you are trying to exactly copy the look of a hand-engraved score. Like the "times" command for tuplets, this is one of <application>LilyPond</application>'s deceptively powerful techniques. When using "relative" entry mode, it is the last note of the chord that is taken into consideration when placing the next note.
</para>
</section>
<section id="sect-Musicians_Guide-LilyPond-Piano-Inputting-Fingering">
<title>Fingering</title>
<para>
- LilyPond allows you to indicate fingering by attaching the digit number to a note as an articulation mark: <code>a16-5</code> will show a "5" as a fingering mark. As with all other articulation marks indicated in this way, you can use <literal>^</literal> or <literal>_</literal> to instruct LilyPond to put the mark above or below the note, respectively. It is usually better to let LilyPond decide for itself by using a <literal>-</literal>.
+ <application>LilyPond</application> allows you to indicate fingering by attaching the digit number to a note as an articulation mark: <code>a16-5</code> will show a "5" as a fingering mark. As with all other articulation marks indicated in this way, you can use <literal>^</literal> or <literal>_</literal> to instruct <application>LilyPond</application> to put the mark above or below the note, respectively. It is usually better to let <application>LilyPond</application> decide for itself by using a <literal>-</literal>.
</para>
<para>
- When entering chords, it is recommended that you enter the fingering with the note to which it is attached, like <literal><![CDATA[<as-1 ces-4>4-_]]></literal>. It is possible to enter this as <literal><![CDATA[<as ces>4-1-4->]]></literal>, but this not only looks confusing, it may confuse LilyPond as to which digit is intended for which note.
+ When entering chords, it is recommended that you enter the fingering with the note to which it is attached, like <literal><![CDATA[<as-1 ces-4>4-_]]></literal>. It is possible to enter this as <literal><![CDATA[<as ces>4-1-4->]]></literal>, but this not only looks confusing, it may confuse <application>LilyPond</application> as to which digit is intended for which note.
</para>
<para>
Because the extra digits look like they indicate note-lengths, it is recommended to mark them consistently. For this same reason, it is also recommended that fingering marks be added to source files only after the pitch and rhythm have been double-checked. The source file included with this tutorial puts fingering marks after any other articulation and length marking.
@@ -157,29 +157,29 @@
<title>Cautionary Accidentals</title>
<para>
Musical Definition:
- This score makes some use of ''cautionary accidentals''. These are accidentals which don't change the pitches to be played, but rather are used as a precaution against forgetting that they are there. This usually happens when an accidental in the written key signature is changed for a significant number of measures, and then suddenly changes back. The cautionary accidental would be applied when the standard key signature returns, to remind the musician of the key signature.
+ This score makes some use of <firstterm>cautionary accidentals</firstterm>. These are accidentals which don't change the pitches to be played, but rather are used as a precaution against forgetting that they are there. This usually happens when an accidental in the written key signature is changed for a significant number of measures, and then suddenly changes back. The cautionary accidental would be applied when the standard key signature returns, to remind the musician of the key signature.
</para>
<para>
- LilyPond Notation:
- These are notated in LilyPond with an exclamation mark placed before the note-value: <code>ces!16</code>
+ <application>LilyPond</application> Notation:
+ These are notated in <application>LilyPond</application> with an exclamation mark placed before the note-value: <code>ces!16</code>
</para>
</section>
<section id="sect-Musicians_Guide-LilyPond-Piano-Inputting-Changing_the_Style_of_Crescendo">
<title>Changing the Style of Crescendo</title>
<para>
- Sometimes the composer or editor prefers to use the words "''crescendo''" or its abbreviation, "''cresc.''", instead of the <literal><![CDATA[\<]]></literal> style of crescendo. In LilyPond these are handled by the same source-file notation (<literal><![CDATA[\<]]></literal> to start and <code>\!</code> to end explicitly). However, if you want to use text and a "spanner" (dotted or dashed line, for example) instead of the < sign, you need to tell LilyPond. This can be accomplished with the following command: <code>\crescTextCresc</code>.
+ Sometimes the composer or editor prefers to use the words <foreignphrase>crescendo</foreignphrase> or its abbreviation, <foreignphrase>cresc.</foreignphrase>, instead of the <literal><![CDATA[\<]]></literal> style of crescendo. In <application>LilyPond</application> these are handled by the same source-file notation (<literal><![CDATA[\<]]></literal> to start and <code>\!</code> to end explicitly). However, if you want to use text and a "spanner" (dotted or dashed line, for example) instead of the < sign, you need to tell <application>LilyPond</application>. This can be accomplished with the following command: <code>\crescTextCresc</code>.
</para>
<para>
- After changing to this style of ''crescendo'', you can revert to the standard < style with the following command: <code>\crescHairpin</code>.
+ After changing to this style of <foreignphrase>crescendo</foreignphrase>, you can revert to the standard < style with the following command: <literal>\crescHairpin</literal>.
</para>
<para>
- The <code>\dimTextDim</code> and <code>\dimHairpin</code> commands do the same for a ''diminuendo''.
+ The <literal>\dimTextDim</literal> and <literal>\dimHairpin</literal> commands do the same for a <foreignphrase>diminuendo</foreignphrase>.
</para>
</section>
<section id="sect-Musicians_Guide-LilyPond-Piano-Inputting-Polyphonic_Sections_of_Homophonic_Music">
<title>Polyphonic Sections of Homophonic Music</title>
<para>
- Sometimes, especially in piano music, a passage of some measures will require polyphonic (multi-Voice) notation in LilyPond, even though most of the music does not. In this case, you would use the following format:
+ Sometimes, especially in piano music, a passage of some measures will require polyphonic (multi-Voice) notation in <application>LilyPond</application>, even though most of the music does not. In this case, you would use the following format:
<literal><![CDATA[
<<
{
@@ -193,7 +193,7 @@
This is used a few times in both hands in the example score file.
</para>
<para>
- When writing these sections in "relative" entry mode, it is a good idea to use the "octave-check" mechanism, at least at the beginning of the lower voice. This is because, when judging the relative starting pitch of the first note of the lower voice, LilyPond judges from the last note of the upper voice - ''not'' the last note before the polyphonic section began.
+ When writing these sections in "relative" entry mode, it is a good idea to use the "octave-check" mechanism, at least at the beginning of the lower voice. This is because, when judging the relative starting pitch of the first note of the lower voice, <application>LilyPond</application> judges from the last note of the upper voice - <emphasis>not</emphasis> the last note before the polyphonic section began.
</para>
</section>
<section id="sect-Musicians_Guide-LilyPond-Piano-Inputting-Octave_Change_Spanners">
@@ -203,29 +203,29 @@
In order to most conveniently notate over large ranges, composers and editors sometimes use text spanners to indicate that a passage should be played one or two octaves higher or lower than written. This allows the notes to stay mostly within the staff lines, thereby decreasing the number of ledger lines required.
</para>
<para>
- LilyPond Notation:
+ <application>LilyPond</application> Notation:
The <code>\ottava</code> command is used to notate all five states of transposition:
<itemizedlist>
<listitem><para>15va (play two octaves higher than written) is engaged with <code>\ottava #2</code></para></listitem>
<listitem><para>8va (play one octave higher than written) is engaged with <code>\ottava #1</code></para></listitem>
- <listitem><para>''loco'' (play in the octave written) is engaged with <code>\ottava #0</code>, which also cancels another sign.</para></listitem>
+ <listitem><para><foreignphrase>loco</foreignphrase> (play in the octave written) is engaged with <code>\ottava #0</code>, which also cancels another sign.</para></listitem>
<listitem><para>8vb (play one octave lower than written) is engaged with <code>\ottava #-1</code></para></listitem>
<listitem><para>15vb (play two octaves lower than written) is engaged with <code>\ottava #-2</code></para></listitem>
</itemizedlist>
</para>
</section>
- </section> <!-- Ends "Inputting" Section --> <!-- LilyPond-Piano-Inputting- -->
+ </section> <!-- Ends "Inputting" Section --> <!-- <application>LilyPond</application>-Piano-Inputting- -->
<section id="sect-Musicians_Guide-LilyPond-Piano-Troubleshooting_Errors">
<title>Troubleshooting Errors</title>
<para>
- It can be difficult to troubleshoot inputting errors, especially when you find them days or weeks after originally inputting that section of a score. The best way to fix errors is to input scores in a way that doesn't allow them in the first place. As they say, "an ounce of prevention is worth a pound of cure," which means "if you input your LilyPond files carefully, then you will encounter fewer problems." Such practices as proper spacing, and regular use of the octave- and bar-check features will deal with many common problems.
+ It can be difficult to troubleshoot inputting errors, especially when you find them days or weeks after originally inputting that section of a score. The best way to fix errors is to input scores in a way that doesn't allow them in the first place. As they say, "an ounce of prevention is worth a pound of cure," which means "if you input your <application>LilyPond</application> files carefully, then you will encounter fewer problems." Such practices as proper spacing, and regular use of the octave- and bar-check features will deal with many common problems.
</para>
<para>
However, when searching for an error in your score, Frescobaldi does offer some features to help you find it:
<itemizedlist>
<listitem><para>If you have written something in the text-input window that is obviously incorrect, then Frescobaldi will sometimes catch your mistake and underline and highlight the erroneous code in red. This is most useful for catching typographical errors ("typos").</para></listitem>
- <listitem><para>If LilyPond encounters a processing error, it will show up in the "LilyPond Log" window below the text-input window. You can click on the blue, underlined text to move the text-selection caret to the error.</para></listitem>
+ <listitem><para>If <application>LilyPond</application> encounters a processing error, it will show up in the "<application>LilyPond</application> Log" window below the text-input window. You can click on the blue, underlined text to move the text-selection caret to the error.</para></listitem>
<listitem><para>If you can see an error in the PDF preview, but you can't find it in the source file, you can click on the problematic note or object in the PDF preview, and Frescobaldi will automatically move the text-selection caret to that object.</para></listitem>
</itemizedlist>
</para>
@@ -234,10 +234,10 @@
<section id="sect-Musicians_Guide-LilyPond-Piano-Formatting">
<title>Formatting the Score (Piano Dynamics)</title>
<para>
- Keyboard instruments use a unique notation when it comes to dynamics. Most instruments use only one staff per player, so the dynamics are, by convention, notated underneath that staff. Keyboard instruments usually use two staves (organs and complex piano music may use three). Because the dynamics are usually meant to apply to both staves, they are usually notated between the two staves. This is similar to notation beneath the upper staff, but in truth, piano dynamics tend to be placed in the middle between the staves - entering the dynamics as belonging to the upper staff, in LilyPond, will not produce that effect.
+ Keyboard instruments use a unique notation when it comes to dynamics. Most instruments use only one staff per player, so the dynamics are, by convention, notated underneath that staff. Keyboard instruments usually use two staves (organs and complex piano music may use three). Because the dynamics are usually meant to apply to both staves, they are usually notated between the two staves. This is similar to notation beneath the upper staff, but in truth, piano dynamics tend to be placed in the middle between the staves - entering the dynamics as belonging to the upper staff, in <application>LilyPond</application>, will not produce that effect.
</para>
<para>
- There is a way to notate dynamics between two staves in LilyPond, and it involves a little bit of thought to get it right. It also requires the addition of a significant number of commands, and the creation of a new context.
+ There is a way to notate dynamics between two staves in <application>LilyPond</application>, and it involves a little bit of thought to get it right. It also requires the addition of a significant number of commands, and the creation of a new context.
</para>
<para>
This process looks difficult, and may seem daunting. It's not necessary to understand all of the commands in the "PianoDynamics" Context in order to use the context, so there is no need to worry!
@@ -313,12 +313,12 @@ dynamics =
Now you can input the dynamic markings. These are inputted with a special note called a "spacer," that uses the letter "s" rather than a note name. You can also use rests (both partial- and multi-measure, r and R), but dynamic markings cannot be assigned to them.
</para>
<para>
- For example, if you want a ''piano'' marking on the first beat, and a ''diminuendo'' from the third to the fourth beat, you could write this: <code>s4\p r s\> s\!</code>, or this: <code>s2\p s4\> s\!</code>
+ For example, if you want a <foreignphrase>piano</foreignphrase> marking on the first beat, and a <foreignphrase>diminuendo</foreignphrase> from the third to the fourth beat, you could write this: <code>s4\p r s\> s\!</code>, or this: <code>s2\p s4\> s\!</code>
</para>
<para>
That's all there is to it! Think of the dynamics part as an invisible, pitch-free line between the two staves, for the sole purpose of dynamics (and other expression markings).
</para>
</section>
- </section> <!-- Ends "Formatting the Score (Piano Dynamics)" Section --> <!-- LilyPond-Piano-Formatting- -->
+ </section> <!-- Ends "Formatting the Score (Piano Dynamics)" Section --> <!-- <application>LilyPond</application>-Piano-Formatting- -->
</section>
diff --git a/en-US/LilyPond/LilyPond-syntax.xml b/en-US/LilyPond/LilyPond-syntax.xml
index b060a11..21fd85f 100644
--- a/en-US/LilyPond/LilyPond-syntax.xml
+++ b/en-US/LilyPond/LilyPond-syntax.xml
@@ -41,7 +41,7 @@
<section id="sect-Musicians_Guide-LilyPond-Syntax-Numbers_Are_Durations">
<title>Numbers Are Durations</title>
<para>
- A number appended to a letter is understood by <application>LilyPond</application> to indicate that particular note's note-value. A ''whole note'' is indicated with a 1, and all other durations are indicated with a number representing the fraction of a whole note that they occupy: ''half notes'' are 2 (like "1/'''2''' note"); ''quarter notes'' are 4 (like "1/'''4''' note"); ''eighth notes'' are 8 (like "1/'''8''' note") and so on.
+ A number appended to a letter is understood by <application>LilyPond</application> to indicate that particular note's note-value. A whole note is indicated with a 1, and all other durations are indicated with a number representing the fraction of a whole note that they occupy: half notes are 2 (like "1/2 note"); quarter notes are 4 (like "1/4 note"); eighth notes are 8 (like "1/8 note") and so on.
</para>
<para>
To add a "dot" to a note (thereby increasing its length by one half), you simply include a period after the number. For example, <literal>e4.</literal> means "dotted quarter note on E."
@@ -79,8 +79,8 @@
There are three position indicators:
<itemizedlist>
<listitem><para><literal>-</literal> which means to put the articulation mark wherever <application>LilyPond</application> thinks it makes sense</para></listitem>
- <listitem><para><literal>_</literal> which means to put the articulation mark ''below'' the note-head</para></listitem>
- <listitem><para><literal>^</literal> which means to put the articulation mark ''above'' the note-head</para></listitem>
+ <listitem><para><literal>_</literal> which means to put the articulation mark <emphasis>below</emphasis> the note-head</para></listitem>
+ <listitem><para><literal>^</literal> which means to put the articulation mark <emphasis>above</emphasis> the note-head</para></listitem>
</itemizedlist>
These position indicators will sometimes result in notes like: <code>g4--</code>, <code>g4__</code>, and <code>g4^^</code>, but although this may look incorrect, it is perfectly acceptable.
</para>
@@ -115,7 +115,7 @@
There are a wide variety of commands available in <application>LilyPond</application>, some of them quite simple, and other quite complex. They all begin with a backslash, followed by the name of the command, and subsequent "arguments" that give the command further information about what you want it to do. Just like using a letter to indicate a note, commands are simply another way for you to tell <application>LilyPond</application> how you want your score to be rendered.
</para>
<para>
- For example, <code>\time 2/4</code> and <code>\clef bass</code> are two commands that you are likely to use quite often. They happen to do precisely what it seems like they should: ''time'' changes the time signature and metre, and ''clef'' changes the clef. they belong to differen contexts (''time'' applies for the whole Score, but ''clef'' for only one Staff).
+ For example, <code>\time 2/4</code> and <code>\clef bass</code> are two commands that you are likely to use quite often. They happen to do precisely what it seems like they should: <literal>\time</literal> changes the time signature and metre, and <literal>\clef</literal> changes the clef. they belong to differen contexts (<literal>\time</literal> applies for the whole Score, but <literal>\clef</literal> for only one Staff).
</para>
<para>
It can take some time to remember even these basic commands and the way you should format their input, and this is where <application>Frescobaldi</application>'s built-in documentation viewer can help out. All of the official <application>LilyPond</application> documentation is made available in <application>Frescobaldi</application>, which makes it easy for you to view the documentation and make changes to your score in the same window of the same application.
diff --git a/en-US/LilyPond/LilyPond.xml b/en-US/LilyPond/LilyPond.xml
index 526401f..16a21e4 100644
--- a/en-US/LilyPond/LilyPond.xml
+++ b/en-US/LilyPond/LilyPond.xml
@@ -10,7 +10,7 @@
<application>LilyPond</application> is a notation engraving program, with a focus on creating a visually appealing product. <application>LilyPond</application> is text-based, and allows you to focus on the (semantic?) content of your musical scores, rather than on their visual appearance. Conventional commercial notation engraving programs allow users to edit the score visually. While this approach has its benefits, especially because it's very easy to see exactly what the printed score will look like, it also has disadvantages - chief among these is the fact that users of those programs are constantly worrying about what their score looks like.
</para>
<para>
- This is where <application>LilyPond</application> comes in - users don't need to worry about how their score will work, because they know that the expertly-crafted methods of <application>LilyPond</application> will automatically configure the objects on the score so that they look good, and are easy to read. <application>LilyPond</application>'s users focus on ''what'' needs to be displayed, rather than on ''how'' it is going to be displayed.
+ This is where <application>LilyPond</application> comes in - users don't need to worry about how their score will work, because they know that the expertly-crafted methods of <application>LilyPond</application> will automatically configure the objects on the score so that they look good, and are easy to read. <application>LilyPond</application>'s users focus on <emphasis>what</emphasis> needs to be displayed, rather than on <emphasis>how</emphasis> it is going to be displayed.
</para>
<para>
As with any particular approach, the <application>LilyPond</application> approach is not for everybody. However, once you have become accustomed to working with the software, and once you have learned methods to help deal with problems and organize your scores' source-files, you will probably realize that <application>LilyPond</application> is both much faster, and much more flexible, than traditional, commercially-available music engraving programs.
diff --git a/en-US/Planet_CCRMA_at_Home.xml b/en-US/Planet_CCRMA_at_Home.xml
index fc5f74a..2df0e61 100644
--- a/en-US/Planet_CCRMA_at_Home.xml
+++ b/en-US/Planet_CCRMA_at_Home.xml
@@ -50,7 +50,7 @@
<section id="sect-Musicians_Guide-CCRMA_Security_and_Stability">
<title>Security and Stability</title>
<para>
- The biggest reason that you should avoid installing the Planet CCRMA at Home repository unless you ''need'' its software is security. There are two main security issues with using the Planet CCRMA repositories:
+ The biggest reason that you should avoid installing the Planet CCRMA at Home repository unless you <emphasis>need</emphasis> its software is security. There are two main security issues with using the Planet CCRMA repositories:
<orderedlist>
<listitem><para>Planet CCRMA is intended for specialized audio workstations. The software is packaged in such a way that creates potential (and unknown) security threats caused by the optimizations necessary to prepare a computer system for use in audio work. Furthermore, these optimizations may reveal software bugs present in non-Planet CCRMA software, and allow them to do more damage than on a non-optimized system. Finally, a computer system's "stability" (its ability to run without trouble) may be compromised by audio optimizations. Regular desktop applications may perform less well on audio-optimized systems, if the optimization process unintentionally un-optimized some other process.</para></listitem>
<listitem><para>CCRMA is not a large, Linux-focussed organization. It is an academic organization, and its primary intention with the Planet CCRMA at Home repository is to allow anybody with a computer to do the same kind of work that they do. The Fedora Project is a relatively large organization, backed by one of the world's largest commercial Linux providers, which is focussed on creating a stable and secure operating system for daily use. Furthermore, thousands of people around the world are working for the Fedora Project or its corporate sponsor, and it is their responsibility to proactively solve problems. CCRMA has the same responsibility, but they do not have the dedicated resources of the Fedora Project, it would be naive(???) to think that they would be capable of providing the same level of support.</para></listitem>
diff --git a/en-US/Qtractor.xml b/en-US/Qtractor.xml
index 90390a0..ddaf624 100644
--- a/en-US/Qtractor.xml
+++ b/en-US/Qtractor.xml
@@ -64,10 +64,10 @@
<title>Audio Options</title>
<!-- "Options Window: Audio Tab" -->
<para>
- The ''Capture/Export'' setting allows you to choose the format in which Qtractor stores its audio clips when recorded or exported. You will be able to choose a file type, such as "WAV Microsoft" for standard ".wav" files, "AIFF Apple-SGI" for standard ".aiff" files, or the preferable "FLAC Lossless Audio Codec," format. FLAC is an open-source, lossless, compressed format for storing audio signals and metadata. See the <citetitle>FLAC Website</citetitle> <ulink url="http://flac.sourceforge.net/" /> for more information. You will also be asked to select a quality setting for lossy compressed formats, or a sample format for all lossless formats. If you do not know which sample format to choose, then "Signed 16-Bit" is a good choice for almost all uses, and will provide you with CD-quality audio. Most non-speciality hardware is incapable of making good use of higher sample formats. See <xref linkend="sect-Musicians_Guide-Sample_Rate_and_Sample_Format" /> for more inf
ormation about sample formats.
+ The "Capture/Export" setting allows you to choose the format in which Qtractor stores its audio clips when recorded or exported. You will be able to choose a file type, such as "WAV Microsoft" for standard ".wav" files, "AIFF Apple-SGI" for standard ".aiff" files, or the preferable "FLAC Lossless Audio Codec," format. FLAC is an open-source, lossless, compressed format for storing audio signals and metadata. See the <citetitle>FLAC Website</citetitle> <ulink url="http://flac.sourceforge.net/" /> for more information. You will also be asked to select a quality setting for lossy compressed formats, or a sample format for all lossless formats. If you do not know which sample format to choose, then "Signed 16-Bit" is a good choice for almost all uses, and will provide you with CD-quality audio. Most non-speciality hardware is incapable of making good use of higher sample formats. See <xref linkend="sect-Musicians_Guide-Sample_Rate_and_Sample_Format" /> for more infor
mation about sample formats.
</para>
<para>
- Setting the ''Transport mode'' will allow you to adjust the behaviour of the transport.
+ Setting the "Transport mode" will allow you to adjust the behaviour of the transport.
<itemizedlist>
<listitem><para>None : allows Qtractor's transport to operate independently</para></listitem>
<listitem><para>Slave : allows Qtractor's transport to accept instructions sent by JACK's transport, which can be controlled by QjackCtl or another application.</para></listitem>
@@ -77,7 +77,7 @@
If you are using Qtractor alone, or if you don't know which to choose, then "None" is a good choice. This setting can be adjusted at any time, if you later decide to link the transport in multiple applications.
</para>
<para>
- The ''Metronome'' section allows you to use a (short) audio file as the metronome sound, rather than the standard, MIDI-based metronome. You can choose the same file for "beat," and "bar," if you prefer. The ''Dedicated audio metronome outputs'' option will output the audio metronome's signal through separate outputs in JACK. This is Ardour's default behaviour.
+ The "Metronome" section allows you to use a (short) audio file as the metronome sound, rather than the standard, MIDI-based metronome. You can choose the same file for "beat," and "bar," if you prefer. The "Dedicated audio metronome outputs" option outputs the audio metronome's signal through separate outputs in JACK. This is Ardour's default behaviour.
</para>
</section>
<section id="sect-Musicians_Guide-Qtractor-Configuration-MIDI_Tab">
@@ -87,14 +87,14 @@
Adjusting the "File format" allows you to change how MIDI clips are stored. You will not need to adjust this unless required by an external application. Refer to <citetitle>Musical Instrument Digital Interface: Standard MIDI (.mid or .smf) (Wikipedia)</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Musical_Instrument_Digital_Interface#Standard_MIDI_.28.mid_or_.smf.29" /> for more information about file types.
</para>
<para>
- "MMC" stands for "MIDI Machine Control," and it allows multiple MIDI-connected devices to interact and control each other. Setting the ''Transport mode'' to a setting other than "None" allows it be controlled by MMC messages.
+ "MMC" stands for "MIDI Machine Control," and it allows multiple MIDI-connected devices to interact and control each other. Setting the "Transport mode" to a setting other than "None" allows it be controlled by MMC messages.
<itemizedlist>
<listitem><para>None : will have Qtractor ignore incoming MMC messages, and not provide outgoing MMC messages</para></listitem>
<listitem><para>Input : will have Qtractor follow incoming MMC instructions, but not provide outgoing MMC messages</para></listitem>
<listitem><para>Output : will have Qtractor ignore incoming MMS messages, but provide outgoing MMC messages</para></listitem>
<listitem><para>Duplex : will have Qtractor follow incoming MMC instructions, and provide outgoing MMC messages</para></listitem>
</itemizedlist>
- You can also select a particular MIDI device number with which Qtractor will interact; if you do this, it will ignore MMC messages from other devices, and not send MMC messages to other devices. Enabled the ''Dedicated MIDI control input/output'' will provide JACK with MIDI inputs and outputs that will be used by Qtractor only for MMC messages. Qtractor will not send or receive MMC messages sent on other inputs or outputs if this option is enabled. "SPP" stands for "Song Position Pointer," and helps MIDI-connected applications to keep track of the current location in a session (in other words, where the transport is). This should probably be set to the same setting as "MMC." If you don't know which of these settings to use, then setting "MMC" to "None" is a good choice. This setting can be adjusted at any time, if you later decide to link applications with MMC messages.
+ You can also select a particular MIDI device number with which Qtractor will interact; if you do this, it will ignore MMC messages from other devices, and not send MMC messages to other devices. Enabled the "Dedicated MIDI control input/output" will provide JACK with MIDI inputs and outputs that will be used by Qtractor only for MMC messages. Qtractor will not send or receive MMC messages sent on other inputs or outputs if this option is enabled. "SPP" stands for "Song Position Pointer," and helps MIDI-connected applications to keep track of the current location in a session (in other words, where the transport is). This should probably be set to the same setting as "MMC." If you don't know which of these settings to use, then setting "MMC" to "None" is a good choice. This setting can be adjusted at any time, if you later decide to link applications with MMC messages.
</para>
<para>
The default metronome sound is provided by the "MIDI Metronome," and you can adjust its settings here. In particular, you may wish to provide a "Dedicated MIDI metronome output," to help you separate the metronome's signal.
@@ -106,10 +106,10 @@
If you're using "<application>FluidSynth</application>" with QSynth, you should tell Qtractor about the SoundFont that you're using. When you do this, you enable Qtractor to help you choose instruments ("patches").
<orderedlist>
<listitem><para>Click on 'View > Instruments'</para></listitem>
- <listitem><para>In the ''Instruments'' window, click "Import."</para></listitem>
+ <listitem><para>In the "Instruments" window, click "Import."</para></listitem>
<listitem><para>Navigate to <filename>/usr/share/soundfonts</filename></para></listitem>
<listitem><para>Select the SoundFonts that you would like to use. The default is the FluidR3 GM SoundFont, but you can choose multiple SoundFonts to use simultaneously.</para></listitem>
- <listitem><para>Close the ''Instruments'' window to return to the main Qtractor window.</para></listitem>
+ <listitem><para>Close the "Instruments" window to return to the main Qtractor window.</para></listitem>
</orderedlist>
</para>
</section>
@@ -161,7 +161,7 @@
<section id="sect-Musicians_Guide-Qtractor-Using-MIDI_Tools">
<title>Using the MIDI Matrix Editor's Tools</title>
<para>
- Qtractor's matrix editor for MIDI clips offers a collection of useful tools, available from the ''Tools'' menu in the matrix editor window. These tools only operate on MIDI notes selected in the matrix editor window before the tool window is opened. Regardless of which tool you select from the menu, the same options are available to you each time the window is opened. It is possible to use multiple tools at a time.
+ Qtractor's matrix editor for MIDI clips offers a collection of useful tools, available from the "Tools" menu in the matrix editor window. These tools only operate on MIDI notes selected in the matrix editor window before the tool window is opened. Regardless of which tool you select from the menu, the same options are available to you each time the window is opened. It is possible to use multiple tools at a time.
</para>
<para>
Be careful: the names of the tools may be misleading.
@@ -207,7 +207,7 @@
<listitem><para>Value, which means loudness (velocity).</para></listitem>
</itemizedlist>
</para></listitem>
- <listitem><para>Resize: This tool allows you to explicitly specify the duration or velocity of some MIDI notes. Setting the ''Value'' field will set the velocity (loudness) of all selected notes to that setting. Valid settings are from 0 (quietest) to 127 (loudest). Setting the ''Duration'' field will set the duration (length) of all selected notes to that setting. Duration is most usefully measured as "BBT" (meaning "Bars, Beats, and Ticks" - each is separated by a decimal point), but can also be measured as time or frames.</para></listitem>
+ <listitem><para>Resize: This tool allows you to explicitly specify the duration or velocity of some MIDI notes. Setting the "Value" field will set the velocity (loudness) of all selected notes to that setting. Valid settings are from 0 (quietest) to 127 (loudest). Setting the "Duration" field will set the duration (length) of all selected notes to that setting. Duration is most usefully measured as "BBT" (meaning "Bars, Beats, and Ticks" - each is separated by a decimal point), but can also be measured as time or frames.</para></listitem>
</itemizedlist>
</para>
</section>
@@ -236,7 +236,7 @@
<listitem><para>Move Qtractor's transport to the start of the session.</para></listitem>
<listitem><para>Ensure that only the newly-created audio track is armed for recording.</para></listitem>
<listitem><para>Arm Qtractor's transport for recording.</para></listitem>
- <listitem><para>Press ''Play'' on the transport, and wait as the session plays through.</para></listitem>
+ <listitem><para>Press "Play" on the transport, and wait as the session plays through.</para></listitem>
<listitem><para>When you have reached the end of the session, stop the transport. Qtractor will not automatically stop the transport.</para></listitem>
<listitem><para>Export the file as you normally would by clicking 'Track > Export Tracks > Audio'.</para></listitem>
</orderedlist>
@@ -346,7 +346,7 @@
<para>
<orderedlist>
<listitem><para>Create a new audio track.</para></listitem>
- <listitem><para>Right-click on the audio track, and go to ''Clip'' then ''Import''</para></listitem>
+ <listitem><para>Right-click on the audio track, and go to "Clip" then "Import"</para></listitem>
<listitem><para>Locate the audio file that you want to import (in this case, I imported a recording of the second movement of Beethoven's Op.57 piano sonata, "Appassionata."</para></listitem>
<listitem><para>If the clip doesn't start at the beginning of the track, then click and drag it to the beginning.</para></listitem>
</orderedlist>
@@ -363,7 +363,7 @@
<listitem><para>Start from the beginning, and listen until the end of the first formal section, which I've decided is about the fourth beat of measure 12 (use the ruler to see).</para></listitem>
<listitem><para>Mark that point with the blue arrow.</para></listitem>
<listitem><para>Mark the beginning of the formal area by left-clicking at the beginning of the session. If the transport is at the beginning, then it will hide a blue marker placed at the beginning.</para></listitem>
- <listitem><para>Create a new clip by clicking on ''Edit > Clip > New''</para></listitem>
+ <listitem><para>Create a new clip by clicking on "Edit > Clip > New"</para></listitem>
<listitem><para>The clip editor will appear.</para></listitem>
</orderedlist>
</para>
@@ -375,7 +375,7 @@
</para>
<para>
<orderedlist>
- <listitem><para>In the MIDI matrix editor window, click on the ''Edit mode'' tool, which looks like a pencil with no other markings.</para></listitem>
+ <listitem><para>In the MIDI matrix editor window, click on the "Edit mode" tool, which looks like a pencil with no other markings.</para></listitem>
<listitem><para>I decided to place a note every three beats (one beat is marked by one vertical line), on the beat, lasting for one sixteenth note.
<orderedlist>
<listitem><para>Click the pencil where you want the note to appear. A box will appear. If you drag the box to the right, then the note will sound for longer.</para></listitem>
@@ -401,18 +401,18 @@
<listitem><para>Randomize the pitches:
<orderedlist>
<listitem><para>Click on 'Tools > Randomize'</para></listitem>
- <listitem><para> Ensure that ''Randomize'' is checked</para></listitem>
- <listitem><para>Ensure that ''Note'' is checked (this means "pitch")</para></listitem>
+ <listitem><para> Ensure that "Randomize" is checked</para></listitem>
+ <listitem><para>Ensure that "Note" is checked (this means "pitch")</para></listitem>
<listitem><para>Choose a percentage.</para></listitem>
<listitem><para>Click "OK" to apply.</para></listitem>
<listitem><para>You may need to experiment with the percent of randomization that you allow. Greater randomization means a lower chance of repetition, but it also means that the pitches will be spread within a smaller range.</para></listitem>
- <listitem><para>If you want to re-try the randomization, click on 'Edit > Undo Randomization', then use the ''Randomize'' tool again.</para></listitem>
+ <listitem><para>If you want to re-try the randomization, click on 'Edit > Undo Randomization', then use the "Randomize" tool again.</para></listitem>
<listitem><para>If you like what happens to most of the pitches, you can select and move a few of them either individually or together. To adjust pitches as a group, select the ones that you want to move (either by click-and-drag select or by Control-click select), and Control-drag them to the desired new location.</para></listitem>
</orderedlist>
</para></listitem>
<listitem><para>Now you need to adjust the volume of the pitches. There are two ways to do this:
<itemizedlist>
- <listitem><para>You can select all of the pitches, then use the "Resize MIDI'' tool, adjusting the "Value" property.</para></listitem>
+ <listitem><para>You can select all of the pitches, then use the "Resize MIDI" tool, adjusting the "Value" property.</para></listitem>
<listitem><para>You can select all of the pitches, then use the value editor portion of the matrix editor window. This is at the bottom of the matrix editor window, and the height of each pitch shown here tells you the volume at which it will play. To adjust all of the pitches at once, Control-drag to adjust the height as desired. Be careful when doing this that you don't change the horizontal position, which will change the time that the notes sound.</para></listitem>
<listitem><para>I would suggest at volume of approximately "32," but this depends on your taste. Also, I adjust the volume of some pitches to be louder when the audio file is louder.</para></listitem>
</itemizedlist>
@@ -444,7 +444,7 @@
<listitem><para>Left-click when you have placed the rectangle where you want it.</para></listitem>
</orderedlist>
</para></listitem>
- <listitem><para>Position the transport so that you can listen to the transition from the end of the first clip into the beginning of the second clip. Press ''Play'' on the transport control to listen, then stop it when you are done.</para></listitem>
+ <listitem><para>Position the transport so that you can listen to the transition from the end of the first clip into the beginning of the second clip. Press <guibutton>Play</guibutton> on the transport control to listen, then stop it when you are done.</para></listitem>
<listitem><para>If you need to adjust the position of the second clip, then click-and-drag it into the desired position. Re-listen to verify that you placed the clip where you want it to stay.</para></listitem>
</orderedlist>
</para>
@@ -460,7 +460,7 @@
<listitem><para>Place the blue markers at the beginning and end of the segment that you chose.</para></listitem>
<listitem><para>Create a new MIDI clip.</para></listitem>
<listitem><para>Create the notes separated by three beats, as in the last segment. This time, be sure to add two notes at the same time, by ensure that they are aligned vertically. Again, it doesn't matter which pitches you choose, because they will be randomized.</para></listitem>
- <listitem><para>Select all of the pitches, and randomize them by using the ''Randomize MIDI'' tool.</para></listitem>
+ <listitem><para>Select all of the pitches, and randomize them by using the "Randomize MIDI" tool.</para></listitem>
<listitem><para>Depending on how the pitches are randomized, each pair of notes will probably end up in one of the following situations:
<itemizedlist>
<listitem><para>They are too close or share a particular intervallic relationship that makes them sound like one note.</para></listitem>
@@ -468,7 +468,7 @@
<listitem><para>They share a particular intervallic relationship that makes them sound like one chord built of two equal chords.</para></listitem>
</itemizedlist>
Depending on your aesthetic preferences, you may wish to change some of the notes so that one or some of these situations are avoided.</para></listitem>
- <listitem><para>I created the tone cluster at the end by clicking arbitrarily across bar 37. It happened to create six notes with the pitches G, E, C-sharp, F-sharp, G-sharp, and B. I could have used the ''Randomize MIDI'' tool, but chose not to.</para></listitem>
+ <listitem><para>I created the tone cluster at the end by clicking arbitrarily across bar 37. It happened to create six notes with the pitches G, E, C-sharp, F-sharp, G-sharp, and B. I could have used the "Randomize MIDI" tool, but chose not to.</para></listitem>
<listitem><para>Then I carefully click-and-dragged the right-most end-point of each pitch, so that they all ended at the same time: the first beat of measure 38.</para></listitem>
<listitem><para>When you're done, you may need to copy-and-paste the segment.</para></listitem>
</orderedlist>
@@ -531,7 +531,7 @@
The second-highest range reflects the quickly-moving accompaniment part in the upper register of the piano.
</para>
<para>
- Sorting out the volumes for this passage posed a small challenge, because of the much greater number of notes than in previous passages. Thankfully, the parts are mostly well-separated from each other in the matrix editor. I was able to use click-and-drag selection to select each range separately, and adjust its volume using both the ''Resize MIDI'' tool and Control-drag in the volume adjustment space at the bottom of the matrix editor window.
+ Sorting out the volumes for this passage posed a small challenge, because of the much greater number of notes than in previous passages. Thankfully, the parts are mostly well-separated from each other in the matrix editor. I was able to use click-and-drag selection to select each range separately, and adjust its volume using both the "Resize MIDI" tool and Control-drag in the volume adjustment space at the bottom of the matrix editor window.
</para>
<para>
My sustained-note flourish at the end of this passage was a feeble attempt to establish A Major tonality in the highest register that I used.
diff --git a/en-US/Real_Time_and_Low_Latency.xml b/en-US/Real_Time_and_Low_Latency.xml
index fa083a8..05924e6 100644
--- a/en-US/Real_Time_and_Low_Latency.xml
+++ b/en-US/Real_Time_and_Low_Latency.xml
@@ -16,10 +16,10 @@
<section id="sect-Musicians_Guide-Low_Latency">
<title>Why Low Latency Is Desirable</title>
<para>
- When computer audio specialists talk about a computer acting in '''real-time''', they mean that it is acting with only an imperceptible delay. A computer cannot act on something instantaneously, and the amount of waiting time between an input and its output is called '''latency'''. In order for the delay between input and output to be perceived as non-existant (in other words, for a computer to "react in real-time,") the latency must be low.
+ When computer audio specialists talk about a computer acting in <firstterm>real-time</firstterm>, they mean that it is acting with only an imperceptible delay. A computer cannot act on something instantaneously, and the amount of waiting time between an input and its output is called <firstterm>latency</firstterm>. In order for the delay between input and output to be perceived as non-existant (in other words, for a computer to "react in real-time,") the latency must be low.
</para>
<para>
- For periodic tasks, like processing audio (which has a consistently recurring amount of data per second), low latency is desirable, but ''consistent'' latency is usually more important. Think of it like this: years ago in North America, milk was delivered to homes by a dedicated delivery person. Imagine if the milk delivery person had a medium-latency, but consistent schedule, returning every seven days. You would be able to plan for how much milk to buy, and to limit your intake so that you don't run out too soon. Now imagine if the milk delivery person had a low-latency, but inconsistent schedule, returning every one to four days. You would never be sure how much milk to buy, and you wouldn't know how to limit yourself. Sometimes there would be too much milk, and sometimes you would run out. Audio-processing and synthesis software behaves in a similar way: if it has a consistent amount of latency, it can plan accordingly. If it has an inconsistent amount of lat
ency - whether large or small - there will sometimes be too much data, and sometimes not enough. If your application runs out of audio data, there will be noise or silence in the audio signal - both bad things.
+ For periodic tasks, like processing audio (which has a consistently recurring amount of data per second), low latency is desirable, but <emphasis>consistent</emphasis> latency is usually more important. Think of it like this: years ago in North America, milk was delivered to homes by a dedicated delivery person. Imagine if the milk delivery person had a medium-latency, but consistent schedule, returning every seven days. You would be able to plan for how much milk to buy, and to limit your intake so that you don't run out too soon. Now imagine if the milk delivery person had a low-latency, but inconsistent schedule, returning every one to four days. You would never be sure how much milk to buy, and you wouldn't know how to limit yourself. Sometimes there would be too much milk, and sometimes you would run out. Audio-processing and synthesis software behaves in a similar way: if it has a consistent amount of latency, it can plan accordingly. If it has an inconsist
ent amount of latency - whether large or small - there will sometimes be too much data, and sometimes not enough. If your application runs out of audio data, there will be noise or silence in the audio signal - both bad things.
</para>
<para>
Relatively low latency is still important, so that your computer reacts imperceptibly quickly to what's going on. The point is that the difference between an 8 ms target latency and a 16 ms target latency is almost certainly imperceptible to humans, but the higher latency may help your computer to be more consistent - and that's more important.
@@ -32,7 +32,7 @@
If you've ever opened the "System Monitor" application, you will probably have noticed that there are a lot of "processes" running all the time. Some of these processes need the processor, and some of them are just waiting around for something to happen. To help increase the number of processes that can run at the same time, many modern CPUs have more than one "core," which allows for more processes to be evaluated at the same time. Even with these improvements, there are usually more processes than available cores: my computer right now has 196 processes and only three cores. There has to be a way of decided which process gets to run and when, and this task is left to the operating system.
</para>
<para>
- In Linux systems like Fedora Linux, the core of the operating system (called the '''kernel''') is responsible for deciding which process gets to execute at what time. This responsibility is called "scheduling." Scheduling access to the processor is called, '''processor scheduling'''. The kernel also manages scheduling for a number of other things, like memory access, video hardware access, audio hardware access, hard drive access, and so on. The algorithm (procedure) used for each of these scheduling tasks is different for each, and can be changed depending on the user's needs and the specific hardware being used. In a hard drive, for example, it makes sense to consider the physical location of data on a disk before deciding which process gets to read first. For a processor this is irrelevant, but there are many other things to consider.
+ In Linux systems like Fedora Linux, the core of the operating system (called the <firstterm>kernel</firstterm>) is responsible for deciding which process gets to execute at what time. This responsibility is called "scheduling." Scheduling access to the processor is called, <firstterm>processor scheduling</firstterm>. The kernel also manages scheduling for a number of other things, like memory access, video hardware access, audio hardware access, hard drive access, and so on. The algorithm (procedure) used for each of these scheduling tasks is different for each, and can be changed depending on the user's needs and the specific hardware being used. In a hard drive, for example, it makes sense to consider the physical location of data on a disk before deciding which process gets to read first. For a processor this is irrelevant, but there are many other things to consider.
</para>
<para>
There are a number of scheduling algorithms that are available with the standard Linux kernel, and for most uses, a "fair queueing" system is appropriate. This helps to ensure that all processes get an equal amount of time with the processor, and it's unacceptable for audio work. If you're recording a live concert, and the "PackageKit" update manager starts, you don't care if PackageKit gets a fair share of processing time - it's more important that the audio is recorded as accurately as possible. For that matter, if you're recording a live concert, and your computer isn't fast enough to update the monitor, keyboard, and mouse position while providing uninterrupted, high-quality audio, you want the audio instead of the monitor, keyboard, and mouse. After all, once you've missed even the smallest portion of audio, it's gone for good!
@@ -45,7 +45,7 @@
There is a "real-time patch" for the Linux kernel which enables the processor to unfairly schedule certain processes that ask for higher priority. Although the term "patch" may make it seem like this is just a partial solution, it really refers to the fact that the programming code used to enable this kind of unfair scheduling is not included in standard kernels; the standard kernel code must have this code "patched" into it.
</para>
<para>
- The default behaviour of a real-time kernel is still to use the "fair queueing" system by default. This is good, because most processes don't need to have consistently low latencies. Only specific processes are designed to request high-priority scheduling. Each process is given (or asks for) a priority number, and the real-time kernel will always give processing time to the process with the highest priority number, even if that process uses up ''all'' of the available processing time. This puts regular applications at a disadvantage: when a high-priority process is running, the rest of the system may be unable to function properly. In extreme (and very rare!) cases, a real-time process can encounter an error, use up all the processing time, and disallow any other process from running - effectively locking you out of your computer. Security measures have been taken to help ensure this doesn't happen, but as with anything, there is no guarantee. If you use a real-tim
e kernel, you are exposing yourself to a slightly higher risk of system crashes.
+ The default behaviour of a real-time kernel is still to use the "fair queueing" system by default. This is good, because most processes don't need to have consistently low latencies. Only specific processes are designed to request high-priority scheduling. Each process is given (or asks for) a priority number, and the real-time kernel will always give processing time to the process with the highest priority number, even if that process uses up <emphasis>all</emphasis> of the available processing time. This puts regular applications at a disadvantage: when a high-priority process is running, the rest of the system may be unable to function properly. In extreme (and very rare!) cases, a real-time process can encounter an error, use up all the processing time, and disallow any other process from running - effectively locking you out of your computer. Security measures have been taken to help ensure this doesn't happen, but as with anything, there is no guarantee. If y
ou use a real-time kernel, you are exposing yourself to a slightly higher risk of system crashes.
</para>
<para>
A real-time kernel should not be used on a computer that acts as a server, for these reasons.
@@ -55,10 +55,10 @@
<section id="sect-Musicians_Guide-Hard_and_Soft_Real_Time">
<title>Hard and Soft Real-Time</title>
<para>
- Finally, there are two different kinds of real-time scheduling. The Linux kernel, even at its most extreme, uses only '''soft real-time'''. This means that, while processor and other scheduling algorithms may be optimized to give preference to higher-priority processes, no absolute guarantee of performance can be made. A real-time kernel helps to greatly reduce the chance of an audio process running out of data, but sometimes it can still happen.
+ Finally, there are two different kinds of real-time scheduling. The Linux kernel, even at its most extreme, uses only <firstterm>soft real-time</firstterm>. This means that, while processor and other scheduling algorithms may be optimized to give preference to higher-priority processes, no absolute guarantee of performance can be made. A real-time kernel helps to greatly reduce the chance of an audio process running out of data, but sometimes it can still happen.
</para>
<para>
- A '''hard real-time''' computer is designed for specialized purposes, where even the smallest amount of latency can make the difference between life and death. These systems are implemented in hardware as well as software. Example uses include triggering airbag deployment in automobile crashes, and monitoring the heart rate of a patient during an operation. These computers are not particularly multi-functional, which is part of their means to accomplishing a guaranteed low latency.
+ A <firstterm>hard real-time</firstterm> computer is designed for specialized purposes, where even the smallest amount of latency can make the difference between life and death. These systems are implemented in hardware as well as software. Example uses include triggering airbag deployment in automobile crashes, and monitoring the heart rate of a patient during an operation. These computers are not particularly multi-functional, which is part of their means to accomplishing a guaranteed low latency.
</para>
</section>
diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml
index fc2df32..af81d32 100644
--- a/en-US/Revision_History.xml
+++ b/en-US/Revision_History.xml
@@ -117,15 +117,33 @@
</revdescription>
</revision>
- <!-- TODO: review <code> in "Basic Programming in SC" -->
+ <revision>
+ <revnumber>7</revnumber>
+ <date>Sun Aug 8 2010</date>
+ <author>
+ <firstname>Christopher</firstname>
+ <surname>Antila</surname>
+ <email>crantila at fedoraproject.org</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Reviewed use of <code> tags in "Basic Programming in SC" chapter.</member>
+ <member>Searched code for '' or ''' and replaced them with <emphasis> where appropriate.</member>
+ <member>Formatted bibliography/book-list in the Solfege chapter.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+
+ <!-- For Summer Coding deadline, August 9th -->
<!-- TODO: re-write JACK install instructions to incorporate jack2 in F14 -->
- <!-- TODO: remove '' and ''' used for emphasis and replace with <emphasis> -->
+ <!-- For the week starting August 9th -->
+ <!-- TODO: fix the example around line 630 of SC Basic Programming -->
<!-- TODO: convert images to format given by R. Landmann -->
- <!-- TODO: complete review of <code> tags -->
<!-- TODO: convert SuperCollider examples to <xi:include ... /> -->
<!-- TODO: convert LilyPond examples to <xi:include ... /> -->
+ <!-- These will never be finished. I mean... they're ongoing tasks. -->
<!-- TODO: ensure that everything is formatted correctly -->
<!-- TODO: re-write the entire Guide to use the Apple Style Guide / CMoS / American Heritage Dictionary -->
</revhistory>
diff --git a/en-US/Solfege.xml b/en-US/Solfege.xml
index e4e7301..b8089e2 100644
--- a/en-US/Solfege.xml
+++ b/en-US/Solfege.xml
@@ -238,7 +238,7 @@
<listitem><para>Segment 1
<itemizedlist>
<listitem><para>When you wake up, before breakfast.</para></listitem>
- <listitem><para>Warm up your voice and body (good activity anyway - ''not'' part of the ten minutes!)</para></listitem>
+ <listitem><para>Warm up your voice and body (good activity anyway - <emphasis>not</emphasis> part of the ten minutes!)</para></listitem>
<listitem><para>Sing and perfect some excerpts from a book designed for sight-singing.</para></listitem>
</itemizedlist>
</para></listitem>
@@ -280,30 +280,64 @@
</itemizedlist>
</para>
<para>
- !!F!! Bibliography list !!F!!
- Books:
- * Hindemith, Paul (1949). ''Elementary Training for Musicians''. Schott.
- ** Antiquated instructions, but the exercises are excellent.
- ** Offers a wide variety of exercises and strategies, especially for coordination of quasi-independent musical lines.
- ** In particular, Hindemith avoids the use of solfa syllables; modern practice uses them anyway.
- * Karpinski, Gary (2007). ''Manual for Ear Training and Sight Singing''. Norton.
- ** Contains chapters with detailed theoretical explanations, tips for listening, and developmental exercises.
- ** Comes with a CD containing listening exercises; possibly incompatible with Linux.
- * Karpinski, Gary. ''Anthology for Sight Singing''. Norton: 2006.
- ** Organized by chapter to coincide with the above ''Manual''.
- ** Contains examples that can be used to train one's ear by singing.
- ** It is best to play only the tonic tone (not a chord or scale) on a keyboard instrument before singing. Only after you are sure that you have sung the excerpt correctly by ear should it be played on a keyboard instrument for verification.
- ** Contains some ensemble excerpts, to be sung by a group of people who are working on ear training together.
- * Hall, Anne (2004). ''Studying Rhythm''. Prentice Hall.
- ** Similar in principle to Karpinski's ''Anthology'': contains one- and two-part rhythms to be spoken or spoken-and-clapped. Also contains some 3- and 4-part rhythms.
- ** Progresses incrementally from easy-to-perform rhythms to more difficult ones.
- ** Offers some performance tips.
- ** Provides a few ensemble rhythms to be performed by a group of people working on ear training; all two-part rhythms can also be treated as ensemble rhythms.
- * Crowell, Ben (2004). ''Eyes and Ears: an Anthology of Melodies for Sight-Singing''.
- ** An open-source sight-singing text, available free from [http://www.lightandmatter.com/sight/sight.html here].
- ** Contains about 400 melodies from the public domain, and some instructions.
- * Hoffman, ''The Rhythm Book''. Smith Creek Music, 2009.
+ Aural Skills Books:
+ <itemizedlist>
+ <listitem><para>Crowell's <citetitle>Eyes and Ears</citetitle> is an open-source sight-singing text, available for free from the URL listed above. This book contains about 400 melodies from the public domain, along with some helpful instructions.</para></listitem>
+ <listitem><para>Hall's <citetitle>Studying Rhythm</citetitle> is a small and expensive - but useful - book, containing a collection of rhythms to be spoken or spoken-and-clapped. This book also contains some three-part and four-part rhythms. The exercises increase in difficulty. The book offers some performance tips.</para></listitem>
+ <listitem><para>Hindemith's <citetitle>Elementary Training</citetitle> is a classic aural skills text, but it was originally published in 1949, and a lot of research has taken place since then about how people learn aural skills. The book offers a wide variety of exercises, especially to develop coordination when performing multiple independent musical lines. We recommend that you ignore Hindemith's instructions, and use <firstterm>tonic solfa</firstterm> syllables. For more information on tonic solfa, refer to <citetitle>Tonic sol-fa</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Tonic_sol-fa" /></para></listitem>
+ <listitem><para>Hoffman's <citetitle>The Rhythm Book</citetitle> was developed specifically for the takadimi rhythm system. Like Hall's text, <citetitle>The Rhythm Book</citetitle> progresses fro easy to difficult exercises, and offers helpful instructions for performance.</para></listitem>
+ <listitem><para>Karpinski's two texts are the result of two decades of research about how musicians acquire aural skills. The <citetitle>Manual</citetitle> contains instructions, exercises, and tips on training yourself to hear musical elements <emphasis>and</emphasis> real music, and how to perform and imagine music. The <citetitle>Anthology</citetitle> is organized in chapters that coincide with the topics discussed in the <citetitle>Manual</citetitle>, and contains very few instructions. The <citetitle>Anthology</citetitle> contains a wide variety of musical excerpts, some from the public domain and others under copyright, taken from the "classical music" canon and from national repertoires. There are some three-part and four-part exercises, which should be performed by a group of people leraning aural skills together.</para></listitem>
+ </itemizedlist>
</para>
+ <para>
+ When you practise sight-singing from any book, we recommend hearing the tonic pitch from a fixed-pitch instrument (like a piano or keyboard synthesizer) before you sing an excerpt. With the tonic pitch in your mind, and without singing aloud, find the starting note of the excerpt, and sing the excerpt <emphasis>in your mind</emphasis> several times, until you are sure that you are singing the excerpt correctly. When you have the melody in your mind, sing the excerpt out loud, as many times as you need to be sure that you are singing it correctly. Only <emphasis>after</emphasis> you sing the excerpt perfectly should you play it on a fixed-pitch instrument to confirm that you are correct.
+ </para>
+ <para>
+ You should build your ear with as little help from external sources (pianos, and so on) as possible. A significant amount of research shows that this gives you a more flexible musical mind, and that, while the initial learning curve is very steep, you will ultimately be able to learn new concepts faster.
+ </para>
+ <bibliography>
+ <title>Aural Skills Books</title>
+ <biblioentry>
+ <author><surname>Crowell</surname><firstname>Ben</firstname></author>
+ <title>Eyes and Ears: an Anthology of Melodies for Sight-Singing</title>
+ <date>2004</date>
+ <publisher>
+ <publishername>Ben Crowell</publishername>
+ <address><otheraddr><ulink url="http://www.lightandmatter.com/sight/sight.html" /></otheraddr></address>
+ </publisher>
+ </biblioentry>
+ <biblioentry>
+ <author><surname>Hall</surname><firstname>Anne</firstname></author>
+ <title>Studying Rhythm</title>
+ <date>2004</date>
+ <publishername>Prentice Hall</publishername>
+ </biblioentry>
+ <biblioentry>
+ <author><surname>Hindemith</surname><firstname>Paul</firstname></author>
+ <title>Elementary Training for Musicains</title>
+ <date>1984</date>
+ <!-- <edition>2</edition> -->
+ <publishername>Schott Music Corp.</publishername>
+ </biblioentry>
+ <biblioentry>
+ <author><surname>Hoffman</surname></author>
+ <title>The Rhythm Book</title>
+ <date>2009</date>
+ <publishername>Smith Creek Music</publishername>
+ </biblioentry>
+ <biblioentry>
+ <author><surname>Karpinski</surname><firstname>Gary</firstname></author>
+ <title>Manual for Ear Training and Sight Singing</title>
+ <date>2007</date>
+ <publishername>Norton</publishername>
+ </biblioentry>
+ <biblioentry>
+ <author><surname>Karpinski</surname><firstname>Gary</firstname></author>
+ <title>Anthology for Sight Singing</title>
+ <date>2006</date>
+ <publishername>Norton</publishername>
+ </biblioentry>
+ </bibliography>
</section>
</section> <!-- Ends "How to Train Yourself" Section --> <!-- Solfege-Training- -->
diff --git a/en-US/Sound_Cards.xml b/en-US/Sound_Cards.xml
index 2748571..2306d9d 100644
--- a/en-US/Sound_Cards.xml
+++ b/en-US/Sound_Cards.xml
@@ -137,10 +137,10 @@
<para>
Here are some widely-used sample rates and sample formats. You can use these to help you decide which sample rate and sample format to use.
<itemizedlist>
- <listitem><para>16-bit samples, 44.1 kHz sample rate. Used for audio CDs. Widely compatible. Bit rate of 705.6 kb/s)</para></listitem>
- <listitem><para>24-bit samples, and 96 kHz sample rate. Audio CDs are recorded with these settings, and "down-mixed" later. Bit rate of 2304 kb/s)</para></listitem>
- <listitem><para>24-bit samples, and 192 kHz sample rate. Maximum settings for DVD Audio, but not widely compatible. Bit rate of 4608 kb/s)</para></listitem>
- <listitem><para>1-bit bit rate, and 2822.4 kHz sample rate. Used for SuperAudio CDs. Very rare elsewhere. Bit rate of 2822.4 kb/s)</para></listitem>
+ <listitem><para>16-bit samples, 44.1 kHz sample rate. Used for audio CDs. Widely compatible. Bit rate of 705.6 kb/s.</para></listitem>
+ <listitem><para>24-bit samples, and 96 kHz sample rate. Audio CDs are recorded with these settings, and "down-mixed" later. Bit rate of 2304 kb/s.</para></listitem>
+ <listitem><para>24-bit samples, and 192 kHz sample rate. Maximum settings for DVD Audio, but not widely compatible. Bit rate of 4608 kb/s.</para></listitem>
+ <listitem><para>1-bit samples, and 2822.4 kHz sample rate. Used for SuperAudio CDs. Very rare elsewhere. Bit rate of 2822.4 kb/s.</para></listitem>
</itemizedlist>
</para>
<para>
diff --git a/en-US/Sound_Servers.xml b/en-US/Sound_Servers.xml
index 8ff8d00..e05c262 100644
--- a/en-US/Sound_Servers.xml
+++ b/en-US/Sound_Servers.xml
@@ -33,7 +33,7 @@
<!--
Fernando Lopez-Lezcano: I don't think that at this point applications can be written for the pulse audio API. Lennart I think discourages it. AFAIK applications still use the ALSA API when talking to pulse audio, it is just that pulse is in the middle, and can manage connections from many applications that basically share the audio hardware (which is only managed by PA). So what is made easier is not "audio programming" but perhaps "shared access to the sound card". You would not want to program for PA (it is very complex, perhaps even more than ALSA as it is all asynchronous and callback based).
- Christopher Antila: This is useful and interesting information, but I don't think it belongs here. I''m keeping it as a comment, in case somebody decides to use it in the future.
+ Christopher Antila: This is useful and interesting information, but I don't think it belongs here. I'm keeping it as a comment, in case somebody decides to use it in the future.
-->
</section>
<section id="sect-Musicians_Guide-Sound_Servers-JACK">
diff --git a/en-US/SuperCollider/SuperCollider-Basic_Programming.xml b/en-US/SuperCollider/SuperCollider-Basic_Programming.xml
index 78b4d74..fcccf05 100644
--- a/en-US/SuperCollider/SuperCollider-Basic_Programming.xml
+++ b/en-US/SuperCollider/SuperCollider-Basic_Programming.xml
@@ -107,7 +107,7 @@ Hello, SC!
A "statement" is a single instruction, which always ends with a semicolon. Exactly what constitutes a statement will become clear as you gain experience, and you will eventually automatically remember the semicolon.
</para>
<para>
- In the Hello World Programs above, all of the statements contain the single instruction to post a line to the output screen. What happens when you remove the first semicolon, which marks the end of the first statement? The <application>SuperCollider</application> interpreter produces an unhelpful error message, and tells you that an error occurred ''after'' the forgotten semicolon. This is why it is important to always remember statement-concluding semicolons.
+ In the Hello World Programs above, all of the statements contain the single instruction to post a line to the output screen. What happens when you remove the first semicolon, which marks the end of the first statement? The <application>SuperCollider</application> interpreter produces an unhelpful error message, and tells you that an error occurred <emphasis>after</emphasis> the forgotten semicolon. This is why it is important to always remember statement-concluding semicolons.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-First_Steps-Numbers_and_Strings">
@@ -116,23 +116,23 @@ Hello, SC!
In many programming languages, it is the programmer's responsibility to determine the type of data that is being used, and how it should be stored. The <application>SuperCollider</application> interpreter takes advantage of the power of modern computers, and deals with this on our behalf. This greatly simplifies basic tasks, because there are only two kinds of data to worry about, and they make perfect sense:
<itemizedlist>
<listitem><para>Numbers: These are numbers, written simply as numbers. Anything that can be done with real-world numbers can also be done with <application>SuperCollider</application>'s numbers. They can be as large or small, positive or negative as you want. They can have any number of digits on either side of the decimal point.</para></listitem>
- <listitem><para>Strings: These are a string of characters, written between two double-quote characters like "this." The double-quote characters are required so that <application>SuperCollider</application> knows where to begin and end the string of characters. A string of character can contain as many characters as you like, including one character and no characters. If you want to include a double-quote character in a string, you should put a blackslash before it. The following is interpreted by <application>SuperCollider</application> as a string with only a double-quote character: <code>"\""</code></para></listitem>
+ <listitem><para>Strings: These are a string of characters, written between two double-quote characters like "this." The double-quote characters are required so that <application>SuperCollider</application> knows where to begin and end the string of characters. A string of character can contain as many characters as you like, including one character and no characters. If you want to include a double-quote character in a string, you should put a blackslash before it. The following is interpreted by <application>SuperCollider</application> as a string with only a double-quote character: <literal>"\""</literal></para></listitem>
</itemizedlist>
</para>
<para>
Here are some examples of numbers and strings:
<itemizedlist>
- <listitem><para><code>5;</code></para></listitem>
- <listitem><para><code>18920982341;</code></para></listitem>
- <listitem><para><code>0.00000000000001;</code></para></listitem>
- <listitem><para><code>"characters";</code></para></listitem>
- <listitem><para><code>"@";</code></para></listitem>
- <listitem><para><code>"";</code></para></listitem>
- <listitem><para><code>"6";</code></para></listitem>
+ <listitem><para><literal>5</literal></para></listitem>
+ <listitem><para><literal>18920982341</literal></para></listitem>
+ <listitem><para><literal>0.00000000000001</literal></para></listitem>
+ <listitem><para><literal>"characters"</literal></para></listitem>
+ <listitem><para><literal>"@"</literal></para></listitem>
+ <listitem><para><literal>""</literal></para></listitem>
+ <listitem><para><literal>"6"</literal></para></listitem>
</itemizedlist>
</para>
<para>
- Is the last example a number or a string? You and I recognize that it is a number inside a string, but <application>SuperCollider</application> will only treat it as a string. You can do string things with it, but you cannot do number things with it. You cannot add <code>"6"</code> to something, for example. Notice also that each example ends with a semicolon, which makes them complete statements. The statements don't do anything but represent themselves.
+ Is the last example a number or a string? You and I recognize that it is a number inside a string, but <application>SuperCollider</application> treats it as a string. You can do string things with it, but you cannot do number things with it. You cannot add <literal>"6"</literal> to something, for example.
</para>
<para>
Try executing the following single-line programs. Think about why the <application>SuperCollider</application> interpreter produces the output that it does.
@@ -179,7 +179,7 @@ Hello, SC!
Consider a traffic light, which has three possible symbols: green, yellow, and red. When you are driving, and you encounter a traffic light, you might see that its red symbol is activated (the red light is illuminated). What you see is a red light, but you understand that it means you should stop your car. Red lights in general do not make you stop - it is specifically red traffic lights, because we know that it is a symbol meaning to stop.
</para>
<para>
- SuperCollider's variables work in the same way: you tell the interpreter that you want to use a symbol, like <code>cheese</code>. Then you assign <code>cheese</code> a value, like <code>5</code>. After that point, whenever you use <code>cheese</code>, the interpreter will automatically know that what you really mean is <code>5</code>.
+ SuperCollider's variables work in the same way: you tell the interpreter that you want to use a symbol, like <literal>cheese</literal>. Then you assign <literal>cheese</literal> a value, like <literal>5</literal>. After that point, whenever you use <literal>cheese</literal>, the interpreter will automatically know that what you really mean is <literal>5</literal>.
</para>
<para>
Run the following two programs. They should result in the same output.
@@ -195,7 +195,7 @@ Hello, SC!
]]></programlisting>
</para>
<para>
- In the first example, the program calculates the value of <code>5 + 5</code>, which is <code>10</code>, and returns that to the interpreter, which prints it out. In the second example, the program tells the interpreter that it wants to use a variable called <code>cheese</code> then it assigns cheese the value <code>5</code>. Finally, the program calculates <code>cheese + cheese</code>, which it understands as meaning <code>5 + 5</code>, and returns <code>10</code> to the interpreter, which prints it out.
+ In the first example, the program calculates the value of <code>5 + 5</code>, which is <literal>10</literal>, and returns that to the interpreter, which prints it out. In the second example, the program tells the interpreter that it wants to use a variable called <literal>x</literal> then it assigns cheese the value <literal>5</literal>. Finally, the program calculates <code>cheese + cheese</code>, which it understands as meaning <code>5 + 5</code>, and returns <literal>10</literal> to the interpreter, which prints it out.
</para>
<para>
This trivial use of a variable does nothing but complicate the process of adding 5 to itself. Soon you will see that variables can greatly simplify your programs.
@@ -218,7 +218,7 @@ Hello, SC!
<para>
The first assignment to a variable is said to "initialize" the variable. Initialization is a special kind of assignment, because a variable cannot be used before it is initialized. If a program attempts to use an un-initialized variable, the <application>SuperCollider</application> interpreter will cause an error. For this reason, you should always initialize a variable when you declare it. There is a special way to do this:
<programlisting>var <replaceable>variableName</replaceable> = nil;</programlisting>
- Since you can't always assign a useful value, you can pick an arbitrary one. Assigning "nil" is common practice, because it means "nothing," but without actually being nothing (this avoids ''some'' errors). Assigning zero is another possibility; it is standard practice in many programming languages, and will avoid most errors, even if the variable is eventually supposed to hold another kind of object. Intialization and declaration of multiple variables can also be done as a list:
+ Since you can't always assign a useful value, you can pick an arbitrary one. Assigning "nil" is common practice, because it means "nothing," but without actually being nothing (this avoids <emphasis>some</emphasis> errors). Assigning zero is another possibility; it is standard practice in many programming languages, and will avoid most errors, even if the variable is eventually supposed to hold another kind of object. Intialization and declaration of multiple variables can also be done as a list:
<programlisting>var <replaceable>variableName</replaceable> = 0, <replaceable>variableOtherName</replaceable> = 0;</programlisting>
</para>
<para>
@@ -234,7 +234,7 @@ Hello, SC!
Use variables to write programs that do the following tasks:
<orderedlist>
<listitem><para>Perform arithmetic with an uninitialized variable. An error should appear when the program is executed.</para></listitem>
- <listitem><para>Calculate the value of <code>y</code>, if all other values are known, for the quadratic equation: <code>y = a * x * x + b * x + c</code></para></listitem>
+ <listitem><para>Calculate the value of <literal>y</literal>, if all other values are known, for the quadratic equation: <code>y = a * x * x + b * x + c</code></para></listitem>
<listitem><para>Re-write the Hello World Program so that it will say "Hello" to a name stored in a variable. Remember that you can use the interpreter to automatically output the last line of a function.</para></listitem>
</orderedlist>
</para>
@@ -261,7 +261,7 @@ myFunction.value;
<section id="sect-Musicians_Guide-SC-Basic_Programming-Variables_and_Functions-Function_Arguments">
<title>Function Arguments</title>
<para>
- The most useful aspect of Functions is that they can produce varying results, depending on their input. For whatever reason, the input accepted by a Function is called an "argument." <application>SuperCollider</application>'s Functions can accept any number of arguments - zero, one, or many. Argument values (called "parameters") are provided to a Function by adding them in parentheses after the name of the Function, separated with commas, like this: <code>exampleFunction( 5, 7, 9 );</code> Argument variables are declared as the first statement in a Function, like this: <code>arg oneNumber, twoNumber;</code>
+ The most useful aspect of Functions is that they can produce varying results, depending on their input. For whatever reason, the input accepted by a Function is called an "argument." <application>SuperCollider</application>'s Functions can accept any number of arguments - zero, one, or many. Argument values (called "parameters") are provided to a Function by adding them in parentheses after the name of the Function, separated with commas, like this: <code>exampleFunction( 5, 7, 9 );</code> Argument variables are declared as the first statement in a Function, like this: <code>arg <replaceable>oneNumber</replaceable>, <replaceable>twoNumber</replaceable>;</code>
</para>
<para>
This program is significantly more complicated than previous examples, but it shows how useful Functions can be. Notice how the braces in that example are on different lines than the rest of the Function, which gives us more space within the Function to complete some useful work.
@@ -280,22 +280,23 @@ myFunction.value;
]]></programlisting>
Here is how the program works:
<orderedlist>
- <listitem><para>A variable named <code>greeter</code> is declared, and assigned a Function.</para></listitem>
- <listitem><para>The Function contains an argument called <code>name</code>, and outputs "Hello" plus the name given to it.</para></listitem>
- <listitem><para>The parentheses here <code>( "Hello" + name )</code> ensure that the two strings are added together ''before'' the "postln" message prints them out.</para></listitem>
- <listitem><para>The <code>greeter</code> variable is used to call the Function with two different names.</para></listitem>
+ <listitem><para>A variable named <literal>greeter</literal> is declared, and assigned a Function.</para></listitem>
+ <listitem><para>The Function contains an argument called <literal>name</literal>, and outputs "Hello" plus the name given to it.</para></listitem>
+ <listitem><para>The parentheses here <code>( "Hello" + name )</code> ensure that the two strings are added together <emphasis>before</emphasis> the <function>postln</function> message prints them out.</para></listitem>
+ <listitem><para>The <literal>greeter</literal> variable is used to call the Function with two different names.</para></listitem>
<listitem><para>The <code>nil;</code> statement is optional, and does not affect the operation of the program. What it does is return a "nothing" value to the interpreter after program execution completes, so that the last message is not repeated.</para></listitem>
</orderedlist>
</para>
<para>
- Since every argument has a name, <application>SuperCollider</application> allows you to use that name when executing the Function. This example executes the <code>greeter</code> Function from the last example:
- <code>greeter.value( name:"Myung-Whun" );</code> This is more useful if there are many arguments, and you do not remember the order that they appear in the Function's definition.
+ Since every argument has a name, <application>SuperCollider</application> allows you to use that name when executing the function. This example executes the <function>greeter</function> function from the last example:
+ <programlisting><![CDATA[greeter.value( name:"Myung-Whun" );]]></programlisting>
+ This is more useful if there are many arguments, and you do not remember the order that they appear in the Function's definition.
</para>
<para>
<application>SuperCollider</application> also allows you to specify default values for arguments, so that they do not need to be specified. This allows optional customization of a Function's behaviour, and is therefore very powerful.
</para>
<para>
- This example modifies the one above by adding default-value arguments, and by calling arguments with their name. As you can see, I've been tricking you a bit: <code>postln</code> is actually a Function, but a special kind, explained later.
+ This example modifies the one above by adding default-value arguments, and by calling arguments with their name. As you can see, I've been tricking you a bit: <function>postln</function> is actually a Function, but a special kind, explained later.
<programlisting><![CDATA[
(
var greeter =
@@ -340,8 +341,8 @@ myFunction.value;
Here is how the program works:
<orderedlist>
<listitem><para>A Function and variable are created, and assigned values.</para></listitem>
- <listitem><para>This line <code>someNumber = mysticalMath.value( someNumber );</code> executes the <code>mysticalMath</code> Function, which multiplies its argument by 23 and returns the value. Then, it assigns the return value of the Function to <code>someNumber</code>. In any statement that contains an assignment, the assignment is always done last. In other words, the Function in this example will ''always'' be given an argument of <code>9</code>, and only ''after'' the Function completes execution and returns a value will that value be assigned to <code>someNumber</code>.</para></listitem>
- <listitem><para>The new value of <code>someNumber</code> is displayed.</para></listitem>
+ <listitem><para>This line <code>someNumber = mysticalMath.value( someNumber );</code> executes the <function>mysticalMath</function> function, which multiplies its argument by <literal>23</literal> and returns the value. Then, it assigns the return value of the Function to <literal>someNumber</literal>. In any statement that contains an assignment, the assignment is always done last. In other words, the Function in this example will <emphasis>always</emphasis> be given an argument of <literal>9</literal>, and only <emphasis>after</emphasis> the Function completes execution and returns a value will that value be assigned to <function>someNumber</function>.</para></listitem>
+ <listitem><para>The new value of <literal>someNumber</literal> is displayed.</para></listitem>
</orderedlist>
</para>
<para>
@@ -401,7 +402,8 @@ myFunction.value;
sixteen.postln; // always causes an error
)
]]></programlisting>
- Because <code>function</code> declares its own copy of <code>zero</code>, it is modified independently of the variable <code>zero</code> declared before the Function. Every time <code>function</code> is executed, it re-declares its own <code>zero</code>, and the interpreter keeps it separate from any other variables with the same name. When <code>function</code> has finished executing, the interpreter destroys its variables. Variables declared inside any Function are only ever accessible from within that Function. This is why, when we try to execute <code>sixteen.postln;</code>, the interpreter encounters an error: <code>sixteen</code> exists only within <code>function</code>, and is not accessible outside the Function. By the way, in order to excute this example, you will need to remove the error-causing reference to <code>sixteen</code>.
+ <!-- Is it <literal>fuction or <function>function??? -->
+ Because <literal>function</literal> declares its own copy of <literal>zero</literal>, it is modified independently of the variable <literal>zero</literal> declared before the Function. Every time <literal>function</literal> is executed, it re-declares its own <literal>zero</literal>, and the interpreter keeps it separate from any other variables with the same name. When <literal>function</literal> has finished executing, the interpreter destroys its variables. Variables declared inside any Function are only ever accessible from within that Function. This is why, when we try to execute <code>sixteen.postln;</code>, the interpreter encounters an error: <literal>sixteen</literal> exists only within <literal>function</literal>, and is not accessible outside the function. By the way, in order to excute this example, you will need to remove the error-causing reference to <literal>sixteen</literal>.
</para>
<para>
Now consider the scope of the variables in this example:
@@ -420,10 +422,10 @@ myFunction.value;
zero.postln; // always prints 8
)
]]></programlisting>
- Why does the last line always print <code>8</code>? It's because <code>zero</code> was set to 8 within <code>function</code>. More importantly, <code>function</code> did not declare its own copy of <code>zero</code>, so it simply accesses the one declared in the next "highest" block of code, which exists between ( and ) in this example.
+ Why does the last line always print <literal>8</literal>? It's because <literal>zero</literal> was set to <literal>8</literal> within <literal>function</literal>. More importantly, <literal>function</literal> did not declare its own copy of <literal>zero</literal>, so it simply accesses the one declared in the next "highest" block of code, which exists between <literal>(</literal> and <literal>)</literal> in this example.
</para>
<para>
- This is why it's important to pay attention to a variable's scope, and to make sure that you declare your variables in the right place. Unexpected and difficult-to-find programming mistakes can occur when you forget to declare a variable, but it is declared elsewhere in your program: you will be allowed to use the variable, but it will be modified unexpectedly. On the other hand, it can be greatly advantageous to be able to access variables declared "outside the local scope" (meaning variables that aren't declared in the same code block in which they're used), but careful thought and planning is required.
+ This is why it is important to pay attention to a variable's scope, and to make sure that you declare your variables in the right place. Unexpected and difficult-to-find programming mistakes can occur when you forget to declare a variable, but it is declared elsewhere in your program: you will be allowed to use the variable, but it will be modified unexpectedly. On the other hand, it can be greatly advantageous to be able to access variables declared "outside the local scope" (meaning variables that are not declared in the same code block in which they are used), but careful thought and planning is required.
</para>
<para>
Astute readers will notice that it is possible to re-declare the single-letter variable names, allowing you to control their scope. Consider the following program:
@@ -442,11 +444,11 @@ myFunction.value;
a.postln;
)
]]></programlisting>
- This example requires careful examination. What is the scope of <code>a</code>, <code>b</code>, and <code>c</code>? The answers may be surprising.
+ This example requires careful examination. What is the scope of <literal>a</literal>, <literal>b</literal>, and <literal>c</literal>? The answers may be surprising.
<itemizedlist>
- <listitem><para><code>a</code> is declared just after the ( character, so the interpreter destroys it upon reaching the ) character.</para></listitem>
- <listitem><para><code>c</code> is declared just after the { character, so the interpreter destroys it upon reaching the } character.</para></listitem>
- <listitem><para><code>b</code> is ''not'' declared in this program, so it refers to the automatically-declared variable with that name. The interpreter does not destroy it until it is restarted or stopped. This means that the Function assigned to <code>b</code> is still available ''after'' the program finishes execution. Try it! Execute the program above, and then execute this single-line program alone: <code>b.value;</code></para></listitem>
+ <listitem><para><literal>a</literal> is declared just after the <literal>(</literal> character, so the interpreter destroys it upon reaching the <literal>)</literal> character.</para></listitem>
+ <listitem><para><literal>c</literal> is declared just after the <literal>{</literal> character, so the interpreter destroys it upon reaching the <literal>}</literal> character.</para></listitem>
+ <listitem><para><literal>b</literal> is <emphasis>not</emphasis> declared in this program, so it refers to the automatically-declared variable with that name. The interpreter does not destroy it until it is restarted or stopped. This means that the Function assigned to <literal>b</literal> is still available <emphasis>after</emphasis> the program finishes execution. Try it! Execute the program above, and then execute this single-line program alone: <code>b.value;</code></para></listitem>
</itemizedlist>
</para>
</section>
@@ -494,10 +496,10 @@ myFunction.value;
<para>
<application>SuperCollider</application> will always execute the inner-most Functions first. This is how the interpreter executes the single-line program above:
<orderedlist>
- <listitem><para>Execute the left call of <code>getinput</code></para></listitem>
- <listitem><para>Execute the right call of <code>getinput</code></para></listitem>
- <listitem><para>Execute <code>add</code> with the two numbers returned by <code>getinput</code></para></listitem>
- <listitem><para>Execute <code>postln</code> with the number returned by <code>add</code></para></listitem>
+ <listitem><para>Execute the left call of <function>getinput</function></para></listitem>
+ <listitem><para>Execute the right call of <function>getinput</function></para></listitem>
+ <listitem><para>Execute <function>add</function> with the two numbers returned by <function>getinput</function></para></listitem>
+ <listitem><para>Execute <function>postln</function> with the number returned by <function>add</function></para></listitem>
</orderedlist>
</para>
<para>
@@ -513,17 +515,17 @@ myFunction.value;
Class names always begin with an uppercase letter.
</para>
<para>
- Anything can be represented as an Object - like a bicycle, for instance. Let's pretend that we have an Object called a Bicycle. We don't yet have a particular bicycle - just the abstract '''class''' containing everything that is true about all bicycles. If a Bicycle class exists in <application>SuperCollider</application>, you generate a specific instance like this: <code>var bike = Bicycle.new;</code> All <application>SuperCollider</application> Objects can be '''instantiated''' in this way: you get a specific Bicycle from the generic class, and you can then modify and work with your own Object as you choose. The specific properties associated with a particular instance of a class are called '''instance variables'''.
+ Anything can be represented as an Object - like a bicycle, for instance. Let's pretend that we have an Object called a Bicycle. We don't yet have a particular bicycle - just the abstract <firstterm>class</firstterm> containing everything that is true about all bicycles. If a Bicycle class exists in <application>SuperCollider</application>, you generate a specific instance like this: <code>var bike = Bicycle.new;</code> All <application>SuperCollider</application> Objects can be <firstterm>instantiated</firstterm> in this way: you get a specific Bicycle from the generic class, and you can then modify and work with your own Object as you choose. The specific properties associated with a particular instance of a class are called <firstterm>instance variables</firstterm>.
</para>
<para>
- There are certain things that Bicycles are designed to do: turn the wheels, turn the handlebar, raise and lower the seat, and so on. You can cause these things to happen by providing a certain input to a real-world Bicycle: if you want to turn the wheels, you might push the pedals. In <application>SuperCollider</application>, you cause things to happen by '''sending a message''' to the Object that tells it what you want: if you have a Bicycle, you might turn the wheels like this: <code>bike.turnTheWheels;</code> When you do this, you are actually executing the <code>turnTheWheels</code> Function, which is defined by the abstract Bicycle class. Because it doesn't make sense to turn the wheels of all bicycles in existence, you don't call the '''method''' (a synonym for "Function") from the Bicycle class itself, but from the particular instance whose wheels you want to turn. The proper way to access instance variables is by using instance methods.
+ There are certain things that Bicycles are designed to do: turn the wheels, turn the handlebar, raise and lower the seat, and so on. You can cause these things to happen by providing a certain input to a real-world Bicycle: if you want to turn the wheels, you might push the pedals. In <application>SuperCollider</application>, you cause things to happen by <firstterm>sending a message</firstterm> to the Object that tells it what you want: if you have a Bicycle, you might turn the wheels like this: <code>bike.turnTheWheels;</code> When you do this, you actually execute the <function>turnTheWheels</function> function, which is defined by the abstract Bicycle class. Because it doesn't make sense to turn the wheels of all bicycles in existence, you don't call the <firstterm>method</firstterm> (a synonym for "Function") from the Bicycle class itself, but from the particular instance whose wheels you want to turn. The proper way to access instance variables is by using ins
tance methods.
</para>
<para>
- If this kind of programming is new to you, it might seem extremely difficult. It can be intimidating at first, but it is actually not too difficult to understand once you start to use it. In fact, you have already been using it! Remember the <code>postln</code> command that was described earlier as a special kind of Function? It's actually a Function defined by <application>SuperCollider</application>'s abstract class <code>Object</code>, which defines a set of messages that can be passed to ''any'' <application>SuperCollider</application> Object. Because most things in <application>SuperCollider</application> are Objects, we can send them the <code>postln</code> message, and they will understand that it means to print themselves in the "<application>SuperCollider</application> output" pane.
+ If this kind of programming is new to you, it might seem extremely difficult. It can be intimidating at first, but it is actually not too difficult to understand once you start to use it. In fact, you have already been using it! Remember the <function>postln</function> command that was described earlier as a special kind of Function? It's actually a Function defined by <application>SuperCollider</application>'s abstract class <classname>Object</classname>, which defines a set of messages that can be passed to <emphasis>any</emphasis> <application>SuperCollider</application> object. Because most things in <application>SuperCollider</application> are objects, we can send them the <function>postln</function> message, and they will understand that it means to print themselves in the "<application>SuperCollider</application> output" pane.
</para>
<para>
<!-- Begin Confusing??? (TODO) -->
- Why is it that all Objects respond to the <code>postln</code> message? <application>SuperCollider</application> classes are allowed to belong to other <application>SuperCollider</application> classes, of which they are a part. Consider the Bicycle class again. It is a kind of vehicle, and philosophers might say that "things that are members of the bicycle class are also members of the vehicle class." That is, real-world bicycles share certain characteristics with other real-world objects that are classified as "vehicles." The bicycle class is a "sub-class" of the vehicle class, and it '''inherits''' certain properties from the vehicles class. <application>SuperCollider</application> allows this behaviour too, and calls it '''inheritance'''. In <application>SuperCollider</application>, since all classes define Objects, they are all automatically considered to be a sub-class of the class called <code>Object</code>. All classes therefore inherit certain characterist
ics from the <code>Object</code> class, like knowing how to respond to the <code>postln</code> message.
+ Why is it that all Objects respond to the <function>postln</function> message? <application>SuperCollider</application> classes are allowed to belong to other <application>SuperCollider</application> classes, of which they are a part. Consider the Bicycle class again. It is a kind of vehicle, and philosophers might say that "things that are members of the bicycle class are also members of the vehicle class." That is, real-world bicycles share certain characteristics with other real-world objects that are classified as "vehicles." The bicycle class is a "sub-class" of the vehicle class, and it <firstterm>inherits</firstterm> certain properties from the vehicles class. <application>SuperCollider</application> allows this behaviour too, and calls it <firstterm>inheritance</firstterm>. In <application>SuperCollider</application>, since all classes define Objects, they are all automatically considered to be a sub-class of the class called <classname>Object</classname>.
All classes therefore inherit certain characteristics from the <classname>Object</classname> class, like knowing how to respond to the <function>postln</function> message.
<!-- End Confusing??? -->
</para>
<para>
@@ -575,31 +577,31 @@ myFunction.value;
"UGen" stands for "unit generator." UGens are special Objects that generate either an audio or a control signal.
</para>
<para>
- The UGen that will be used for most of the experimentation in this Guide, and which was primarily used to generate the "Method One" program that goes with this Guide, is called <code>SinOsc</code>, which generates a sine wave. The Class' name, "SinOsc," means "sine oscillator."
+ The UGen that will be used for most of the experimentation in this Guide, and which was primarily used to generate the "Method One" program that goes with this Guide, is called <classname>SinOsc</classname>, which generates a sine wave. The class' name, <classname>SinOsc</classname> means "sine oscillator."
</para>
<para>
- The example at the beginning of this chapter, <code>SinOsc.ar( 440, 0, 0.2 );</code> produces an "instance" of the <code>SinOsc</code> Class, which continuously outputs a signal, based on the parameters given in parentheses. This instance produces an "audio rate" signal, which means that it is of sufficient quality to eventually become sound.
+ The example at the beginning of this chapter, <code>SinOsc.ar( 440, 0, 0.2 );</code> produces an "instance" of the <classname>SinOsc</classname> class, which continuously outputs a signal, based on the parameters given in parentheses. This instance produces an "audio rate" signal, which means that it is of sufficient quality to eventually become sound.
</para>
<para>
A slightly modified version of that code will give us a "control rate" signal: <code>SinOsc.kr( 440, 0, 0.2 );</code> There is only one small difference between the two examples - for us - but for <application>SuperCollider</application>, the difference is huge. A control rate signal will not be of sufficient quality to become sound; it is used to control other UGens that do become sound.
</para>
<para>
- Unlike other Classes, UGen Classes should not be instantiated with the <code>new</code> message. They should always be instantiated as either audio-rate (by passing the <code>ar</code> message), or control-rate (by passing the <code>kr</code> message). Control-rate signals are calculated much less often than audio-rate signals, which allows the <application>SuperCollider</application> interpreter and server to save processing power where it wouldn't be noticed.
+ Unlike other Classes, UGen Classes should not be instantiated with the <function>new</function> message. They should always be instantiated as either audio-rate (by passing the <function>ar</function> message), or control-rate (by passing the <function>kr</function> message). Control-rate signals are calculated much less often than audio-rate signals, which allows the <application>SuperCollider</application> interpreter and server to save processing power where it wouldn't be noticed.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Sound_Making_Functions-The_play_Function">
<title>The "play" Function</title>
<para>
- The <code>play</code> Function does exactly what it says: it plays its input. The input must be a Function with an audio-rate signal generator as the return value.
+ The <function>play</function> function does exactly what it says: it plays its input. The input must be a function with an audio-rate signal generator as the return value.
</para>
<para>
The following two examples produce the same output:
<programlisting><![CDATA[{ SinOsc.ar( 440, 0, 0.2 ); }.play;]]></programlisting>
<programlisting><![CDATA[play( { SinOsc.ar( 440, 0, 0.2 ); } );]]></programlisting>
- The first example is written from an object-oriented perspective. Functions know how to play their return value, when passed the <code>play</code> message. This is true of all Functions whose return value is an audio-rate UGen. The second example is written from a functional perspective. The Function called <code>play</code> will play its input, which must be a Function whose return value is an audio-rate UGen. Whether you should write <code>play</code> in the functional or object-oriented way depends on which makes more sense to you.
+ The first example is written from an object-oriented perspective. Functions know how to play their return value, when passed the <function>play</function> message. This is true of all Functions whose return value is an audio-rate UGen. The second example is written from a functional perspective. The Function called <function>play</function> will play its input, which must be a Function whose return value is an audio-rate UGen. Whether you should write <function>play</function> in the functional or object-oriented way depends on which makes more sense to you.
</para>
<para>
- Try to re-write the above example so that the <code>play</code> Function operates on a variable-defined Function.
+ Try to re-write the above example so that the <function>play</function> function operates on a variable-defined Function.
<!--
(
var noise =
@@ -612,11 +614,11 @@ myFunction.value;
) -->
</para>
<para>
- The arguments to <code>SinOsc</code>, whether the audio- or control-rate generator, are these:
+ The arguments to <classname>SinOsc</classname>, whether the audio- or control-rate generator, are these:
<itemizedlist>
- <listitem><para>The first is called <code>freq</code>; it sets the frequency.</para></listitem>
- <listitem><para>The second is called <code>add</code>; it is added to all values produced by the UGen.</para></listitem>
- <listitem><para>The third is called <code>mul</code>; all values produced by the UGen are multiplied by this.</para></listitem>
+ <listitem><para>The first is called <literal>freq</literal>; it sets the frequency.</para></listitem>
+ <listitem><para>The second is called <literal>add</literal>; it is added to all values produced by the UGen.</para></listitem>
+ <listitem><para>The third is called <literal>mul</literal>; all values produced by the UGen are multiplied by this.</para></listitem>
</itemizedlist>
</para>
<para>
@@ -647,7 +649,7 @@ myFunction.value;
<para>
Here is our simple sine oscillator expanded to produce stereo audio:
<programlisting><![CDATA[{ [ SinOsc.ar( 440, 0, 0.2 ), SinOsc.ar( 440, 0, 0.2 ) ]; }.play;]]></programlisting>
- Not much has changed, except that the audio we hear is now being emitted from both the left and right channels. Change the frequency of one of the sine oscillators to <code>450</code> and the difference will become much more apparent.
+ Not much has changed, except that the audio we hear is now being emitted from both the left and right channels. Change the frequency of one of the sine oscillators to <literal>450</literal> and the difference will become much more apparent.
</para>
<para>
Multichannel arrays can also be combined with each other, like this:
@@ -658,7 +660,7 @@ myFunction.value;
[ one, two ];
}
]]></programlisting>
- If <code>a</code>, <code>b</code>, <code>c</code>, <code>x</code>, <code>y</code>, and <code>z</code> were all audio-rate UGens, this Function could be <code>play</code>'ed. It would produce stereo audio, and each channel would have three independent UGens.
+ If <literal>a</literal>, <literal>b</literal>, <literal>c</literal>, <literal>x</literal>, <literal>y</literal>, and <literal>z</literal> were all audio-rate UGens, this function could be <function>play</function>'ed. It would produce stereo audio, and each channel would have three independent UGens.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Multichannel_Audio-Multichannel_Expansion">
@@ -690,7 +692,7 @@ myFunction.value;
<section id="sect-Musicians_Guide-SC-Basic_Programming-Multichannel_Audio-Method_One">
<title>Method One</title>
<para>
- Believe it or not, you now know enough to understand a slightly-modified version of the first part of "Method One," a <application>SuperCollider</application> program written and heavily commented specifically for use with this Guide. You should <code>play</code> this example, and experiment with changing the frequencies, volumes, and so on. The fully-commented version provides a full explanation of how the Function works.
+ Believe it or not, you now know enough to understand a slightly-modified version of the first part of "Method One," a <application>SuperCollider</application> program written and heavily commented specifically for use with this guide. You should <function>play</function> this example, and experiment with changing the frequencies, volumes, and so on. The fully-commented version provides a full explanation of how the function works.
<programlisting><![CDATA[
{
// sets up the frequencies of both channels
@@ -727,7 +729,7 @@ myFunction.value;
A "collection" is just that - a collection of Objects. Collections are simply a means of organizing a large amount of data, without having to assign a variable name for each portion of data. Compared to other programming languages, <application>SuperCollider</application> provides a relatively large number of Collections in the standard library.
</para>
<para>
- We have already seen an example of a Collection as multichannel audio arrays. An Array is a kind of Collection - in object-oriented terminology, the Array Class is a '''sub-class''' of the Collection Class, and inherits its behaviours. Conversely, the Collection Class is the '''super-class''' of the Array Class. The Collection Class itself is not to be used; it is designed to provide common features so that it is easier to write Classes for collections.
+ We have already seen an example of a Collection as multichannel audio arrays. An Array is a kind of Collection - in object-oriented terminology, the Array Class is a <firstterm>sub-class</firstterm> of the Collection Class, and inherits its behaviours. Conversely, the Collection Class is the <firstterm>super-class</firstterm> of the Array Class. The Collection Class itself is not to be used; it is designed to provide common features so that it is easier to write Classes for collections.
</para>
<para>
As with all the chapters from this point on, it is not necessary to read this in sequence. If you prefer, you can skip it and return later when you need to manage a large set of data.
@@ -756,7 +758,7 @@ myFunction.value;
nil;
)
]]></programlisting>
- Notice that Array is a Class, and it must be instantiated before use. Here, the variable <code>tA</code> is assigned an Array with enough space for two objects. Notice that the elements are printed out in the order that you add them to the Array. They are not sorted or shuffled (unless you send a message like <code>scramble</code>). But why did I write <code>tA = tA.add( 17 );</code> instead of <code>tA.add( 17 );</code>? Shouldn't the second method be sufficient for adding an Object to an Array, thereby making the re-assignment unnecessary? It does, but let's see what happens when we take it away:
+ Notice that Array is a Class, and it must be instantiated before use. Here, the variable <literal>tA</literal> is assigned an Array with enough space for two objects. Notice that the elements are printed out in the order that you add them to the Array. They are not sorted or shuffled (unless you send a message like <function>scramble</function>). But why did I write <code>tA = tA.add( 17 );</code> instead of <code>tA.add( 17 );</code>? Shouldn't the second method be sufficient for adding an Object to an Array, thereby making the re-assignment unnecessary? It does, but let's see what happens when we take it away:
<programlisting><![CDATA[
(
var tA = Array.new( 2 ); // "tA" stands for "testArray"
@@ -769,13 +771,13 @@ myFunction.value;
nil;
)
]]></programlisting>
- The <code>17</code> is missing - it doesn't get added into the Array! This is because the Array was only declared with two slots, and you can't add three Objects into two slots. So why did this work the first time? <application>SuperCollider</application> was programmed to help us fit additional items into an Array. If an Array has reached its capacity, <application>SuperCollider</application> will automatically make a new, larger Array for us, and returns that from the <code>add</code> method. Therefore, any time you add an element to an Array, you should always re-assign the result, so that you don't have to worry about whether you exceeded the Array's capacity.
+ The <literal>17</literal> is missing - it doesn't get added into the Array! This is because the Array was only declared with two slots, and you can't add three Objects into two slots. So why did this work the first time? <application>SuperCollider</application> was programmed to help us fit additional items into an Array. If an Array has reached its capacity, <application>SuperCollider</application> will automatically make a new, larger Array for us, and returns that from the <function>add</function> method. Therefore, any time you add an element to an Array, you should always re-assign the result, so that you don't have to worry about whether you exceeded the Array's capacity.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections-Array-Accessing">
<title>Accessing an Array's Elements</title>
<para>
- There are two ways to access individual elements within an Array. One way is object-oriented, and one way is more traditional, inspired by programming languages such as the wildly popular "C" language. The object-oriented style uses the <code>at</code> and <code>put</code> methods. The traditional style uses square brackets with an index number.
+ There are two ways to access individual elements within an Array. One way is object-oriented, and one way is more traditional, inspired by programming languages such as the wildly popular "C" language. The object-oriented style uses the <function>at</function> and <function>put</function> methods. The traditional style uses square brackets with an index number.
</para>
<para>
The following examples produce equivalent output. The first uses the object-oriented style, and the second uses the traditional style.
@@ -831,10 +833,10 @@ myFunction.value;
<para>
There are four methods which instantiate a List. These are all "Class methods," meaning they do not operate on a specific List, but can be used to make any List.
<itemizedlist>
- <listitem><para><code>List.new</code> creates a List. You can also specify the initial number of elements as an argument, if you choose.</para></listitem>
- <listitem><para><code>List.newClear( x )</code> creates a List with x number of slots, filled with <code>nil</code>.</para></listitem>
- <listitem><para><code>List.copyInstance( aList )</code> creates a List which is a copy of <code>aList</code>.</para></listitem>
- <listitem><para><code>List.newUsing( anArray )</code> creates a List with the same elements as <code>anArray</code>.</para></listitem>
+ <listitem><para><function>List.new</function> creates a List. You can also specify the initial number of elements as an argument, if you choose.</para></listitem>
+ <listitem><para><function>List.newClear( <replaceable>x</replaceable> )</function> creates a List with <literal>x</literal> number of slots, filled with <literal>nil</literal>.</para></listitem>
+ <listitem><para><function>List.copyInstance( <replaceable>aList</replaceable> )</function> creates a List which is a copy of <literal>aList</literal>.</para></listitem>
+ <listitem><para><function>List.newUsing( <replaceable>anArray</replaceable> )</function> creates a List with the same elements as <literal>anArray</literal>.</para></listitem>
</itemizedlist>
</para>
</section>
@@ -843,9 +845,9 @@ myFunction.value;
<para>
These are "instance methods," meaning that they operate on a specific list.
<itemizedlist>
- <listitem><para><code>put( index, item )</code> adds "item" into the List at index number "index".</para></listitem>
- <listitem><para><code>add( item )</code> adds "item" to the end of a List.</para></listitem>
- <listitem><para><code>addFirst( item )</code> adds "item" to the beginning of a List.</para></listitem>
+ <listitem><para><function>put( <replaceable>index</replaceable>, <replaceable>item</replaceable> )</function> adds <literal>item</literal> into the List at index number <literal>index</literal>.</para></listitem>
+ <listitem><para><function>add( <replaceable>item</replaceable> )</function> adds <literal>item</literal> to the end of a List.</para></listitem>
+ <listitem><para><function>addFirst( <replaceable>item</replaceable> )</function> adds <literal>item</literal> to the beginning of a List.</para></listitem>
</itemizedlist>
</para>
</section>
@@ -854,20 +856,20 @@ myFunction.value;
<para>
These are "instance methods," meaning that they operate on a specific list.
<itemizedlist>
- <listitem><para><code>at( index )</code> returns the Object assigned to the "index" index number. If "index" is greater than the last element in the List, returns "nil".</para></listitem>
- <listitem><para><code>clipAt( index )</code> returns the Object assigned to the "index" index number. If "index" is greater than the last element in the List, returns the last element in the List.</para></listitem>
- <listitem><para><code>wrapAt( index )</code> returns the Object assigned to the "index" index number. If "index" is greater than the last element in the List, returns an element based on a "wrap-around" index number. For a three-element List, 0 will return element 0, 1 returns 1, 2 returns 2, 3 returns 0, 4 returns 1, 5 returns 2, 6 returns 0, and so on.</para></listitem>
- <listitem><para><code>foldAt( index )</code> returns the Object assigned to the "index" index number. If "index" is greater than the last element in the List, returns an element based on a "fold-back" index number. Whereas <code>wrapAt()</code> will always continue from the lowest to the highest index number, <code>foldAt()</code> will change every time: low to high, high to low, low to high, and so on.</para></listitem>
+ <listitem><para><function>at( <replaceable>index</replaceable> )</function> returns the Object assigned to the <literal>index</literal> index number. If <literal>index</literal> is greater than the last element in the List, returns <literal>nil</literal>.</para></listitem>
+ <listitem><para><function>clipAt( <replaceable>index</replaceable> )</function> returns the Object assigned to the <literal>index</literal> index number. If <literal>index</literal> is greater than the last element in the List, returns the last element in the List.</para></listitem>
+ <listitem><para><function>wrapAt( <replaceable>index</replaceable> )</function> returns the Object assigned to the <literal>index</literal> index number. If <literal>index</literal> is greater than the last element in the List, returns an element based on a "wrap-around" index number. For a three-element List, <literal>0</literal> will return element <literal>0</literal>, <literal>1</literal> returns <literal>1</literal>, <literal>2</literal> returns <literal>2</literal>, <literal>3</literal> returns <literal>0</literal>, <literal>4</literal> returns <literal>1</literal>, <literal>5</literal> returns <literal>2</literal>, <literal>6</literal> returns <literal>0</literal>, and so on.</para></listitem>
+ <listitem><para><function>foldAt( <replaceable>index</replaceable> )</function> returns the Object assigned to the <literal>index</literal> index number. If <literal>index</literal> is greater than the last element in the List, returns an element based on a "fold-back" index number. Whereas <function>wrapAt()</function> always continues from the lowest to the highest index number, <function>foldAt()</function> changes every time: low to high, high to low, low to high, and so on.</para></listitem>
</itemizedlist>
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Collections-List-Removing">
<title>Removing from a List</title>
<para>
- One way to remove an element from a List is to re-assign that element's index number the value "nil". These two Functions also remove elements from a List. They are "instance methods," meaning that they operate on a specific list.
+ One way to remove an element from a List is to re-assign that element's index number the value <literal>nil</literal>. These two Functions also remove elements from a List. They are "instance methods," meaning that they operate on a specific list.
<itemizedlist>
- <listitem><para><code>pop</code> returns the last element in a List, and removes it from the List.</para></listitem>
- <listitem><para><code>removeAt( index )</code> removes the element assigned to "index" index number, removing it from the List and shrinking the List. This will not leave a "nil" element in the List.</para></listitem>
+ <listitem><para><function>pop</function> returns the last element in a List, and removes it from the List.</para></listitem>
+ <listitem><para><function>removeAt( <replaceable>index</replaceable> )</function> removes the element assigned to <literal>index</literal> index number, removing it from the List and shrinking the List. <function>removeAt()</function> does not leave a <literal>nil</literal> element in the List.</para></listitem>
</itemizedlist>
</para>
</section>
@@ -1048,7 +1050,7 @@ myFunction.value;
Knowing when to use a LinkedList over a List is a question of efficiency, and for small collections of information, it isn't going to make a big difference - you might as well use a basic List. When you plan to store hundreds or thousands of elements, choosing the right Class becomes more important, and can save a lot of processor time. Here is how to know which Class you should use:
<itemizedlist>
<listitem><para>If you're going to be adding elements to the start or end of the list, and accessing from the start or end of the list, the LinkedList Class will be more efficient.</para></listitem>
- <listitem><para>If you're going to be adding elements at arbitrary index numbers ''inside'' the list, and accessing elements at arbitrary index numbers inside the list, the List Class will be more efficient.</para></listitem>
+ <listitem><para>If you're going to be adding elements at arbitrary index numbers <emphasis>inside</emphasis> the list, and accessing elements at arbitrary index numbers inside the list, the List Class will be more efficient.</para></listitem>
<listitem><para>If you're going to be adding elements to the start or end, but accessing specific indices, or adding elements at specific indices, but accessing from the start or end, then you get to choose where to save computation time. In one of these cases, it might not matter which one you choose.</para></listitem>
</itemizedlist>
</para>
@@ -1057,12 +1059,12 @@ myFunction.value;
<para>
These Functions make use of the LinkedList Class in an efficient way. They are efficient because they access only the first or last element in the LinkedList.
<itemizedlist>
- <listitem><para><code>add( obj )</code> adds "obj" to a LinkedList as the last item.</para></listitem>
- <listitem><para><code>addFirst( obj )</code> adds "obj" to a LinkedList as the first item.</para></listitem>
- <listitem><para><code>pop</code> removes the last item in a LinkedList and returns it.</para></listitem>
- <listitem><para><code>popFirst</code> removes the first item in a LinkedList and returns it.</para></listitem>
- <listitem><para><code>first</code> returns a copy of the first item in a LinkedList.</para></listitem>
- <listitem><para><code>last</code> returns a copy of the last item in a LinkedList.</para></listitem>
+ <listitem><para><function>add( <replaceable>obj</replaceable> )</function> adds <literal>obj</literal> to a LinkedList as the last item.</para></listitem>
+ <listitem><para><function>addFirst( <replaceable>obj</replaceable> )</function> adds <literal>obj</literal> to a LinkedList as the first item.</para></listitem>
+ <listitem><para><function>pop</function> removes the last item in a LinkedList and returns it.</para></listitem>
+ <listitem><para><function>popFirst</function> removes the first item in a LinkedList and returns it.</para></listitem>
+ <listitem><para><function>first</function> returns a copy of the first item in a LinkedList.</para></listitem>
+ <listitem><para><function>last</function> returns a copy of the last item in a LinkedList.</para></listitem>
</itemizedlist>
</para>
</section>
@@ -1071,10 +1073,10 @@ myFunction.value;
<para>
These Functions make use of the LinkedList Class in an inefficient way, but they can be useful. They are inefficient because they may potentially have to review all of the elements in a LinkedList before completing.
<itemizedlist>
- <listitem><para><code>at( index )</code> pretends the LinkedList is an Array, and returns a copy of what would be the element at the given index number.</para></listitem>
- <listitem><para><code>put( index, obj )</code> pretends the LinkedList is an Array, and changes the element at the given index number to be "obj."</para></listitem>
- <listitem><para><code>remove( obj )</code> searches through a LinkedList and removes the element judged to be equal to "obj," regardless of its index number.</para></listitem>
- <listitem><para><code>removeAt( index )</code> pretends the LinkedList is an Array, and removes the element located at the given index number.</para></listitem>
+ <listitem><para><function>at( <replaceable>index</replaceable> )</function> pretends the LinkedList is an Array, and returns a copy of what would be the element at the given index number.</para></listitem>
+ <listitem><para><function>put( <replaceable>index</replaceable>, <replaceable>obj</replaceable> )</function> pretends the LinkedList is an Array, and changes the element at the given index number to be <literal>obj</literal>.</para></listitem>
+ <listitem><para><function>remove( <replaceable>obj</replaceable> )</function> searches through a LinkedList and removes the element judged to be equal to <literal>obj</literal>, regardless of its index number.</para></listitem>
+ <listitem><para><function>removeAt( <replaceable>index</replaceable> )</function> pretends the LinkedList is an Array, and removes the element located at the given index number.</para></listitem>
</itemizedlist>
</para>
</section>
@@ -1126,7 +1128,7 @@ myFunction.value;
Repeating boring tasks is one of the main uses of computers, which don't mind doing the same thing over and over again. More importantly, writing code once and using it many times is much more intelligent than writing the same code many times. Repetition of the same code is often problematic, and repetition with subtle differences is even worse. Errors in this kind of code are difficult to find in the first place, and more difficult to solve effectively. Thankfully, as with most other things, <application>SuperCollider</application> offers a wide variety of ways to repeat code without re-writing it.
</para>
<para>
- The code structure used to create repetition is normally called a '''loop'''. "Do" loops are <application>SuperCollider</application>'s most versatile and useful repetition structure, and there are a few different ways to think about and write it. The "while" loop is a standard of most programming languages.
+ The code structure used to create repetition is normally called a <firstterm>loop</firstterm>. "Do" loops are <application>SuperCollider</application>'s most versatile and useful repetition structure, and there are a few different ways to think about and write it. The "while" loop is a standard of most programming languages.
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Repeating-Simple_Do">
<title>"Do This to Everything in This Collection"</title>
@@ -1178,7 +1180,7 @@ myFunction.value;
nil;
)
]]></programlisting>
- This example is of the first syntax shown. For each element in <code>tL</code>, the interpreter executes the Function once, giving it ''first'' the corresponding element of the Collection, and ''then'' the iteration counter, which happens to be equal to the element's List index number.
+ This example is of the first syntax shown. For each element in <literal>tL</literal>, the interpreter executes the function once, giving it <emphasis>first</emphasis> the corresponding element of the Collection, and <emphasis>then</emphasis> the iteration counter, which happens to be equal to the element's List index number.
</para>
<para>
<programlisting><![CDATA[
@@ -1197,7 +1199,7 @@ myFunction.value;
nil;
)
]]></programlisting>
- This example does several things differently, but maintains the same basic functionality as the previous example. In this case, the Function only uses the first argument that the interpreter provides, and completely ignores the iteration counter. The syntax here also puts the Collection outside the parentheses, which perhaps makes it more clear that <code>tL</code> is not part of the Function.
+ This example does several things differently, but maintains the same basic functionality as the previous example. In this case, the Function only uses the first argument that the interpreter provides, and completely ignores the iteration counter. The syntax here also puts the Collection outside the parentheses, which perhaps makes it more clear that <literal>tL</literal> is not part of the function.
</para>
<para>
<programlisting><![CDATA[
@@ -1231,7 +1233,7 @@ myFunction.value;
<paramdef><replaceable>bodyFunction</replaceable><funcparams>number</funcparams></paramdef>
</funcprototype>
</funcsynopsis>
- The test condition, called <code>testFunc</code>, is a Function which returns a boolean value - either "true" or "false". The loop's body, called <code>bodyFunc</code>, is a Function which can do anything. The loop body function is not provided any arguments by the interpreter. You will have to use comparison operators and boolean expressions when writing the Function for the test condition. For information on how these work in <application>SuperCollider</application>, see <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Boolean_Operators" /> and <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Boolean_Expressions" />.
+ The test condition, called <function>testFunc</function>, is a function which returns a boolean value - either <literal>true</literal> or <literal>false</literal>. The loop's body, called <function>bodyFunc</function>, is a function which can do anything. The loop body function is not provided any arguments by the interpreter. You will have to use comparison operators and boolean expressions when writing the Function for the test condition. For information on how these work in <application>SuperCollider</application>, see <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Boolean_Operators" /> and <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Boolean_Expressions" />.
</para>
<para>
The following three code blocks are equivalent:
@@ -1263,7 +1265,7 @@ play( some background music );
while( { is the user still inputting information? }, { keep playing music } );
stop( some background music );
]]></programlisting>
- The background music is begun, and then the interpreter would enter the loop. For as long as the user is still inputting information, the interpreter will then "keep playing music." When the user is not still inputting information, the interpreter will move on to the next command, which stops the music. An equivalent "do" loop would be very difficult to write, if not impossible. This is because we won't know when the user has finished inputting their information until ''after'' they've finished, so we can't plan in advance for how long to play background music.
+ The background music is begun, and then the interpreter would enter the loop. For as long as the user is still inputting information, the interpreter will then "keep playing music." When the user is not still inputting information, the interpreter will move on to the next command, which stops the music. An equivalent "do" loop would be very difficult to write, if not impossible. This is because we won't know when the user has finished inputting their information until <emphasis>after</emphasis> they've finished, so we can't plan in advance for how long to play background music.
</para>
<para>
Thus, the most appropriate use of a "while" loop is for cases where you cannot know in advance how many times something should be executed. For most other cases of repeated execution, a "do" loop is the most appropriate choice.
@@ -1434,7 +1436,7 @@ a = 42; // assigns the value 42 to "a", over-writing the previously-stored value
a === b; // evaluates to "false"
)
]]></programlisting>
- The <code>==</code> operator evaluates to <literal>true</literal> because <literal>a</literal> and <literal>b</literal> represent equivalent Objects - they are equal. The <code>===</code> operator evaluates to <literal>false</literal> because <literal>a</literal> and <literal>b</literal> represent different instances of the Objects - they are not identical.
+ The <literal>==</literal> operator evaluates to <literal>true</literal> because <literal>a</literal> and <literal>b</literal> represent equivalent Objects - they are equal. The <literal>===</literal> operator evaluates to <literal>false</literal> because <literal>a</literal> and <literal>b</literal> represent different instances of the Objects - they are not identical.
<programlisting><![CDATA[
(
var a = [12,24,48];
@@ -1444,13 +1446,13 @@ a = 42; // assigns the value 42 to "a", over-writing the previously-stored value
a === b; // evaluates to "true"
)
]]></programlisting>
- In this case, the <code>==</code> operator still evaluates to <literal>true</literal>. The <code>===</code> operator also evaluates to <literal>true</literal>, because <literal>a</literal> and <literal>b</literal> both represent the same Object. When the interpreter evaluates <code>var b = a;</code> in the example above, it actually assigns <literal>b</literal> the same value that <literal>a</literal> stores, not a copy of it.
+ In this case, the <literal>==</literal> operator still evaluates to <literal>true</literal>. The <literal>===</literal> operator also evaluates to <literal>true</literal>, because <literal>a</literal> and <literal>b</literal> both represent the same Object. When the interpreter evaluates <code>var b = a;</code> in the example above, it actually assigns <literal>b</literal> the same value that <literal>a</literal> stores, not a copy of it.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Conditional_Execution-Logical_And_and_Or">
<title>Logical <literal>And</literal> and <literal>Or</literal></title>
<para>
- The logical And and Or operators must receive two boolean arguments. Logical And returns "true" if both of its arguments are "true". Logical Or returns "true" if one of its arguments are "true".
+ The logical And and Or operators must receive two boolean arguments. Logical And returns <literal>true</literal> if both of its arguments are <literal>true</literal>. Logical Or returns <literal>true</literal> if one of its arguments are <literal>true</literal>.
</para>
<para>
The following table illustrates how the <application>SuperCollider</application> interpreter will evaluate each of the following situations.
@@ -1499,7 +1501,7 @@ a = 42; // assigns the value 42 to "a", over-writing the previously-stored value
</table>
</para>
<para>
- The interpreter evaluates the expression on the left first, and then the expression on the right ''only'' if it will influence the outcome. This means that, if the left-side expression of a logical Or operator evaluates to "true", the interpreter will not test the right-side expression, because the result will be "true" anyway. Similarly, if the left-side expression of a logical And operator evaluates to "false", the interpreter will not test the right-side expression, because the result will be "false" anyway.
+ The interpreter evaluates the expression on the left first, and then the expression on the right <emphasis>only</emphasis> if it will influence the outcome. This means that, if the left-side expression of a logical Or operator evaluates to "true", the interpreter will not test the right-side expression, because the result will be "true" anyway. Similarly, if the left-side expression of a logical And operator evaluates to "false", the interpreter will not test the right-side expression, because the result will be "false" anyway.
</para>
<para>
This can be exploited to help avoid errors like division-by-zero.
@@ -1557,7 +1559,7 @@ a = 42; // assigns the value 42 to "a", over-writing the previously-stored value
<programlisting><![CDATA[if ( booleanExpression, trueFunction, falseFunction );]]></programlisting>
and
<programlisting><![CDATA[booleanExpression.if( trueFunction, falseFunction );]]></programlisting>
- It's possible to exclude the <code>falseFunction</code>, which is like telling the interpreter, "If the boolean expression is true, then execute this Function. Otherwise, don't execute it."
+ It's possible to exclude the <function>falseFunction</function>, which is like telling the interpreter, "If the boolean expression is true, then execute this Function. Otherwise, don't execute it."
</para>
<para>
<programlisting><![CDATA[
@@ -1568,10 +1570,10 @@ a = 42; // assigns the value 42 to "a", over-writing the previously-stored value
nil;
)
]]></programlisting>
- This example prints out a nice message, saying whether <code>test</code> is "true" or "false". Because <code>test</code> is already a boolean value, we don't need to include it in an expression. The "if" statement could have been shortened like this: <code>if ( test, { "It's true!".postln; }, { "It's false!".postln; } );</code>
+ This example prints out a nice message, saying whether <literal>test</literal> is <literal>true</literal> or <literal>false</literal>. Because <literal>test</literal> is already a boolean value, we don't need to include it in an expression. The "if" statement could have been shortened like this: <code>if ( test, { "It's true!".postln; }, { "It's false!".postln; } );</code>
</para>
<para>
- Suppose we only wanted to be alerted if <code>test</code> is "true".
+ Suppose we only wanted to be alerted if <literal>test</literal> is <literal>true</literal>.
<programlisting><![CDATA[
(
var test = [true,false].choose; // pseudo-randomly chooses one of the elements in the List
@@ -1661,7 +1663,7 @@ case( compareThis,
nil;
)
]]></programlisting>
- The code picks a pseudo-random number between 1 and 12, then uses a "switch" structure to convert that number into a letter-grade, assigning it to the same <code>grade</code> variable. Then, it adds the "Your grade is" string to the value of <code>grade</code> (with a space between), and prints that result.
+ The code picks a pseudo-random number between 1 and 12, then uses a "switch" structure to convert that number into a letter-grade, assigning it to the same <literal>grade</literal> variable. Then, it adds the "Your grade is" string to the value of <literal>grade</literal> (with a space between), and prints that result.
</para>
<para>
This example avoids the complex nested "if" structure from above.
@@ -1685,10 +1687,10 @@ case( compareThis,
nil;
)
]]></programlisting>
- This is an elegant way to inspect two otherwise-separate variables. Remember that the first argument to "switch" (in this case, it's <code>[testA,tesB]</code>) is compared to the first argument of possibe result with the equality operator: "==".
+ This is an elegant way to inspect two otherwise-separate variables. Remember that the first argument to "switch" (in this case, it's <code>[testA,tesB]</code>) is compared to the first argument of possibe result with the equality operator: <literal>==</literal>
</para>
<para>
- When evaluating which switch to use, the <application>SuperCollider</application> interpreter will always apply the ''last'' one that evaluates to "true".
+ When evaluating which switch to use, the <application>SuperCollider</application> interpreter will always apply the <emphasis>last</emphasis> one that evaluates to <literal>true</literal>.
<programlisting><![CDATA[
(
switch( 5,
@@ -1743,7 +1745,7 @@ case
( 5 == 5 ).while( coolFunction ); // executes coolFunction contiuously
)
]]></programlisting>
- It might seem like this example doesn't relate to a real <application>SuperCollider</application> programming situation, but in fact it might. If you could program Function's which determined all of those questions and all of the answers, this sort of "case" structure would be very helpful in a situation where a computer running <application>SuperCollider</application> were left in a room by itself, and expected to play music whenever anybody entered the room. Since five is always equal to five, the interpreter will run <code>coolFunction</code> forever. If the music needs adjustment in some way, the Function will adjust the music. If everything is okay, then the interpreter will wait for 10 seconds, and then the loop will cause the Function to be re-evaluated. Because many different criteria are evaluated in the "case" structure, this represents an efficient use of the structure.
+ It might seem like this example doesn't relate to a real <application>SuperCollider</application> programming situation, but in fact it might. If you could program Function's which determined all of those questions and all of the answers, this sort of "case" structure would be very helpful in a situation where a computer running <application>SuperCollider</application> were left in a room by itself, and expected to play music whenever anybody entered the room. Since five is always equal to five, the interpreter will run <function>coolFunction</function> forever. If the music needs adjustment in some way, the Function will adjust the music. If everything is okay, then the interpreter will wait for 10 seconds, and then the loop will cause the Function to be re-evaluated. Because many different criteria are evaluated in the "case" structure, this represents an efficient use of the structure.
</para>
<para>
"Case" structures can be used to do the same thing as "switch" structures, but it's usually less elegant solution. Also, it doesn't allow the interpreter to use an speed optimization that it would have used in an equivalent "switch" structure.
@@ -1774,7 +1776,7 @@ case
This example is equivalent to one of the "switch" structure examples. This is not a good use of the "case" structure, because it requires a lot of code repetition.
</para>
<para>
- Unlike a "switch" structure, a "case" structure will always follow the ''first'' case that evaluates to "true".
+ Unlike a "switch" structure, a "case" structure will always follow the <emphasis>first</emphasis> case that evaluates to "true".
<programlisting><![CDATA[
(
case
@@ -1834,10 +1836,10 @@ case
SinOsc.ar(1000, 0, 0.1)] );
}.play;
]]></programlisting>
- Notice how all of these SinOsc's are heard through the left channel only. The "Mix" Class mixes all the UGen's together into one. You could use a bus to send the audio to both the left and right channels. What happens if we don't use the Mix Class? Try removing the Function, and find out. You only hear some of the SinOsc's. Which ones? The first two, representing the left and right channels. If your audio interface has more than two channels, you may be able to hear more than those first two channels.
+ Notice how all of these <classname>SinOsc</classname>s are heard through the left channel only. The <classname>Mix</classname> class mixes all the UGen's together into one. You could use a bus to send the audio to both the left and right channels. What happens if we don't use the <classname>Mix</classname> class? Try to remove the function, and find out. You only hear some of the <classname>SinOsc</classname>'s. Which ones? The first two, representing the left and right channels. If your audio interface has more than two channels, you may be able to hear more than those first two channels.
</para>
<para>
- There is another Function offered by the Mix Class, and it is a kind of loop. The Function is called <code>Fill</code>, and it takes two arguments: the number of times to run a Function, and the Function to run. The Function is provided with one argument (like in a "do" loop), which is the number of times the Function has ''already'' been run.
+ There is another function offered by the <classname>Mix</classname> class, and it is a kind of loop. The function is called <function>Fill</function>, and it takes two arguments: the number of times to run a function, and the function to run. The function is provided with one argument (like in a "do" loop), which is the number of times the function has <emphasis>already</emphasis> been run.
<programlisting><![CDATA[
(
var n = 8;
@@ -1852,7 +1854,7 @@ case
{ Mix.fill( n, sineFunc ); }.play;
)
]]></programlisting>
- As you can see, the "fill" Function itself is quite simple: you provide the number of UGen's to create, and a Function that creates UGen's. It's the <code>sineFunc</code> Function that is a little confusing. The argument is called "iteration", because it holds how many times the Function has already been run - how many iterations have happened already. It uses this value to help calculate the frequency (stored in a variable called "freq"), and then creates a SinOsc UGen. The "mul" argument helps to automatically control the volume level. Since the total volume should be no more than 1.0, the "sineFunc" Function calculates UGen's' volume by dividing 1, the maximum level, by the number of UGen's that will be created. The slowly pulsating volume is part of the acoustic result of this many frequencies being so close together - it is not a hidden effect by <application>SuperCollider</application>.
+ As you can see, the <function>fill</function> function itself is quite simple: you provide the number of UGen's to create, and a function that creates UGen's. It's the <literal>sineFunc</literal> function that is a little confusing. The argument is called "iteration", because it holds how many times the function has already been run - how many iterations have happened already. It uses this value to help calculate the frequency (stored in a variable called <literal>freq</literal>), and then creates a <classname>SinOsc</classname> UGen. The <literal>mul</literal> argument helps to automatically control the volume level. Since the total volume should be no more than 1.0, the <function>sineFunc</function> function calculates UGen's' volume by dividing 1, the maximum level, by the number of UGen's that will be created. The slowly pulsating volume is part of the acoustic result of this many frequencies being so close together - it is not a hidden effect by <application>S
uperCollider</application>.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Combining_and_Mix-Arrays_of_Arrays">
@@ -1960,13 +1962,13 @@ case
</para>
<para>
There are two steps to creating a useful SynthDef: making an interpreter Object, and sending the actual synthesis information to the server. There are two ways to write this, as follows:
-<programlisting><![CDATA[
-someVariable = SynthDef.new( nameOfSynthDef, FunctionContainingOutUGen );
-someVariable.send( nameOfServer );
-]]></programlisting>
+<programlisting>
+<replaceable>someVariable</replaceable> = SynthDef.new( <replaceable>nameOfSynthDef</replaceable>, <replaceable>FunctionContainingOutUGen</replaceable> );
+<replaceable>someVariable</replaceable>.send( <replaceable>nameOfServer</replaceable> );
+</programlisting>
and
- <programlisting><![CDATA[SynthDef.new( nameOfSynthDef, FunctionContainingOutUGen ).send( nameOfServer );]]></programlisting>
- The <code>FunctionContainingOutUGen</code> is simply that - a Function that, when executed, returns an "Out" UGen (meaning that the "Out" UGen must be the last expression in the Function). The <code>nameOfSynthDef</code> should be a symbol (as described in <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-SynthDef_and_Synth-Symbols" />), but can also be a string. The <code>nameOfServer</code> is a variable that represents the server to which you want to send the SynthDef's information; unless you know that you need to use a different variable for this, it's probably just the letter "s", which the interpreter automatically assigns to the default server.
+<programlisting>SynthDef.new( <replaceable>nameOfSynthDef</replaceable>, <replaceable>FunctionContainingOutUGen</replaceable> ).send( <replaceable>nameOfServer</replaceable> );</programlisting>
+ The <function>FunctionContainingOutUGen</function> is simply that - a function that, when executed, returns an <classname>Out</classname> UGen (meaning that the <classname>Out</classname> UGen must be the last expression in the function). The <literal>nameOfSynthDef</literal> should be a symbol (as described in <xref linkend="sect-Musicians_Guide-SC-Basic_Programming-SynthDef_and_Synth-Symbols" />), but can also be a string. The <literal>nameOfServer</literal> is a variable that represents the server to which you want to send the SynthDef's information; unless you know that you need to use a different variable for this, it's probably just the letter "s", which the interpreter automatically assigns to the default server.
</para>
<para>
Here is a demonstration of both methods:
@@ -2073,7 +2075,7 @@ c === d; \\ returns "true" because the symbols are identical
<paramdef><parameter>nameOfSynthDef</parameter></paramdef>
</funcprototype>
</funcsynopsis>
- The name will be a symbol or a string - whatever you supplied when you ran the <code>SynthDef.new()</code> Function.
+ The name will be a symbol or a string - whatever you supplied when you ran the <function>SynthDef.new()</function> function.
</para>
<para>
Because we're creating a new Synth Object, we should assign it to a variable, for later reference.
@@ -2085,7 +2087,7 @@ var mySynth = Synth.new( \playMe );
<para>
Recall that the interpreter automatically uses the Synth and SynthDef Classes when we send the "play" message to a Function. We can actually capture and use the Synth Object created from "play-ing" a Function, too. This example is almost the same as the previous one.
<programlisting><![CDATA[var mySynth = { SinOsc.ar( freq:443, mul:0.2 ); }.play;]]></programlisting>
- The difference is subtle: after the second example, we have no control over what name the interpreter gives to the SynthDef that it sends to the server, so we can't re-use the SynthDef. On the other hand, because we assign the name <code>\sillyTutorialSD</code> to the SynthDef in the first example, we know what it's called, and we can re-use it. Theoretically, we can make an infinite number of synths from this single definition. Realistically, it's limited by the amount of memory the server can use; for most modern computers, this number is so high that we don't ever need to worry about it.
+ The difference is subtle: after the second example, we have no control over what name the interpreter gives to the SynthDef that it sends to the server, so we can't re-use the SynthDef. On the other hand, because we assign the name <literal>\sillyTutorialSD</literal> to the SynthDef in the first example, we know what it's called, and we can re-use it. Theoretically, we can make an infinite number of synths from this single definition. Realistically, it's limited by the amount of memory the server can use; for most modern computers, this number is so high that we don't ever need to worry about it.
</para>
<para>
As usual, the interpreter provides us with an optional short-cut:
@@ -2125,10 +2127,10 @@ var mySynth = Synth.new( \playMe );
10.do( { Synth.new( \myRandFunc ); } );
)
]]></programlisting>
- Execute the program a few times. The result is still different each time, but it's the ''same'' ten SinOsc's, all with the same frequency. This is the nature of a SynthDef: once it's sent to the server, you can create a synth from the same instructions without re-sending them.
+ Execute the program a few times. The result is still different each time, but it's the <emphasis>same</emphasis> ten SinOsc's, all with the same frequency. This is the nature of a SynthDef: once it's sent to the server, you can create a synth from the same instructions without resending them.
</para>
<para>
- This program causes an error the first time you run it. Inspect the error messages, and see if you can determine why. It's because the server is processing commands ''asynchronously'': things don't happen right when the interpreter asks, but very shortly thereafter. The result is that the server is asked to make a new synth before it deals with the synth definition. There are ways to get around this, but they're too complex for this section - for now (to simplify this text's examples), just accept that the error may happen the first time you run a Synth.
+ This program causes an error the first time you run it. Inspect the error messages, and see if you can determine why. It's because the server is processing commands <emphasis>asynchronously</emphasis>: things don't happen right when the interpreter asks, but very shortly thereafter. The result is that the server is asked to make a new synth before it deals with the synth definition. There are ways to get around this, but they're too complex for this section - for now (to simplify this text's examples), just accept that the error may happen the first time you run a Synth.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Basic_Programming-SynthDef_and_Synth-Creating_Change_Anyway">
@@ -2184,7 +2186,7 @@ var mySynth = Synth.new( \playMe );
</tbody>
</tgroup>
</table>
- For an audio-rate SinOsc UGen, you set the frequency and the volume level. For a control-rate UGen, you set the mid-point of oscillation with "add", the extremes of oscillation which will be <code>add - mul</code> and <code>add + mul</code>, and the speed of oscillation with "freq". The end result is very different numbers.
+ For an audio-rate SinOsc UGen, you set the frequency and the volume level. For a control-rate UGen, you set the mid-point of oscillation with <literal>add</literal>, the extremes of oscillation which will be <code>add - mul</code> and <code>add + mul</code>, and the speed of oscillation with <literal>freq</literal>. The end result is very different numbers.
</para>
<para>
There is a handy UGen designed specifically for replacing pseudo-randomness in Functions. The following example restores the "ten different pitches" to the example from the last section.
@@ -2498,18 +2500,18 @@ h.do( { arg item; item.set( \frequency, (440.rand + 440) ); } );
]]></programlisting>
This example contains three stages: prepare the server, create the synths, destroy the synths. These three stages will become familiar as you program in <application>SuperCollider</application>, whether or not you use busses frequently. The example is fairly complicated, so the code is explained here:
<itemizedlist>
- <listitem><para>"busAudioSynth" Function: Accepts two arguments, and creates an audio-rate <code>SinOsc</code>, routed to the left output channel. The frequency is determined by a control-rate bus given as an argument, and optionally with an offset that can be supplied as an argument.</para></listitem>
- <listitem><para>"busControlSynth" Function: Accepts two arguments, and creates a control-rate <code>SinOsc</code>, routed to the bus given as an argument. Can also be given a frequency; the value produced by the synth is intended to be used to control pitch. The centre pitch of the oscillation is "freq", and the range of oscillation is one-twentieth the size of "freq" (one-fourtieth both higher and lower than "freq").</para></listitem>
+ <listitem><para><function>busAudioSynth</function> Function: Accepts two arguments, and creates an audio-rate <classname>SinOsc</classname>, routed to the left output channel. The frequency is determined by a control-rate bus given as an argument, and optionally with an offset that can be supplied as an argument.</para></listitem>
+ <listitem><para><function>busControlSynth</function> Function: Accepts two arguments, and creates a control-rate <classname>SinOsc</classname>, routed to the bus given as an argument. Can also be given a frequency; the value produced by the synth is intended to be used to control pitch. The centre pitch of the oscillation is <literal>freq</literal>, and the range of oscillation is one-twentieth the size of <literal>freq</literal> (one-fourtieth both higher and lower than <literal>freq</literal>).</para></listitem>
<listitem><para>SynthDef: These commands are straight-forward. They send the synthesis definitions to the server.</para></listitem>
- <listitem><para><code>b = Bus.control( s );</code> : This should also be straight-forward. A single-channel control bus is created, and assigned to the pre-declared variable "b".</para></listitem>
- <listitem><para>For synth creation, x is assigned a control-rate synth, while y and z are assigned audio-rate synths. Each synth is given the variable "b", which refers to our control-rate bus. "z" is also given an argument for \freqOffset, which makes its frequency 200 Hz higher than the synth assigned to "y".</para></listitem>
- <listitem><para>Don't worry about the "after" message for now. It's explained in <xref linkend="sect-Musicians_Guide-C-Basic_Programming-Ordering_and_Other_Features-Ordering" />.</para></listitem>
+ <listitem><para><code>b = Bus.control( s );</code> : This should also be straight-forward. A single-channel control bus is created, and assigned to the pre-declared variable <literal>b</literal>.</para></listitem>
+ <listitem><para>For synth creation, <literal>x</literal> is assigned a control-rate synth, while <literal>y</literal> and <literal>z</literal> are assigned audio-rate synths. Each synth is given the variable <literal>b</literal>, which refers to our control-rate bus. <literal>z</literal> is also given an argument for <literal>\freqOffset</literal>, which makes its frequency 200 Hz higher than the synth assigned to <literal>y</literal>.</para></listitem>
+ <listitem><para>Don't worry about the <function>after</function> message for now. It's explained in <xref linkend="sect-Musicians_Guide-C-Basic_Programming-Ordering_and_Other_Features-Ordering" />.</para></listitem>
</itemizedlist>
</para>
<section id="sect-Musicians_Guide-SC-Basic_Programming-Busses-Control_Rate_Example-Global_Variables">
<title>Why Use Global Variables</title>
<para>
- Since this is just an example, and not an actual program, the program uses four automatically-declared global variables: b, x, y, and z. Because these variables are shared with everything, it's especially important to set them to "nil" when you're done. If this were going to be written into a real program, it would be a good idea to change the variables to something which can't be accessed by other programs.
+ Since this is just an example, and not an actual program, the program uses four automatically-declared global variables: <literal>b</literal>, <literal>x</literal>, <literal>y</literal>, and <literal>z</literal>. Because these variables are shared with everything, it's especially important to set them to <literal>nil</literal> when you're done. If this were going to be written into a real program, it would be a good idea to change the variables to something which can't be accessed by other programs.
</para>
</section>
<section id="sect-Musicians_GuideSC-Basic_Programming-Busses-Control_Rate_Example-Why_Use_a_Bus">
@@ -2520,7 +2522,7 @@ h.do( { arg item; item.set( \frequency, (440.rand + 440) ); } );
<para>
Here are some advantages to using a control-rate Bus over a UGen:
<itemizedlist>
- <listitem><para>The signal can be changed without sending the "set" message to the audio-rate UGen, simply by changing the input to the bus.</para></listitem>
+ <listitem><para>The signal can be changed without sending the <literal>set</literal> message to the audio-rate UGen, simply by changing the input to the bus.</para></listitem>
<listitem><para>Input to the bus can be produced by any number of control-rate UGen's.</para></listitem>
<listitem><para>The signal in the bus can be received by more than one UGen, as it is in this example. One thousand audio-rate UGen's powered by 25 control-rate UGen's is a much better solution than if each audio-rate UGen were powered by its own control-rate UGen.</para></listitem>
<listitem><para>Busses can be accessed quickly and efficiently from any place in the program that has access to the variable holding the Bus. It's easier and safer (less error-prone) than making all of your UGen's equally accessible.</para></listitem>
@@ -2538,7 +2540,7 @@ h.do( { arg item; item.set( \frequency, (440.rand + 440) ); } );
Now you've managed to spice up an otherwise-boring synth!
</para>
<para>
- Also, control-rate Bus'ses don't need to be constantly changing. Unlike an audio-rate Bus, a control-rate Bus will hold the last-inputted value until another value is provided. You can the value of a control-rate Bus with the "set" message (and a single argument, which is the value). You can also get the current value, whether created by "set" or a UGen, by using the "get" message, and sending a Function with one argument.
+ Also, control-rate Bus'ses don't need to be constantly changing. Unlike an audio-rate Bus, a control-rate Bus will hold the last-inputted value until another value is provided. You can the value of a control-rate Bus with the <function>set</function> message (and a single argument, which is the value). You can also get the current value, whether created by <function>set</function> or a UGen, by using the <function>get</function> message, and sending a Function with one argument.
<programlisting><![CDATA[
(
var bus = Bus.control( s );
@@ -2547,10 +2549,10 @@ h.do( { arg item; item.set( \frequency, (440.rand + 440) ); } );
bus.free; bus = nil;
)
]]></programlisting>
- When running this example, you'll notice that the "12" doesn't get posted until ''after'' the program finishes with "nil". This is because of the '''latency''' between when the interpreter asks the server to do something, and when the server does it. The amount of time it takes for the server to complete a command is usually very small, but as you can see, it can make an important difference to your program. This latency is also the reason that you can't call "SynthDef.new( ... )" and "Synth.new( ... )" at the exact same time.
+ When running this example, you'll notice that the <literal>12</literal> doesn't get posted until <emphasis>after</emphasis> the program finishes with <literal>nil</literal>. This is because of the <firstterm>latency</firstterm> between when the interpreter asks the server to do something, and when the server does it. The amount of time it takes for the server to complete a command is usually very small, but as you can see, it can make an important difference to your program. This latency is also the reason that you can't call <code>SynthDef.new( <replaceable>...</replaceable> )</code> and <code>Synth.new( <replaceable>...</replaceable> )</code> at the exact same time.
</para>
<para>
- This latency is also the reason that we have to provide a single-argument Function as an argument to the "get" Function. Since the Function won't immediately be able to get the value of the bus from the server, we can't expect the value to be returned by the Function. Instead, when "get" gets the value of the bus from the server, it runs the Function that you gave it.
+ This latency is also the reason that we have to provide a single-argument function as an argument to the <function>get</function> function. Since the function won't immediately be able to get the value of the bus from the server, we can't expect the value to be returned by the function. Instead, when "get" gets the value of the bus from the server, it runs the function that you gave it.
</para>
</section>
</section> <!-- Ends "Using Busses: Control-Rate Example" Section -->
@@ -2644,7 +2646,7 @@ z.set( \direct, 0.5 ); // original Sine wave
]]></programlisting>
</para>
<para>
- I'm not going to explain this example as extensively as the previous one. It's definitely the most complex example so far. It's better if you figure out what the parts do by playing with them yourself. The bus works by routing audio from the <code>\tutorialDecayPink</code> and <code>\tutorialDecaySine</code> synths into the <code>\tutorialReverb</code> synth. The first two synths can be controlled to put all, none, or some of their signal into the bus (so that it goes through the <code>\tutorialReverb</code> synth), or straight out the audio interface (bypassing the <code>\tutorialReverb</code> synth). Notice that the ''same'' effects processor is operating on two different input sources.
+ I'm not going to explain this example as extensively as the previous one. It's definitely the most complex example so far. It's better if you figure out what the parts do by playing with them yourself. The bus works by routing audio from the <literal>\tutorialDecayPink</literal> and <literal>\tutorialDecaySine</literal> synths into the <literal>\tutorialReverb</literal> synth. The first two synths can be controlled to put all, none, or some of their signal into the bus (so that it goes through the <literal>\tutorialReverb</literal> synth), or straight out the audio interface (bypassing the <literal>\tutorialReverb</literal> synth). Notice that the <emphasis>same</emphasis> effects processor is operating on two different input sources.
</para>
</section> <!-- Ends "Using Busses: Audio-Rate Example" Section -->
</section> <!-- Ends "Busses" Section --> <!-- SC-Basic_Programming-Busses- -->
@@ -2803,7 +2805,7 @@ z.set( \direct, 0.5 ); // original Sine wave
The <application>SuperCollider</application> interpreter provides two default clocks, and one default pseudo-clock.
</para>
<para>
- The <code>SystemClock</code> always operates in seconds, and it can be used to schedule musical events, but usually this isn't necessary.
+ The <classname>SystemClock</classname> always operates in seconds, and it can be used to schedule musical events, but usually this isn't necessary.
</para>
<para>
The <code>TempoClock.default</code> runs at 60 beats-per-minute by default (equal to one beat per second). Since it's accessible from anywhere within a program, any tempo changes will have an effect on the scheduling of the entire program - so be careful! If you don't want something to be effected by tempo changes, you can create a new TempoClock just for that part of the program. If you will be using this clock frequently, you can assign it to a variable like this:
@@ -2843,7 +2845,7 @@ thisThread.clock.beats;
</funcsynopsis>
The interpreter will let you schedule just about anything, but there's no point in scheduling something other than a Function: scheduling a five won't have any effect - try it!
<programlisting><![CDATA[SystemClock.sched( 5, 5 );]]></programlisting>
- It looks like nothing happens. The <literal>5</literal> does happen, but... well... it doesn't do anything. Scheduling a Function ''will'' do something:
+ It looks like nothing happens. The <literal>5</literal> does happen, but... well... it doesn't do anything. Scheduling a Function <emphasis>will</emphasis> do something:
<programlisting><![CDATA[SystemClock.sched( 5, { 5.postln; } );]]></programlisting>
When you run this, there are two things to notice:
<itemizedlist>
diff --git a/en-US/SuperCollider/SuperCollider-Composing.xml b/en-US/SuperCollider/SuperCollider-Composing.xml
index 1a89ab0..8c1fa5b 100644
--- a/en-US/SuperCollider/SuperCollider-Composing.xml
+++ b/en-US/SuperCollider/SuperCollider-Composing.xml
@@ -94,7 +94,7 @@
</para></step>
<step><para>Now we can't hear the left channel, because the right channel is too loud! Playing with volumes (sometimes called "adjusting levels" for computers) is a constant aesthetic concern for all musicians. Add a "mul" argument to the right channel, and set it to what seems an appropriate volume for the moment. It will probably change later, but that's okay.</para></step>
<step><para>But let's add another dimension to this: there's no reason to keep the volume static, because we can use a SinOsc to change it periodically! I added a SinOsc variable called "volumeL," which I used as the argument to "mul" for the "frequencyL" SinOsc in the left channel.</para></step>
- <step><para>And now the sheer boredom of the drone in the left channel becomes obvious. I decide to make it more interesting by adding a series of overtones (an overtone is...). I decide to add six, then experiment with which frequencies to add. But, every time I adjust one frequency, I have to re-calculate and change all the others. So I decide to add a variable for the drone's frequency: "frequencyL_drone". This way, after finding the right intervals, I can easily adjust all of them just by changing the variable. I've decided on drone*1, 2, 5, 13, and 28. These are more or less arbitrary, and I arrived on them through experimentation. Of course, the drone will be ''way'' too loud.</para></step>
+ <step><para>And now the sheer boredom of the drone in the left channel becomes obvious. I decide to make it more interesting by adding a series of overtones (an overtone is...). I decide to add six, then experiment with which frequencies to add. But, every time I adjust one frequency, I have to re-calculate and change all the others. So I decide to add a variable for the drone's frequency: "frequencyL_drone". This way, after finding the right intervals, I can easily adjust all of them just by changing the variable. I've decided on drone*1, 2, 5, 13, and 28. These are more or less arbitrary, and I arrived on them through experimentation. Of course, the drone will be <emphasis>way</emphasis> too loud.</para></step>
<step><para>Writing
<programlisting><![CDATA[SinOsc.ar( [frequencyL_drone,2*frequencyL_drone,5*frequencyL_drone,13*frequencyL_drone,28*frequencyL_drone], mul:0.1 )]]></programlisting>
in your program is not easy to read, and actually it doesn't work out volume-balance-wise (for me, at least): the high frequencies are too loud, and the lower ones are not loud enough. In retrospect, I should have created a variable for the "mul" of these drones, so I could adjust them easily in proportion. But, I didn't.</para></step>
@@ -218,7 +218,7 @@
}.play;
]]></programlisting>
</para></step>
- <step><para>It still doesn't work! SuperCollider is confused because I was been lazy and didn't include enough semicolons. The error we get is, "Index not an Integer," which is a clue as to what SuperCollider is trying to do (but it's irrelevant). The real problem is that SuperCollider interprets our ten stereo arrays as all being part of the same statement. We don't want them to be the same statement, however, because we want ten ''different'' stereo arrays to be played. Fix this problem by putting a semicolon at the end of each stereo array. You don't ''need'' to include one at the end of the last statement, because SuperCollider assumes the end of the statement when it encounters a } (end-of-function marker) after it. Since we're still building our code, we might move these around or add something aftwards, so it's better to include a semicolon at the end of each stereo array.</para></step>
+ <step><para>It still doesn't work! SuperCollider is confused because I was been lazy and didn't include enough semicolons. The error we get is, "Index not an Integer," which is a clue as to what SuperCollider is trying to do (but it's irrelevant). The real problem is that SuperCollider interprets our ten stereo arrays as all being part of the same statement. We don't want them to be the same statement, however, because we want ten <emphasis>different</emphasis> stereo arrays to be played. Fix this problem by putting a semicolon at the end of each stereo array. You do not <emphasis>need</emphasis> to include one at the end of the last statement, because SuperCollider assumes the end of the statement when it encounters a } (end-of-function marker) after it. Since we're still building our code, we might move these around or add something aftwards, so it's better to include a semicolon at the end of each stereo array.</para></step>
<step><para>Now the file plays successfully, but with a disappointing result. If you can't already see the problem, try to think of it before continuing to read.</para></step>
<step><para>Only one SinOsc array gets played, and it's the last one. This is because the last statement is returned by the function that ends at } and it is that result which gets sent to the following .play</para></step>
<step><para>To fix this, and ensure that all of the stereo arrays are played, you should remove the .play from the end of the function, and add a .play to each stereo array statement. You end up with
@@ -368,14 +368,14 @@ var t_c = TempoClock.default;
<step><para>At this point, we've eliminated ten lines of code, and made ten more lines easier to read by eliminating the subtle copy-and-paste changes. If you can't manage to work it out, refer to the FSC_method_1.sc file for tips.</para></step>
<step><para>We can eliminate ten more lines of code by using a loop with an array. Let's change only one thing at a time, to make it easier to find a problem, if it should arise. Start by commenting out the lines which declare and initialize sinosc1, sinosc2, and so on.</para></step>
<step><para>Then declare a ten-element array in the same place: <code>var sinosc = Array.new( 10 );</code></para></step>
- <step><para>The next part is to write code to get ten func.value's into the array. To add something to an array in SuperCollider, we use the "add" method: <code>sinosc.add( thing_to_add );</code> There is a small wrinkle to this, described in the SuperCollider documentation. It's not important to understand (for musical reasons, that is - it is explained on this help page), but when you add an element to an array, you ''should'' re-assign the array to the variable-name: <code>sinosc = sinosc.add( thing_to_add )</code> Basically it works out like this: if you don't re-assign, then there is a chance that the array name only includes the elements that were in the array before the "add" command was run.</para></step>
+ <step><para>The next part is to write code to get ten func.value's into the array. To add something to an array in SuperCollider, we use the "add" method: <code>sinosc.add( thing_to_add );</code> There is a small wrinkle to this, described in the SuperCollider documentation. It's not important to understand (for musical reasons, that is - it is explained on this help page), but when you add an element to an array, you <emphasis>should</emphasis> re-assign the array to the variable-name: <code>sinosc = sinosc.add( thing_to_add )</code> Basically it works out like this: if you don't re-assign, then there is a chance that the array name only includes the elements that were in the array before the "add" command was run.</para></step>
<step><para>With this, we are able to eliminate a further level of redundancy in the code. Ten exact copies of <code>sinosc = sinosc.add( { func.value; } );</code> Now, ten lines that look almost identical actually are identical. Furthermore, we don't have to worry about assigning unique names, or even about index numbers, as in other programming languages. SuperCollider does this for us!</para></step>
<step><para>This still won't work, because we need to adjust the rest of the function to work with this array. The scheduling commands be changed to look something like this: <code>t_c.sched( 1, { so1 = sinosc[0].play; } );</code> Since arrays are indexed from 0 to 9, those are the index numbers of the first ten objects in the array.</para></step>
- <step><para>Remember that you need to put all of your variable declarations ''before'' anything else.</para></step>
- <step><para>It ''should'' still work. Let's use a loop to get rid of the ten identical lines.</para></step>
+ <step><para>Remember that you need to put all of your variable declarations <emphasis>before</emphasis> anything else.</para></step>
+ <step><para>It <emphasis>should</emphasis> still work. Let's use a loop to get rid of the ten identical lines.</para></step>
<step><para>In SuperCollider, <code><replaceable>x</replaceable>.do( <replaceable>f</replaceable> );</code> will send the <literal>value</literal> message to the function <literal>f</literal> <literal>x</literal> times. So, to do this ten times, we should write <code>10.do( { sinosc = sinosc.add( { func.value; } ); } );</code> and get rid of the other ones. This is very powerful for simple things that must be done multiple times, because you are definitely not going to make a copy-and-paste error, because it's easy to see what is being executed, and because it's easy to see how many times it is being executed.</para></step>
<step><para>Now let's reduce the repetitiveness of the scheduling. First, replace so1, so2, etc. with a ten-element array. Test it to ensure that the code still works.</para></step>
- <step><para>Getting the next two loops working is a little bit more complicated. We know how to run the exact same code in a loop, but we don't know how to change it subtly (by supplying different index numbers for the array, for example). Thankfully, SuperCollider provides a way to keep track of how many times the function in a loop has already been run. The first argument given to a function in a loop is the number of times that the function has ''already'' been executed. The first time it is run, the function receives a 0; if we're using a <code>10.do( <replaceable>something</replaceable> );</code> loop, then the last time the function is run, it receives a 9 because the function has already been executed 9 times. Since our ten-element array is indexed from 0 to 9, this works perfectly for us.</para></step>
+ <step><para>Getting the next two loops working is a little bit more complicated. We know how to run the exact same code in a loop, but we don't know how to change it subtly (by supplying different index numbers for the array, for example). Thankfully, SuperCollider provides a way to keep track of how many times the function in a loop has already been run. The first argument given to a function in a loop is the number of times that the function has <emphasis>already</emphasis> been executed. The first time it is run, the function receives a 0; if we're using a <code>10.do( <replaceable>something</replaceable> );</code> loop, then the last time the function is run, it receives a 9 because the function has already been executed 9 times. Since our ten-element array is indexed from 0 to 9, this works perfectly for us.</para></step>
<step><para>The code to free is shorter: <code>10.do( { arg index; t_c.sched( 51, { so[index].free; } ); } );</code> This can look confusing, especially written in one line, like it is. If it helps, you might want to write it like this instead:
<programlisting><![CDATA[
10.do
@@ -592,7 +592,7 @@ var secondPart =
<listitem><para>5 beats between the entrance of each SinOsc,</para></listitem>
<listitem><para>10 SinOsc's,</para></listitem>
<listitem><para>5 beats after the last SinOsc until the function stops.</para></listitem>
- <listitem><para>This gives us <code>1 + ( 5 * 9 ) + 5 = 51</code>. Why <code>5 * 9</code>? Because although there are ten SinOsc's, there are only nine spaces between them; the last five-second space happens ''after'' the last SinOsc.</para></listitem>
+ <listitem><para>This gives us <code>1 + ( 5 * 9 ) + 5 = 51</code>. Why <code>5 * 9</code>? Because although there are ten SinOsc's, there are only nine spaces between them; the last five-second space happens <emphasis>after</emphasis> the last <classname>SinOsc</classname>.</para></listitem>
</itemizedlist>
</para></step>
<step><para>This gives us the following schedule:
diff --git a/en-US/SuperCollider/SuperCollider-Exporting.xml b/en-US/SuperCollider/SuperCollider-Exporting.xml
index 868783d..cce4af5 100644
--- a/en-US/SuperCollider/SuperCollider-Exporting.xml
+++ b/en-US/SuperCollider/SuperCollider-Exporting.xml
@@ -13,32 +13,31 @@
<section id="sect-Musicians_Guide-SC-Non_Real_Time_Synthesis">
<title>Non-Real-Time Synthesis</title>
<para>
- SuperCollider allows you to synthesze audio output to an audio file. Doing this requires using OSC commands on the server, the "DiskOut" UGen, the "Buffer" UGen, and other relatively advanced concepts. The built-in <citetitle>DiskOut</citetitle> help file, available from <ulink url="file:///usr/share/SuperCollider/Help/UGens/Playback%20and%20Recording/DiskOut.html" /> on Fedora Linux systems, contains some help with the DiskOut UGen, and links to other useful help files. This method is not further discussed here.
+ SuperCollider allows you to synthesze audio output to an audio file. Doing this requires using OSC commands on the server, the <classname>DiskOut</classname> UGen, the <classname>Buffer</classname> UGen, and other relatively advanced concepts. The built-in <citetitle>DiskOut</citetitle> help file, available from <ulink url="file:///usr/share/SuperCollider/Help/UGens/Playback%20and%20Recording/DiskOut.html" /> on Fedora Linux systems, contains some help with the <classname>DiskOut</classname> UGen, and links to other useful help files. This method is not further discussed here.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Recording_SuperColliders_Output">
<title>Recording SuperCollider's Output (Tutorial)</title>
<para>
- Since SuperCollider outputs its audio signals to the JACK sound server, any other JACK-aware program has the opportunity to record, process, and use them. This portion of the tutorial will help you to record SuperCollider's output in Ardour. Due to the advanced nature of SuperCollider, the text assumes that you have a basic knowledge of how to work with Ardour. If not, you may find it helpful to refer to <xref linkend="chap-Musicians_Guide-Ardour" />.
+ Since <systemitem>SuperCollider</systemitem> outputs its audio signals to the JACK sound server, any other <systemitem>JACK</systemitem>-aware program has the opportunity to record, process, and use them. This portion of the tutorial will help you to record SuperCollider's output in Ardour. Due to the advanced nature of SuperCollider, the text assumes that you have a basic knowledge of how to work with Ardour. If not, you may find it helpful to refer to <xref linkend="chap-Musicians_Guide-Ardour" />.
</para>
<para>
- This procedure will help you to use Ardour to record SuperCollider's output.
+ This procedure will help you to use <application>Ardour</application> to record the <application>SuperCollider</application> output.
</para>
<procedure>
- <step><para>Close unnecessary applications and stop unnecessary processes, which will help to reduce the risk of a buffer overrun or underrun, which cause an audible break in audio. If you are viewing this document in a web browser, you may want to copy-and-paste it into a simple text editor, or GEdit, if you are already using that.</para></step>
- <step><para>Use QjackCtl to set up JACK with the right audio interface and configuration options.</para></step>
- <step><para>In order to get a clean start, restart the SuperCollider interpreter in GEdit, then start the server.</para></step>
- <step><para>Open Ardour with a new session, and set up the rulers and timeline as desired. Seconds is usually the most appropriate unit with which to measure a SuperCollider recording.</para></step>
+ <step><para>Close unnecessary applications and stop unnecessary processes, which will help to reduce the risk of a buffer overrun or underrun, which cause an audible break in audio. If you are viewing this document in a web browser, you may want to copy-and-paste it into a simple text editor, or <application>GEdit</application>, if you are already using that.</para></step>
+ <step><para>Use <application>QjackCtl</application> to set up <systemitem>JACK</systemitem> with the right audio interface and configuration options.</para></step>
+ <step><para>In order to get a clean start, restart the <application>SuperCollider</application> interpreter in <application>GEdit</application>, then start the server.</para></step>
+ <step><para>Open <application>Ardour</application> with a new session, and set up the rulers and timeline as desired. Seconds is usually the most appropriate unit with which to measure a <application>SuperCollider</application> recording.</para></step>
<step><para>Add a stereo track (or however many channels desired), and rename it it "SuperCollider."</para></step>
- <step><para>Use Ardour (the "Track/Bus Inspector" window) or QjackCtl to connect the "SuperCollider" track to SuperCollider's outputs.</para></step>
- <step><para>You'll want to make sure that the SuperCollider output is also connected to your audio interface, so that you can hear the program as you progress. This is an example of multi-plexing. Changes to your audio interface's volume control will not affect the recording in Ardour.</para></step>
- <step><para>Arm the track and transport in Ardour. When you are ready, start the transport. It is not important to start SuperCollider as quickly as possible, since you can cut out the silence after the recording is made.</para></step>
- <step><para>Switch to GEdit and play the program that you want to record. If you make a mistake while starting the program, that's okay. We can always edit the recording after it's recorded.</para></step>
- <step><para>Listen to the recording as it goes along. Use QjackCtl to make sure that you don't encounter a buffer underrun, and Ardour to make sure that you don't record a distorted signal.</para></step>
- <step><para>When SuperCollider has finished playing your program, switch to Ardour, and stop the transport.</para></step>
- <step><para>The audio file will be created in the "export" sub-directory of the session's directory.</para></step>
- <step><para>When you are ready to export, use the Ardour menu: 'Session > Export > Export session to audio file'</para></step>
+ <step><para>Use Ardour (the "Track/Bus Inspector" window) or <application>QjackCtl</application> to connect the "SuperCollider" track to SuperCollider's outputs.</para></step>
+ <step><para>You'll want to make sure that the <application>SuperCollider</application> output is also connected to your audio interface, so that you can hear the program as you progress. This is an example of multi-plexing. Changes to your audio interface's volume control will not affect the recording in Ardour.</para></step>
+ <step><para>Arm the track and transport in <application>Ardour</application>. When you are ready, start the transport. It is not important to start SuperCollider as quickly as possible, since you can cut out the silence after the recording is made.</para></step>
+ <step><para>Switch to <application>GEdit</application> and play the program that you want to record. If you make a mistake while starting the program, that's okay. We can always edit the recording after it's recorded.</para></step>
+ <step><para>Listen to the recording as it goes along. Use <application>QjackCtl</application> to make sure that you don't encounter a buffer underrun, and <application>Ardour</application> to make sure that you do not record a distorted signal.</para></step>
+ <step><para>When <application>SuperCollider</application> has finished playing your program, switch to <application>Ardour</application>, and stop the transport.</para></step>
+ <step><para>When you are ready to export, use the <application>Ardour</application> menu. <menuchoice><guimenu>Choose Session</guimenu><guisubmenu>Export</guisubmenu><guimenuitem>Export session to audio file</guimenuitem></menuchoice></para></step>
<step><para>The audio file will be created in the "export" sub-directory of the session's directory.</para></step>
</procedure>
</section>
diff --git a/en-US/SuperCollider/SuperCollider.xml b/en-US/SuperCollider/SuperCollider.xml
index 492d994..7efb103 100644
--- a/en-US/SuperCollider/SuperCollider.xml
+++ b/en-US/SuperCollider/SuperCollider.xml
@@ -5,9 +5,9 @@
]>
<chapter id="chap-Musicians_Guide-SuperCollider">
- <title>SuperCollider</title>
+ <title><application>SuperCollider</application></title>
<para>
- SuperCollider is many things, but above all:
+ <application>SuperCollider</application> is many things, but above all:
<itemizedlist>
<listitem><para>An audio synthesis engine,</para></listitem>
<listitem><para>A flexible programming language, and</para></listitem>
@@ -15,36 +15,40 @@
</itemizedlist>
</para>
+ <!-- TODO : decide whether you need this (CRA)
+ CRA: took it out, 2010-08-09
+
<section id="sect-Musicians_Guide-SC-Technical_Convetions">
<title>Technical Conventions for This Chapter</title>
- <!-- TODO : decide whether you need this (CRA) -->
+
<para>
Because this chapter of the Musicians' Guide is more like a textbook or technical manual than a regular user manual, I have adopted several conventions commonly used in those contexts:
<orderedlist>
<listitem><para>Plural forms of technical words are written with an apostrophe (for example: Synth's instead of Synths), which helps you to know that the technical word is being used.</para></listitem>
- <listitem><para>Plural and singular forms of technical words - in particular of language classes - are always capitalized (for example: Synth instead of synth), which helps you to differentiate between the use of the word in SuperCollider and in the real world.</para></listitem>
+ <listitem><para>Plural and singular forms of technical words - in particular of language classes - are always capitalized (for example: Synth instead of synth), which helps you to differentiate between the use of the word in <application>SuperCollider</application> and in the real world.</para></listitem>
<listitem><para>Other stuff?</para></listitem>
</orderedlist>
</para>
</section>
+ -->
<section id="sect-Musicians_Guide-SC-Requirements_and_Installation">
<title>Requirements and Installation</title>
<section id="sect-Musicians_Guide-SC-Req_and_Inst-Knowledge">
<title>Knowledge Requirements</title>
<para>
- <!-- Rarely is such a warning required, but I feel it is necessary for SuperCollider -->
- SuperCollider is by far the most difficult program described in the Fedora Musicians' Guide. The SuperCollider applications themselves are easy to use, and they work very well, but they are merely tools to help you accomplish something useful. SuperCollider has an extremely powerful and flexible programming language, with libraries designed primarily for audio processing. As often happens with computers, however, this added flexibility and power comes at the cost of requiring greater understanding and learning on the part of the user.
+ <!-- Rarely is such a warning required, but I feel it is necessary for <application>SuperCollider</application> -->
+ <application>SuperCollider</application> is by far the most difficult program described in the Fedora Musicians' Guide. The <application>SuperCollider</application> applications themselves are easy to use, and they work very well, but they are merely tools to help you accomplish something useful. <application>SuperCollider</application> has an extremely powerful and flexible programming language, with libraries designed primarily for audio processing. As often happens with computers, however, this added flexibility and power comes at the cost of requiring greater understanding and learning on the part of the user.
- Because SuperCollider involves actual programming, a rudimentary understanding of some principles and concepts of computer science will provide huge benefits to somebody learning the language. The following articles from Wikipedia are not mandatory reading, but you should refer to them as necessary while learning the language.
+ Because <application>SuperCollider</application> involves actual programming, a rudimentary understanding of some principles and concepts of computer science will provide huge benefits to somebody learning the language. The following articles from Wikipedia are not mandatory reading, but you should refer to them as necessary while learning the language.
<itemizedlist>
<listitem><para><citetitle>Computer Programming</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Computer_programming" />: You probably know what this is; it's what you'll be doing.</para></listitem>
- <listitem><para><citetitle>Programming Language</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Programming_language" />: SuperCollider is a programming language.</para></listitem>
+ <listitem><para><citetitle>Programming Language</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Programming_language" />: <application>SuperCollider</application> is a programming language.</para></listitem>
<listitem><para><citetitle>Interpreter</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Interpreter_%28computing%29" />: This reads your code, and sends commands to the server, which causes it to produce sound.</para></listitem>
- <listitem><para><citetitle>Server</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Server_%28computing%29" />: SuperCollider has a 'server' component, which is operated by the interpreter.</para></listitem>
- <listitem><para><citetitle>Functional Programming</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Functional_programming" />: SuperCollider can be treated as a "functional" language.</para></listitem>
- <listitem><para><citetitle>Imperative Programming</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Imperative_programming" />: SuperCollider can be treated as an "imperative" language.</para></listitem>
- <listitem><para><citetitle>Object-Oriented Programming</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Object-oriented_programming" />: SuperCollider can be treated as an "object-oriented" language.</para></listitem>
+ <listitem><para><citetitle>Server</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Server_%28computing%29" />: <application>SuperCollider</application> has a 'server' component, which is operated by the interpreter.</para></listitem>
+ <listitem><para><citetitle>Functional Programming</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Functional_programming" />: <application>SuperCollider</application> can be treated as a "functional" language.</para></listitem>
+ <listitem><para><citetitle>Imperative Programming</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Imperative_programming" />: <application>SuperCollider</application> can be treated as an "imperative" language.</para></listitem>
+ <listitem><para><citetitle>Object-Oriented Programming</citetitle> at <ulink url="http://en.wikipedia.org/wiki/Object-oriented_programming" />: <application>SuperCollider</application> can be treated as an "object-oriented" language.</para></listitem>
</itemizedlist>
<!-- Sourced from http://en.wikipedia.org/wiki/List_of_basic_computer_programming_topics -->
</para>
@@ -52,77 +56,77 @@
<section id="sect-Musicians_Guide-SC-Req_and_Inst-Software_Requirements">
<title>Software Requirements</title>
<para>
- SuperCollider uses the JACK Audio Connection Kit. You should install JACK before installing SuperCollider. Refer to <xref linkend="sect-Musicians_Guide-Install_and_Configure_JACK" /> for instructions to install JACK.
+ <application>SuperCollider</application> uses the JACK Audio Connection Kit. You should install JACK before installing <application>SuperCollider</application>. Refer to <xref linkend="sect-Musicians_Guide-Install_and_Configure_JACK" /> for instructions to install JACK.
</para>
<para>
- SuperCollider is not available from the Fedora software repositories. You must enable the "Planet CCRMA at Home" repository to install SuperCollider. See <xref linkend="sect-Musicians_Guide-CCRMA_Installing_Repository" /> for instructions ti enable the "Planet CCRMA at Home" repository. The "Planet CCRMA at Home" repository contains a wide variety of music and audio applications.
+ <application>SuperCollider</application> is not available from the Fedora software repositories. You must enable the "Planet CCRMA at Home" repository to install <application>SuperCollider</application>. See <xref linkend="sect-Musicians_Guide-CCRMA_Installing_Repository" /> for instructions ti enable the "Planet CCRMA at Home" repository. The "Planet CCRMA at Home" repository contains a wide variety of music and audio applications.
</para>
</section>
<section id="sect-Musicians_Guide-SC-Req_and_Inst-Hardware_Requirements">
<title>Hardware Requirements</title>
<para>
- You need an audio interface to use SuperCollider. You do not need a microphone to use SuperCollider.
+ You need an audio interface to use <application>SuperCollider</application>. You do not need a microphone to use <application>SuperCollider</application>.
</para>
</section>
<section id="sect-Musicians_Guide-SC-SC-Req_and_Inst-Available_Packages">
- <title>Available SuperCollider Packages</title>
+ <title>Available <application>SuperCollider</application> Packages</title>
<para>
- The SuperCollider packages are all held in the Planet CCRMA at Home repository, and there are a lot of them. Many of them have standard Fedora suffixes, but many are other kinds of optional components. Most of the optional features add libraries to SuperCollider, allowing you to use them in your audio programs. The specific features available in each additional package are not described here.
+ The <application>SuperCollider</application> packages are all held in the Planet CCRMA at Home repository, and there are a lot of them. Many of them have standard Fedora suffixes, but many are other kinds of optional components. Most of the optional features add libraries to <application>SuperCollider</application>, allowing you to use them in your audio programs. The specific features available in each additional package are not described here.
<itemizedlist>
- <listitem><para>supercollider-ambiem : Optional Library ("Ambisonics classes for SC").</para></listitem>
- <listitem><para>supercollider-debuginfo : Decodes the debugging information provided by SuperCollider.</para></listitem>
- <listitem><para>supercollider-devel : Contains files needed for development with SuperCollider.</para></listitem>
- <listitem><para>supercollider-dewdrop : Optional Library ("DewDrop external collection for SC").</para></listitem>
- <listitem><para>supercollider-emacs : Adds SuperCollider support to the "emacs" text editor.</para></listitem>
- <listitem><para>supercollider-extras : Optional Library ("Extra plugins and classes for SC").</para></listitem>
- <listitem><para>supercollider-gedit : Adds SuperCollider support to the "gedit" text editor.</para></listitem>
- <listitem><para>supercollider-libscsynth : "SuperCollider synthesis library."</para></listitem>
- <listitem><para>supercollider-quarks : Optional Library ("Local quarks repository for SuperCollider").</para></listitem>
- <listitem><para>supercollider-sclang : Help files, examples, the class library, and language interpreter.</para></listitem>
- <listitem><para>supercollider-vim : Adds SuperCollider support to the "vim" text editor.</para></listitem>
- <listitem><para>supercollider : Installs the "minimum requirements" to run SuperCollider.
+ <listitem><para><package>supercollider-ambiem</package> : Optional Library ("Ambisonics classes for SC").</para></listitem>
+ <listitem><para><package>supercollider-debuginfo</package> : Decodes the debugging information provided by <application>SuperCollider</application>.</para></listitem>
+ <listitem><para><package>supercollider-devel</package> : Contains files needed for development with <application>SuperCollider</application>.</para></listitem>
+ <listitem><para><package>supercollider-dewdrop</package> : Optional Library ("DewDrop external collection for SC").</para></listitem>
+ <listitem><para><package>supercollider-emacs</package> : Adds <application>SuperCollider</application> support to the <application>emacs</application> text editor.</para></listitem>
+ <listitem><para><package>supercollider-extras</package> : Optional Library ("Extra plugins and classes for SC").</para></listitem>
+ <listitem><para><package>supercollider-gedit</package> : Adds <application>SuperCollider</application> support to the <application>GEdit</application> text editor.</para></listitem>
+ <listitem><para><package>supercollider-libscsynth</package> : "<application>SuperCollider</application> synthesis library."</para></listitem>
+ <listitem><para><package>supercollider-quarks</package> : Optional Library ("Local quarks repository for <application>SuperCollider</application>").</para></listitem>
+ <listitem><para><package>supercollider-sclang</package> : Help files, examples, the class library, and language interpreter.</para></listitem>
+ <listitem><para><package>supercollider-vim</package> : Adds <application>SuperCollider</application> support to the <application>vim</application> text editor.</para></listitem>
+ <listitem><para><package>supercollider</package> : Installs the "minimum requirements" to run <application>SuperCollider</application>.
<itemizedlist>
- <listitem><para>supercollider-sclang</para></listitem>
- <listitem><para>supercollider-libscsynth</para></listitem>
- <listitem><para>fftw</para></listitem>
- <listitem><para>w3m-el</para></listitem>
- <listitem><para>emacs</para></listitem>
+ <listitem><para><package>supercollider-sclang</package></para></listitem>
+ <listitem><para><package>supercollider-libscsynth</package></para></listitem>
+ <listitem><para><package>fftw</package></para></listitem>
+ <listitem><para><package>w3m-el</package></para></listitem>
+ <listitem><para><package>emacs</package></para></listitem>
</itemizedlist>
</para></listitem>
- <listitem><para>supercollider-bbcut2 : Optional Library ("Beat tracking of audio streams").</para></listitem>
- <listitem><para>supercollider-bbcut2-debuginfo : Decodes the debugging information provided by bbcut2.</para></listitem>
- <listitem><para>supercollider-mathlib : Optional Library ("Useful classes for SC").</para></listitem>
- <listitem><para>supercollider-redclasses : Optional Library ("Frederik Olofsson Red SC classes").</para></listitem>
- <listitem><para>supercollider-redclasses-debuginfo : Decodes the debugging information provided by redclasses.</para></listitem>
- <listitem><para>supercollider-world : Installs most SuperCollider packages.
+ <listitem><para><package>supercollider-bbcut2</package> : Optional Library ("Beat tracking of audio streams").</para></listitem>
+ <listitem><para><package>supercollider-bbcut2-debuginfo</package> : Decodes the debugging information provided by bbcut2.</para></listitem>
+ <listitem><para><package>supercollider-mathlib</package> : Optional Library ("Useful classes for SC").</para></listitem>
+ <listitem><para><package>supercollider-redclasses</package> : Optional Library ("Frederik Olofsson Red SC classes").</para></listitem>
+ <listitem><para><package>supercollider-redclasses-debuginfo</package> : Decodes the debugging information provided by redclasses.</para></listitem>
+ <listitem><para><package>supercollider-world</package> : Installs most <application>SuperCollider</application> packages.
<itemizedlist>
- <listitem><para>supercollider</para></listitem>
- <listitem><para>abmiem</para></listitem>
- <listitem><para>supercollider-redclasses</para></listitem>
- <listitem><para>supercollider-dewdrop</para></listitem>
- <listitem><para>supercollider-emacs</para></listitem>
- <listitem><para>supercollider-mathlib</para></listitem>
- <listitem><para>supercollider-midifile</para></listitem>
- <listitem><para>supercollider-extras</para></listitem>
- <listitem><para>supercollider-bbcut2</para></listitem>
- <listitem><para>supercollider-reduniverse</para></listitem>
+ <listitem><para><package>supercollider</package></para></listitem>
+ <listitem><para><package>abmiem</package></para></listitem>
+ <listitem><para><package>supercollider-redclasses</package></para></listitem>
+ <listitem><para><package>supercollider-dewdrop</package></para></listitem>
+ <listitem><para><package>supercollider-emacs</package></para></listitem>
+ <listitem><para><package>supercollider-mathlib</package></para></listitem>
+ <listitem><para><package>supercollider-midifile</package></para></listitem>
+ <listitem><para><package>supercollider-extras</package></para></listitem>
+ <listitem><para><package>supercollider-bbcut2</package></para></listitem>
+ <listitem><para><package>supercollider-reduniverse</package></para></listitem>
</itemizedlist>
</para></listitem>
- <listitem><para>supercollider-midifile : Optional Library ("MIDI file reader for SuperCollider").</para></listitem>
- <listitem><para>supercollider-reduniverse : Optional Library ("Sonification and visualization of dynamic systems").</para></listitem>
+ <listitem><para><package>supercollider-midifile</package> : Optional Library ("MIDI file reader for <application>SuperCollider</application>").</para></listitem>
+ <listitem><para><package>supercollider-reduniverse</package> : Optional Library ("Sonification and visualization of dynamic systems").</para></listitem>
</itemizedlist>
</para>
</section>
<section id="sect-Musicians_Guide-SC-Req_and_Inst-Recommended_Installation">
<title>Recommended Installation</title>
<para>
- If you have never used SuperCollider before, then we recommend installing the smallest number of packages possible. This will allow you to start learning with the core classes, available on all SuperCollider installations. Installing the bare minimum requirements will not prevent you from installing optional libraries in the future, of course.
+ If you have never used <application>SuperCollider</application> before, then we recommend installing the smallest number of packages possible. This will allow you to start learning with the core classes, available on all <application>SuperCollider</application> installations. Installing the bare minimum requirements will not prevent you from installing optional libraries in the future, of course.
</para>
<para>
- The recommended installation also avoids installing the "emacs" or "vim" components, which - unless you are already a programmer - you probably don't know how to use. The "emacs" and "vim" text editors are extremely powerful and extensible, but they can be difficult to learn. Furthermore, there's no reason to learn them just for SuperCollider, because the component for GEdit is more than sufficient.
+ The recommended installation also avoids installing the <application>emacs</application> or <application>vim</application> components, which - unless you are already a programmer - you probably don't know how to use. The <application>emacs</application> and <application>vim</application> text editors are extremely powerful and extensible, but they can be difficult to learn. Furthermore, there's no reason to learn them just for <application>SuperCollider</application>, because the component for <application>GEdit</application> is more than sufficient.
</para>
<para>
- To install the minimum recommended installation for SuperCollider:
+ To install the minimum recommended installation for <application>SuperCollider</application>:
<orderedlist>
<listitem><para>In a terminal, run <command>su -c 'yum install supercollider supercollider-gedit'</command></para></listitem>
<listitem><para>Review the proposed installation carefully. The list may be quite long, and require a large download.</para></listitem>
@@ -132,40 +136,40 @@
</section> <!-- Ends "Requirements and Installation" Section --> <!-- SC-Req_and_Inst- -->
<section id="sect-Musicians_Guide-SC-Using_GEdit">
- <title>Using GEdit to Write and Run SuperCollider Programs</title>
+ <title>Using <application>GEdit</application> to Write and Run <application>SuperCollider</application> Programs</title>
<para>
- The 'supercollider-gedit' package installs an extension for GEdit which allows editing and running SuperCollider code from within GEdit. There are also SuperCollider extensions for the "emacs" and "vim" text editors. This tutorial uses the GEdit extension, because it is easier to learn how to use GEdit than "vim" or "emacs."
+ The <package>supercollider-gedit</package> package installs an extension for <application>GEdit</application> which allows editing and running <application>SuperCollider</application> code from within <application>GEdit</application>. There are also <application>SuperCollider</application> extensions for the <application>emacs</application> and <application>vim</application> text editors. This tutorial uses the <application>GEdit</application> extension, because it is easier to learn how to use <application>GEdit</application> than <application>vim</application> or "emacs."
</para>
<section id="sect-Musicians_Guide-SC-Using_GEdit-Enable_and_Configure_SCEd">
- <title>Enable and Configure SCEd in GEdit</title>
+ <title>Enable and Configure SCEd in <application>GEdit</application></title>
<para>
- These steps should be followed the first time that you use GEdit's SuperCollider extension.
+ These steps should be followed the first time that you use <application>GEdit</application>'s <application>SuperCollider</application> extension.
</para>
<procedure>
- <step><para>Start "GEdit"</para></step>
- <step><para>Open the Preferences window (from the menu, select 'Edit > Preferences')</para></step>
- <step><para>Choose the 'Plugins' tab, and scroll down to "Sced," then make sure that it is selected.</para></step>
- <step><para>Click on the "Configure Plugin" button, then select a runtime folder where the SuperCollider server will store any synth sent to it during program execution. The safest place for this folder could be a sub-folder of the location where you will store your SuperCollider code.</para></step>
+ <step><para>Start <application>GEdit</application></para></step>
+ <step><para>Open the Preferences window (from the menu, choose <menuchoice><guimenu>Edit</guimenu> <guimenuitem>Preferences</guimenuitem></menuchoice>)</para></step>
+ <step><para>Choose the 'Plugins' tab, and scroll down to <package>Sced</package>, then make sure that it is selected.</para></step>
+ <step><para>Click on the <guibutton>Configure Plugin</guibutton> button, then select a runtime folder where the <application>SuperCollider</application> server will store any synth sent to it during program execution. The safest place for this folder could be a sub-folder of the location where you will store your <application>SuperCollider</application> code.</para></step>
</procedure>
</section>
<section id="sect-Musicians_Guide-SC-Using_GEdit-Start_a_Server">
- <title>Enable SuperCollider Mode and Start a Server</title>
+ <title>Enable <application>SuperCollider</application> Mode and Start a Server</title>
<para>
- These steps should be followed every time you open GEdit, and wish to use the SuperCollider extension.
+ These steps should be followed every time you open <application>GEdit</application>, and wish to use the <application>SuperCollider</application> extension.
</para>
<procedure>
<step><para>Choose <menuchoice><guimenu>Tools</guimenu><guimenuitem>SuperCollider Mode</guimenuitem></menuchoice></para></step>
- <step><para>A 'SuperCollider' menu should appear, and a window at the bottom which says, "SuperCollider output".</para></step>
- <step><para>If you cannot see the window at the bottom, then select 'View > Bottom Pane' from the menu, so that it shows up. It is sometimes important to see the information that SuperCollider provides in this window.</para></step>
- <step><para>After enabling SuperCollider mode, the window should display a series of notices. Near the end should be something like this:
+ <step><para>A <guimenu>SuperCollider</guimenu> menu should appear, and a window at the bottom which says, "<application>SuperCollider</application> output".</para></step>
+ <step><para>If you cannot see the window at the bottom, then select <menuchoice><guimenu>View</guimenu><guimenuitem>Bottom Pane</guimenuitem></menuchoice> from the menu, so that it shows up. It is sometimes important to see the information that <application>SuperCollider</application> provides in this window.</para></step>
+ <step><para>After enabling <application>SuperCollider</application> mode, the window should display a series of notices. Near the end should be something like this:
<programlisting><![CDATA[
RESULT = 0
Welcome to SuperCollider, for help type ctrl-c ctrl-h (Emacs) or :SChelp (vim) or ctrl-U (sced/gedit)
]]></programlisting>
- If this window gives a non-zero value for "RESULT," then an error has probably occurred, and you should scroll up to see what it is, and try to fix it. If you receive the following warning: "The GUI scheme 'swing' is not installed" then you will not be able to run any SuperCollider prorams that use a GUI (graphical user interface). The GUI components are not used anywhere in this Guide, and they are highly optional.</para></step>
- <step><para>You will probably also want to start a server at this point, so from the menu select 'SuperCollider > Start Server'.</para></step>
- <step><para>After the server starts, you should see messages from "JackDriver". If a JACK server is not already started, then SuperCollider will start one automatically.</para></step>
- <step><para>If the SuperCollider server started successfully, you should see a message similar to this:
+ If this window gives a non-zero value for "RESULT," then an error has probably occurred, and you should scroll up to see what it is, and try to fix it. If you receive the following warning: "The GUI scheme 'swing' is not installed" then you will not be able to run any <application>SuperCollider</application> prorams that use a GUI (graphical user interface). The GUI components are not used anywhere in this Guide, and they are highly optional.</para></step>
+ <step><para>You will probably also want to start a server at this point, so from the menu select '<application>SuperCollider</application> > Start Server'.</para></step>
+ <step><para>After the server starts, you should see messages from "JackDriver". If a JACK server is not already started, then <application>SuperCollider</application> will start one automatically.</para></step>
+ <step><para>If the <application>SuperCollider</application> server started successfully, you should see a message similar to this:
<programlisting><![CDATA[
SuperCollider 3 server ready..
JackDriver: max output latency 46.4 ms
@@ -175,16 +179,16 @@ notification is on
</procedure>
</section>
<section id="sect-Musicians_Guide-SC-Using_GEdit-Executing_Code">
- <title>Executing Code in GEdit</title>
+ <title>Executing Code in <application>GEdit</application></title>
<para>
- You can execute code directly from GEdit, without having to use "sclang" from the command-line.
+ You can execute code directly from <application>GEdit</application>, without having to use <command>sclang</command> from the command-line.
</para>
<procedure>
- <step><para>Ensure that SuperCollider mode is enabled, and that a server has been started.</para></step>
+ <step><para>Ensure that <application>SuperCollider</application> mode is enabled, and that a server has been started.</para></step>
<step><para>Select the code that you wish to execute. A single line of code may be executed simply by placing the text-input cursor on that line.</para></step>
- <step><para>Press 'Ctrl+E' on the keyboard, or from the menu select 'SuperCollider > Evaluate'</para></step>
- <step><para>To stop all sound on the server, press 'Esc' on the keyboard, or from the menu select 'SuperCollider > Stop Sound'</para></step>
- <step><para>If the server successfully executes the code, then it will output something to the "SuperCollider output" pane. The output will be different, depending on what SuperCollider asked the server to do, but will usually either look like this:
+ <step><para>Press 'Ctrl+E' on the keyboard, or from the menu select '<application>SuperCollider</application> > Evaluate'</para></step>
+ <step><para>To stop all sound on the server, press 'Esc' on the keyboard, or from the menu select '<application>SuperCollider</application> > Stop Sound'</para></step>
+ <step><para>If the server successfully executes the code, then it will output something to the "<application>SuperCollider</application> output" pane. The output will be different, depending on what <application>SuperCollider</application> asked the server to do, but will usually either look like this:
<programlisting><![CDATA[Synth("temp_0": 1000)]]></programlisting>
or this:
<programlisting><![CDATA[RESULT = 0]]></programlisting>
@@ -192,26 +196,26 @@ notification is on
</procedure>
</section>
<section id="sect-Musicians_Guide-SC-Using_GEdit-Other_Tips">
- <title>Other Tips for Using GEdit with SuperCollider</title>
+ <title>Other Tips for Using <application>GEdit</application> with <application>SuperCollider</application></title>
<para>
<itemizedlist>
- <listitem><para>If you close GEdit while the SuperCollider server is running, then GEdit will automatically shut down the server.</para></listitem>
- <listitem><para>If JACK is started by SuperCollider, then it will automatically terminate when the SuperCollider server terminates.</para></listitem>
- <listitem><para>SuperCollider will automatically attempt to connect its outputs to the system's outputs. If your audio output doesn't work, then you should use "QjackCtl" to verify that it is correctly connected.</para></listitem>
- <listitem><para>Other Functions available in the SuperCollider menu include:
+ <listitem><para>If you close <application>GEdit</application> while the <application>SuperCollider</application> server is running, then <application>GEdit</application> will automatically shut down the server.</para></listitem>
+ <listitem><para>If <systemitem>JACK</systemitem> is started by <application>SuperCollider</application>, then it will automatically terminate when the <application>SuperCollider</application> server terminates.</para></listitem>
+ <listitem><para><application>SuperCollider</application> will automatically attempt to connect its outputs to the system's outputs. If your audio output doesn't work, then you should use <application>QjackCtl</application> to verify that it is correctly connected.</para></listitem>
+ <listitem><para>Other functions available in the <application>SuperCollider</application> menu include:
<itemizedlist>
- <listitem><para>Find Help (Opens the SuperCollider help file for currently-selected object).</para></listitem>
- <listitem><para>Find Definition (Opens the SuperCollider source file for the currently-selected object).</para></listitem>
- <listitem><para>Restart Interpreter (Restarts the SuperCollider interpreter; also closes running servers, but does not restart them).</para></listitem>
- <listitem><para>Clear output (Clears all output from the "SuperCollider output" pane).</para></listitem>
+ <listitem><para>Find Help (Opens the <application>SuperCollider</application> help file for currently-selected object).</para></listitem>
+ <listitem><para>Find Definition (Opens the <application>SuperCollider</application> source file for the currently-selected object).</para></listitem>
+ <listitem><para>Restart Interpreter (Restarts the <application>SuperCollider</application> interpreter; also closes running servers, but does not restart them).</para></listitem>
+ <listitem><para>Clear output (Clears all output from the "<application>SuperCollider</application> output" pane).</para></listitem>
</itemizedlist>
</para></listitem>
</itemizedlist>
</para>
</section>
- </section> <!-- Ends the "Using GEdit" Section --> <!-- SC-Using_GEdit- -->
+ </section> <!-- Ends the "Using <application>GEdit</application>" Section --> <!-- SC-Using_GEdit- -->
- <!-- These link to the rest of the SuperCollider chapter -->
+ <!-- These link to the rest of the <application>SuperCollider</application> chapter -->
<xi:include href="SuperCollider-Basic_Programming.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="SuperCollider-Composing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="SuperCollider-Exporting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
More information about the docs-commits
mailing list