X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fexpressive.itely;h=514a2d8cc2cf82fe0e780cd409713d8dd03c9087;hb=84dfa31321b6f0c3224ed8c586b64ec97e88402f;hp=0a92d4461f74d2df357e8b467b4e79505741af7d;hpb=46c9b2ad0a3cd576509fa68293c424f6e8bb57b4;p=lilypond.git

diff --git a/Documentation/user/expressive.itely b/Documentation/user/expressive.itely
index 0a92d4461f..514a2d8cc2 100644
--- a/Documentation/user/expressive.itely
+++ b/Documentation/user/expressive.itely
@@ -9,8 +9,7 @@
 @node Expressive marks
 @section Expressive marks
 
-@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
-{expressive-headword.ly}
+@lilypondfile[quote]{expressive-headword.ly}
 
 @menu
 * Attached to notes::           
@@ -22,58 +21,63 @@
 @node Attached to notes
 @subsection Attached to notes
 
-
 @menu
 * Articulations and ornamentations::  
 * Dynamics::                    
 @end menu
 
 @node Articulations and ornamentations
-@unnumberedsubsubsec Articulations and ornamentations
+@subsubsection Articulations and ornamentations
 
-@cindex Articulations
+@cindex articulations
 @cindex scripts
 @cindex ornaments
 
-A variety of symbols can appear above and below notes to indicate
-different characteristics of the performance.  All these symbols
-can be attached to a note using the syntax @var{note}@code{\}@var{name}. 
+A variety of symbols that denote articulations, ornamentations,
+and other performance indications can be attached to a note using
+this syntax:
 
-The possible values for @var{name} are listed in @ref{List of
-articulations}.
+@example
+@var{note}\@var{name}
+@end example
 
-Some of these articulations have shorthands for easier entry.  They
-are used by adding a dash and the character signifying
-the articulation to the note name.  The available shorthands and
-their output are:
+The possible values for @var{name} are listed in @ref{List of
+articulations}.  For example:
 
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-c4-.  c--   c-+   c-|   
-c->   c-^   c-_         
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c4\staccato c\mordent b2\turn
+c1\fermata
 @end lilypond
 
-The marks are automatically placed, but the direction can be
-forced as well.  Like other pieces of LilyPond code, @code{_} will
-place them below the staff, and @code{^} will place them above.
-This applies both to the shorthands and the fully named
-articulations.  For the shorthands, the dash itself should be
-omitted; the shorthand signs replace it:
+@cindex marcato
+@cindex stopped
+@cindex tenuto
+@cindex staccatissimo
+@cindex accent
+@cindex staccato
+@cindex portato
 
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-c4^^ c4_^
-c\fermata c^\fermata c_\fermata
+Some of these articulations have shorthands for easier entry.
+Shorthands are appended to the note name, and their syntax
+consists of a dash (@tie{}@code{-}) followed by a symbol
+signifying the articulation.  Predefined shorthands exist for
+@notation{marcato}, @notation{stopped}, @notation{tenuto},
+@notation{staccatissimo}, @notation{accent}, @notation{staccato},
+and @notation{portato}.  Their corresponding output appears as
+follows:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c4-^  c-+  c--  c-|
+c->   c-.  c-_
 @end lilypond
 
+The rules for the default placement of articulations are defined
+in @file{scm/@/script@/.scm}.  Articulations and ornamentations
+may be manually placed above or below the staff, see
+@ref{Controlling direction and placement}.
 
-@cindex accent
-@cindex marcato
-@cindex staccatissimo
 @cindex espressivo
 @cindex fermata
-@cindex stopped
-@cindex staccato
-@cindex portato
-@cindex tenuto
 @cindex upbow
 @cindex downbow
 @cindex foot marks
@@ -96,60 +100,37 @@ c\fermata c^\fermata c_\fermata
 @cindex varcoda
 
 
-@commonprop
+@snippets
 
-The meanings of the shorthands can be changed.  They are defined
-in @file{ly/@/script@/-init@/.ly}, where the variables  
-@code{DashDot}, @code{DashDash}, @code{DashPlus}, @code{DashBar},
-@code{DashLarger}, @code{DashHat}, and @code{DashUnderscore}
-are associated with the default articulation marks.  If you want,
-e.g., @code{-+} to produce a trill instead of a "+", you can
-redefine the variable in your document:
+@c Send these snippets to Valentin for the LSR.
 
-@lilypond[quote,ragged-right,verbatim]
-\relative c'' { c-+ }       
-dashPlus = "trill"
-\relative c'' { c-+ }       
-@end lilypond
+The shorthands are defined in @file{ly/@/script@/-init@/.ly},
+where the variables @code{dashHat}, @code{dashPlus},
+@code{dashDash}, @code{dashBar}, @code{dashLarger},
+@code{dashDot}, and @code{dashUnderscore} are assigned default
+values.  The default values for the shorthands can be modified.
+For example, to associate the @code{-+} (@code{dashPlus})
+shorthand with the @notation{trill} symbol instead of the default
+@notation{+} symbol, assign the value @code{trill} to the variable
+@code{dashPlus}:
 
-The vertical ordering of scripts is controlled with the
-@code{script-priority} property.  The lower this number, the
-closer it will be put to the note.  In this example, the
-@internalsref{TextScript} (the sharp symbol) first has the lowest
-priority, so it is put lowest in the first example.  In the
-second, the prall trill (the @internalsref{Script}) has the
-lowest, so it is on the inside.  When two objects have the same
-priority, the order in which they are entered decides which one
-comes first.
-
-
-@commonprop
-
-The meanings of the shorthands can be changed.  They are defined
-in @file{ly/@/script@/-init@/.ly}, where the variables  
-@code{DashDot}, @code{DashDash}, @code{DashPlus}, @code{DashBar},
-@code{DashLarger}, @code{DashHat}, and @code{DashUnderscore}
-are associated with the default articulation marks.  If you want,
-e.g., @code{-+} to produce a trill instead of a "+", you can
-redefine the variable in your document:
-
-@lilypond[quote,ragged-right,verbatim]
-\relative c'' { c-+ }       
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' { c-+ }
 dashPlus = "trill"
-\relative c'' { c-+ }       
+\relative c'' { c-+ }
 @end lilypond
 
 The vertical ordering of scripts is controlled with the
 @code{script-priority} property.  The lower this number, the
 closer it will be put to the note.  In this example, the
-@internalsref{TextScript} (the sharp symbol) first has the lowest
+@code{TextScript} (the sharp symbol) first has the lowest
 priority, so it is put lowest in the first example.  In the
-second, the prall trill (the @internalsref{Script}) has the
+second, the @notation{prall trill} (the @code{Script}) has the
 lowest, so it is on the inside.  When two objects have the same
 priority, the order in which they are entered decides which one
 comes first.
 
-@lilypond[verbatim,relative=3,ragged-right,fragment,quote]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=3]
 \once \override TextScript #'script-priority = #-100
 a4^\prall^\markup { \sharp }
 
@@ -160,21 +141,25 @@ a4^\prall^\markup { \sharp }
 
 @seealso
 
-Snippets: @lsrdir{expressive}
+Music Glossary: @rglos{tenuto}, @rglos{accent}, @rglos{staccato},
+@rglos{portato}.
 
-Internals Reference: @internalsref{Script}.
+Snippets: @lsrdir{Expressive,Expressive-marks}
 
+Internals Reference: @internalsref{Script},
+@internalsref{TextScript}.
 
-@refbugs
+
+@knownissues
 
 These signs appear in the printed output but have no effect on the
 MIDI rendering of the music.
 
 
 @node Dynamics
-@unnumberedsubsubsec Dynamics
+@subsubsection Dynamics
 
-@cindex Dynamics
+@cindex dynamics
 @funindex \pppp
 @funindex \ppp
 @funindex \pp
@@ -193,95 +178,102 @@ MIDI rendering of the music.
 @funindex \sfz
 @funindex \rfz
 
-Absolute dynamic marks are specified using a command after a note
-@code{c4\ff}.  The available dynamic marks are @code{\ppppp},
+Absolute dynamic marks are specified using a command after a note,
+like @code{c4\ff}.  The available dynamic marks are @code{\ppppp},
 @code{\pppp}, @code{\ppp}, @code{\pp}, @code{\p}, @code{\mp},
 @code{\mf}, @code{\f}, @code{\ff}, @code{\fff}, @code{\ffff},
 @code{\fp}, @code{\sf}, @code{\sff}, @code{\sp}, @code{\spp},
-@code{\sfz}, and @code{\rfz}.  The dynamic marks can be placed
-above or below the staff with @code{_} and @code{^}, just like
-articulation marks. 
+@code{\sfz}, and @code{\rfz}.  The dynamic marks may be manually
+placed above or below the staff, see @ref{Controlling direction
+and placement}.
 
-@lilypond[quote,verbatim,ragged-right,fragment,relative=2]
-c2\ppp c\mp 
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c2\ppp c\mp
 c\rfz c^\mf
 c_\spp c_\staccato^\ff
 @end lilypond
 
+@cindex hairpin
 @funindex \<
 @funindex \>
 @funindex \!
+@funindex \cr
+@funindex \decr
 
-A crescendo mark is started with @code{\<} and terminated with
-@code{\!} or an absolute dynamic.  A decrescendo is started with
-@code{\>} and is also terminated with @code{\!} or an absolute
-dynamic.  @code{\cr} and @code{\decr} may be used instead of
-@code{\<} and @code{\>}.  They can be engraved either using a
-graphical sign (a @q{hairpin}), or with textual signs.
+A @notation{crescendo} mark is started with @code{\<} and
+terminated with @code{\!} or an absolute dynamic.  A
+@notation{decrescendo} is started with @code{\>} and is also
+terminated with @code{\!} or an absolute dynamic.  @code{\cr} and
+@code{\decr} may be used instead of @code{\<} and @code{\>}.  They
+can be engraved either using a graphical sign (a
+@notation{hairpin}), or with textual signs.
 
 Because these marks are bound to notes, you must use spacer notes
 if multiple marks are needed during one note.
 
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 c\< c\! d\> e\!
 << f1 { s4 s4\< s4\! \> s4\! } >>
 @end lilypond
 
-This may give rise to very short hairpins.  Use
-@code{minimum-length} in
-@internalsref{Voice}.@internalsref{Hairpin} to lengthen them, for
-example:
+This may give rise to very short hairpins.  To lengthen them, the
+following code can be used, for example:
 
 @example
 \override Voice.Hairpin #'minimum-length = #5
 @end example
 
 @noindent
-A hairpin normally starts at the left edge of the beginning note
-and ends on the right edge of the ending note.  If the ending note
-falls on the downbeat, the hairpin ends on the immediately
-preceding bar line.  This may be modified by setting the
-@code{hairpinToBar line} property,
-@cindex Hairpin
-
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+A @notation{hairpin} normally starts at the left edge of the
+beginning note and ends on the right edge of the ending note.  If
+the ending note falls on the downbeat, the @notation{hairpin} ends
+on the immediately preceding bar line.  The following example
+illustrates this behavior:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 e4\< e2. e1\!
 \set hairpinToBarline = ##f
 e4\< e2. e1\!
 @end lilypond
 
 @cindex espressivo, articulation
+
 In some situations the @code{\espressivo} articulation mark may be
 suitable to indicate a crescendo and decrescendo on the one note:
 
-@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 c2 b4 a g1\espressivo
 @end lilypond
 
 @cindex al niente
 @cindex niente, al
 
-Hairpins may be printed with a circled tip (al niente notation) by
-setting the @code{circled-tip} property:
+Hairpins may be printed with a circled tip (al niente notation):
 
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \override Hairpin #'circled-tip = ##t
 c2\< c\!
 c4\> c\< c2\!
 @end lilypond
 
-
 @cindex crescendo
 @cindex decrescendo
 @cindex diminuendo
-
-You can use text saying @emph{cresc.}, @emph{decr.}, or
-@emph{dim.} instead of hairpins with the commands \setTextCresc,
-\setTextDim, and \setTextDecresc.  The corresponding
-\setHairpinCresc, \setHairpinDim, and \setHairpinDecresc will
-revert to hairpins again: 
-
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+@funindex \setTextCresc
+@funindex \setTextDim
+@funindex \setTextDecresc
+@funindex \setHairpinCresc
+@funindex \setHairpinDim
+@funindex \setHairpinDecresc
+
+You can use text saying @notation{cresc.}, @notation{decr.}, or
+@notation{dim.} instead of hairpins with the commands
+@code{\setTextCresc}, @code{\setTextDim}, and
+@code{\setTextDecresc}.  The corresponding
+@code{\setHairpinCresc}, @code{\setHairpinDim}, and
+@code{\setHairpinDecresc} will revert to hairpins again:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \setTextCresc
 c\< d e f\!
 \setHairpinCresc
@@ -297,17 +289,16 @@ e\> d c b\!
 You can also supply your own texts and change the style of the
 spanner line with the properties @code{\crescendoText},
 @code{\crescendoSpanner}, @code{\decrescendoText}, and
-@code{\decrescendoSpanner}. Available values for the spanner
+@code{\decrescendoSpanner}.  Available values for the spanner
 properties are @code{hairpin}, @code{line}, @code{dashed-line},
-and @code{dotted-line}. If unset, a hairpin crescendo is used:
+and @code{dotted-line}.  If unset, a hairpin crescendo is used:
 
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 \set crescendoText = \markup { \italic "cresc. poco" }
 \set crescendoSpanner = #'dotted-line
 a'2\< a a a a a a a\!\mf
 @end lilypond
 
-
 To create new dynamic marks or text that should be aligned with
 dynamics, see @ref{New dynamic marks}.
 
@@ -315,7 +306,17 @@ Vertical positioning of dynamics is handled by
 @internalsref{DynamicLineSpanner}.
 
 
-@commonprop
+@predefined
+
+@funindex \dynamicUp
+@code{\dynamicUp},
+@funindex \dynamicDown
+@code{\dynamicDown},
+@funindex \dynamicNeutral
+@code{\dynamicNeutral}.
+
+
+@snippets
 
 Dynamics that occur at, begin on, or end on the same note will be
 vertically aligned.  If you want to ensure that dynamics are
@@ -326,47 +327,41 @@ the @code{staff-padding} property.
 \override DynamicLineSpanner #'staff-padding = #4
 @end example
 
+@noindent
 You may also use this property if the dynamics are colliding with
 other notation.
 
-Crescendi and decrescendi that cross a line break will be
-continued on the second line.  If they end on the first note of a
-new line, nothing will be printed on that line.  To change this
-behavior, use
+@notation{Crescendi} and @notation{decrescendi} that cross a line
+break will be continued on the second line.  If they end on the
+first note of a new line, nothing will be printed on that line.
+To change this behavior, use
 
 @example
 \override Score.Hairpin #'after-line-breaking = ##t
 @end example
 
-Text style dynamic changes (such as @emph{cresc.} and @emph{dim.})
-are printed with a dashed line showing their extent.  To surpress
-printing this line, use
+Text style dynamic changes (such as @notation{cresc.} and
+@notation{dim.}) are printed with a dashed line showing their
+extent.  To suppress printing this line, use
 
 @example
 \override DynamicTextSpanner #'dash-period = #-1.0
 @end example
 
 
-@refcommands
+@seealso
 
-@funindex \dynamicUp
-@code{\dynamicUp},
-@funindex \dynamicDown
-@code{\dynamicDown},
-@funindex \dynamicNeutral
-@code{\dynamicNeutral}.
+@c TODO: Add hairpin to glossary.
 
+Music Glossary: @rglos{crescendo}, @rglos{decrescendo}.
 
-@seealso
+Learning Manual: @rlearning{Articulation and dynamics}.
 
-Snippets: @lsrdir{expressive}
+Snippets: @lsrdir{Expressive,Expressive-marks}
 
 Internals Reference: @internalsref{DynamicText},
 @internalsref{Hairpin}.  Vertical positioning of these symbols is
 handled by @internalsref{DynamicLineSpanner}.
-Glossary: @rglos{Hairpin}, @rglos{crescendo}, @rglos{decrescendo}
-
-@c TODO: add link to LM directions
 
 
 @node Curves
@@ -380,45 +375,33 @@ Glossary: @rglos{Hairpin}, @rglos{crescendo}, @rglos{decrescendo}
 @end menu
 
 @node Slurs
-@unnumberedsubsubsec Slurs
+@subsubsection Slurs
 
-@cindex Slurs
+@cindex slurs
 
-A slur indicates that notes are to be played bound or
+A @notation{slur} indicates that notes are to be played bound or
 @emph{legato}.  They are entered using parentheses:
 
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 f( g a) a8 b( a4 g2 f4)
 <c e>2( <b d>2)
 @end lilypond
 
 Just as with ties, the direction of a slur can be specified with
 @code{\slur@emph{DIR}}, where @code{@emph{DIR}} is either
-@code{Up}, @code{Down}, or @code{Neutral} (automatically
-selected).  The shorthands are also available: by adding
-@code{_} or @code{^} before the opening parentheses, the direction
-is also set.  
+@code{Up}, @code{Down}, or @code{Neutral} (@code{Neutral} is the
+default).  Slurs may be manually placed above or below the staff,
+see @ref{Controlling direction and placement}.
 
-@lilypond[relative=2,ragged-right,quote,verbatim,fragment]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 c4_( c) c^( c)
 @end lilypond
 
-Only one slur can be printed at once.  If you need to print a long
-slur over a few small slurs, please see @ref{Phrasing slurs}.
-
-
-@commonprop
-
-Some composers write two slurs when they want legato chords.  This
-can be achieved in LilyPond by setting @code{doubleSlurs},
-
-@lilypond[verbatim,ragged-right,relative,fragment,quote]
-\set doubleSlurs = ##t
-<c e>4 ( <d f> <c e> <d f> )
-@end lilypond
+Using this method, only one slur can be printed at once.  To print
+a long slur over a few small slurs, see @ref{Phrasing slurs}.
 
 
-@refcommands
+@predefined
 
 @funindex \slurUp
 @code{\slurUp},
@@ -433,24 +416,40 @@ can be achieved in LilyPond by setting @code{doubleSlurs},
 @funindex \slurSolid
 @code{\slurSolid}.
 
+
+@snippets
+
+Some composers write two slurs when they want legato chords.  This
+can be achieved in LilyPond by setting @code{doubleSlurs},
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
+\set doubleSlurs = ##t
+<c e>4 ( <d f> <c e> <d f> )
+@end lilypond
+
+
 @seealso
 
-Snippets: @lsrdir{expressive}
+Music Glossary: @rglos{slur}
+
+Snippets: @lsrdir{Expressive,Expressive-marks}
 
 Internals Reference: @internalsref{Slur}.
 
 
 @node Phrasing slurs
-@unnumberedsubsubsec Phrasing slurs
+@subsubsection Phrasing slurs
 
 @cindex phrasing slurs
 @cindex phrasing marks
+@funindex \(
+@funindex \)
 
 A phrasing slur (or phrasing mark) connects notes and is used to
 indicate a musical sentence.  It is written using @code{\(} and
 @code{\)} respectively:
 
-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 \time 6/4 c'\( d( e) f( e) d\)
 @end lilypond
 
@@ -458,13 +457,14 @@ Typographically, the phrasing slur behaves almost exactly like a
 normal slur.  However, they are treated as different objects.  A
 @code{\slurUp} will have no effect on a phrasing slur; instead,
 use @code{\phrasingSlurUp}, @code{\phrasingSlurDown}, and
-@code{\phrasingSlurNeutral}, or use the shorthands @code{_} and
-@code{^}.
+@code{\phrasingSlurNeutral}.  Phrasing slurs may be manually
+placed above or below the staff, see @ref{Controlling direction
+and placement}.
 
 You cannot have simultaneous phrasing slurs.
 
 
-@refcommands
+@predefined
 
 @funindex \phrasingSlurUp
 @code{\phrasingSlurUp},
@@ -476,28 +476,31 @@ You cannot have simultaneous phrasing slurs.
 
 @seealso
 
-Snippets: @lsrdir{expressive}
+Snippets: @lsrdir{Expressive,Expressive-marks}
 
-Internals Reference: @internalsref{PhrasingSlur}.
+Internals Reference: @internalsref{PhrasingSlur}
 
 
 @node Breath marks
-@unnumberedsubsubsec Breath marks
+@subsubsection Breath marks
 
-Breath marks are entered using @code{\breathe}
+@cindex breath marks
+@funindex \breathe
 
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+Breath marks are entered using @code{\breathe}:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 c'4 \breathe d4
 @end lilypond
 
 
-@commonprop
+@snippets
 
 The glyph of the breath mark can be tuned by overriding the
 @code{text} property of the @code{BreathingSign} layout object
 with any markup text.  For example,
 
-@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 c'4
 \override BreathingSign #'text
   = #(make-musicglyph-markup "scripts.rvarcomma")
@@ -505,27 +508,58 @@ c'4
 d4
 @end lilypond
 
-@seealso
 
-Snippets: @lsrdir{expressive}
+@seealso
 
-Internals Reference: @internalsref{BreathingSign}.
+Snippets: @lsrdir{Expressive,Expressive-marks}
+@c @lsr{expressive,breathing-sign.ly}.
 
-Examples: @lsr{expressive,breathing-sign.ly}
+Internals Reference: @internalsref{BreathingSign}
 
 
 @node Falls and doits
-@unnumberedsubsubsec Falls and doits
+@subsubsection Falls and doits
+
+@cindex falls
+@cindex doits
+@funindex \bendAfter
 
-Falls and doits can be added to notes using the @code{\bendAfter}
-command,
+@notation{Falls} and @notation{doits} can be added to notes using
+the @code{\bendAfter} command:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c2-\bendAfter #+4
+c-\bendAfter #-4
+c-\bendAfter #+8
+c-\bendAfter #-8
+@end lilypond
 
-@lilypond[fragment,ragged-right,relative=2]
+The dash (@tie{-}) following the note name is @emph{required} when
+writing @notation{falls} and @notation{doits}.
+
+
+@snippets
+
+The @code{shortest-duration-space} property may have to be tweaked
+to adjust the shape of @notation{falls} and @notation{doits}.
+
+@c Fix this snippet. The tweak does not work. -pm
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 \override Score.SpacingSpanner #'shortest-duration-space = #3.0
 c4-\bendAfter #+5
 c4-\bendAfter #-3
 @end lilypond
 
+
+@seealso
+
+@c TODO: add falls and doits to glossary.
+@c Music Glossary: @rglos{falls}, @rglos{doits}.
+
+Snippets: @lsrdir{Expressive,Expressive-marks}
+
+
 @node Lines
 @subsection Lines
 
@@ -536,80 +570,83 @@ c4-\bendAfter #-3
 @end menu
 
 @node Glissando
-@unnumberedsubsubsec Glissando
+@subsubsection Glissando
 
-@cindex Glissando
+@cindex glissando
 @funindex \glissando
 
-A glissando is a smooth change in pitch.  It is denoted by a line
-or a wavy line between two notes.  It is requested by attaching
-@code{\glissando} to a note
+A @notation{glissando} is a smooth change in pitch.  It is denoted
+by a line or a wavy line between two notes.  A
+@notation{glissando} is created by attaching @code{\glissando} to
+a note:
 
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 c2\glissando c'
 \override Glissando #'style = #'zigzag
 c2\glissando c,
 @end lilypond
 
-@commonprop
 
+@snippets
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 I = \once \override NoteColumn #'ignore-collision = ##t
 
-\relative <<
+\relative c' <<
   { \oneVoice \stemDown f2 \glissando \stemNeutral a } \\
   { \oneVoice \I c2 \glissando \I d, }
 >>
 @end lilypond
 
 
-
 @seealso
 
-Snippets: @lsrdir{expressive}
+Music Glossary: @rglos{glissando}
 
-Internals Reference: @internalsref{Glissando}.
+Snippets: @lsrdir{Expressive,Expressive-marks}
 
-Glossary: @rglos{falls}, @rglos{doits}
-Example files:
-@lsr{expressive,glissando.ly}, @lsr{expressive,line-styles.ly}
+@c FIXME: I need to figure out what's up with these.  -gp
+@c @lsr{expressive,glissando.ly},
+@c @lsr{expressive,line-styles.ly}
 
+Internals Reference: @internalsref{Glissando}
 
-@refbugs
+
+@knownissues
 
 Printing text over the line (such as @emph{gliss.}) is not
 supported.
 
 
 @node Arpeggio
-@unnumberedsubsubsec Arpeggio
+@subsubsection Arpeggio
 
-@cindex Arpeggio
+@cindex arpeggio
 @cindex broken chord
-@funindex \arpeggio
 
-You can specify an arpeggio sign (also known as broken chord) on a
-chord by attaching an @code{\arpeggio} to the chord:
+You can specify an @notation{arpeggio} (also known as a
+@notation{broken chord}) on a chord by attaching an
+@code{\arpeggio} to the chord:
 
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 <c e g c>\arpeggio
 @end lilypond
 
-A square bracket on the left is used to indicate that the chord should
-@emph{not} be arpeggiated:
+A square bracket on the left, denoted by @code{\arpeggioBracket},
+is used to indicate that the chord should @emph{not} be
+arpeggiated:
 
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 \arpeggioBracket
-<c' e g c>\arpeggio
+<c e g c>\arpeggio
 @end lilypond
 
 The direction of the arpeggio can be denoted by adding an
-arrowhead to the wiggly line. This is done with the commands
-@code{arpeggioUp} and @code{arpeggioDown}. @code{arpeggioNeutral}
+arrowhead to the wiggly line.  This is done with the commands
+@code{arpeggioUp} and @code{arpeggioDown}.  @code{arpeggioNeutral}
 reverts to the arrow-less version:
 
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 \new Voice {
   \arpeggioUp
   <c e g c>\arpeggio
@@ -621,13 +658,27 @@ reverts to the arrow-less version:
 @end lilypond
 
 
-@commonprop
+@predefined
+
+@funindex \arpeggio
+@code{\arpeggio},
+@funindex \arpeggioUp
+@code{\arpeggioUp},
+@funindex \arpeggioDown
+@code{\arpeggioDown},
+@funindex \arpeggioNeutral
+@code{\arpeggioNeutral},
+@funindex \arpeggioBracket
+@code{\arpeggioBracket}.
+
+
+@snippets
 
 In a @code{PianoStaff}, it is possible to let an arpeggio cross
 between the staves by setting the property
-@internalsref{PianoStaff}.@code{connectArpeggios}. 
+@code{PianoStaff}.@code{connectArpeggios}.
 
-@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 \new PianoStaff <<
   \set PianoStaff.connectArpeggios = ##t
   \new Staff { <c' e g c>\arpeggio }
@@ -639,7 +690,7 @@ The same can be accomplished in contexts other than
 @code{PianoStaff} if the @code{Span_arpeggio_engraver} is included
 in the Score context.
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 \score {
   \new StaffGroup {
     \set Score.connectArpeggios = ##t
@@ -655,18 +706,18 @@ in the Score context.
   }
   \layout {
     \context {
-      \Score 
+      \Score
       \consists "Span_arpeggio_engraver"
-    } 
+    }
   }
 }
 @end lilypond
 
-Similarly,  an arpeggio can be drawn across notes in
-different voices on the same staff if the Span_arpeggio_engraver
-is moved to the Staff context:
+Similarly, an arpeggio can be drawn across notes in different
+voices on the same staff if the @code{Span_arpeggio_engraver} is
+moved to the Staff context:
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 \new Staff
 \with {
   \consists "Span_arpeggio_engraver"
@@ -681,74 +732,70 @@ is moved to the Staff context:
 @end lilypond
 
 
+@seealso
 
-@refcommands
-
-@code{\arpeggio},
-@funindex \arpeggioUp
-@code{\arpeggioUp},
-@funindex \arpeggioDown
-@code{\arpeggioDown},
-@funindex \arpeggioNeutral
-@code{\arpeggioNeutral},
-@funindex \arpeggioBracket
-@code{\arpeggioBracket}.
-
+@c TODO: Add 'broken chord' to glossary.
 
-@seealso
+Music Glossary: @rglos{arpeggio}
 
-Notation manual: @ref{Ties}, for writing out arpeggios.
+Notation Reference: @ref{Ties}, for writing out arpeggios.
 
-Snippets: @lsrdir{expressive}
+Snippets: @lsrdir{Expressive,Expressive-marks}
 
-Internals Reference: @internalsref{Arpeggio}.
+Internals Reference: @internalsref{Arpeggio},
+@internalsref{PianoStaff}.
 
 
-@refbugs
+@knownissues
 
 It is not possible to mix connected arpeggios and unconnected
-arpeggios in one @internalsref{PianoStaff} at the same point in
+arpeggios in one @code{PianoStaff} at the same point in
 time.
 
 
 @node Trills
-@unnumberedsubsubsec Trills
+@subsubsection Trills
 
-Short trills are printed with @code{\trill} like normal
+@cindex trills
+@funindex \trill
+
+Short @notation{trills} are printed with @code{\trill} like normal
 articulation; see @ref{Articulations and ornamentations}.
 
-Long running trills are made with @code{\startTrillSpan} and
-@code{\stopTrillSpan}. In the following example, it is shown in
-the common combination with grace notes.  If a more precise
-control of the placement of the grace notes is needed, see
-@ref{Grace notes}.
+Long running @notation{trills} are made with
+@code{\startTrillSpan} and @code{\stopTrillSpan}.  In the
+following example, a long running @notation{trill} is shown
+combined with grace notes.  To achieve precise control of the
+placement of the grace notes, see @ref{Grace notes}.
 
-@lilypond[verbatim,ragged-right,relative=2,quote,fragment]
-\relative c''
-{c1 \afterGrace 
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c1 \afterGrace
 d1\startTrillSpan { c16[\stopTrillSpan d] }
-c4 }
+c4
 @end lilypond
 
-@cindex Pitched trills
+@cindex pitched trills
+
+@notation{Trills} that should be executed on an explicitly
+specified pitch can be typeset with the command
+@code{\pitchedTrill} using the following syntax:
 
-Trills that should be executed on an explicitly specified pitch
-can be typeset with the command @code{pitchedTrill}, and the
-syntax @code{\pitchedTrill} @var{mainnote}@code{\startTrillSpan}
-@var{trillnote} @var{endnote} @code{\stopTrillSpan}.
+@example
+@code{\pitchedTrill} @var{mainnote} @code{\startTrillSpan}
+@var{trillnote} @var{endnote} @code{\stopTrillSpan}
+@end example
 
-@lilypond[ragged-right,verbatim,fragment,relative=1,quote]
+@lilypond[verbatim,quote,ragged-right,fragment,relative=1]
 \pitchedTrill e2 \startTrillSpan fis
 d\stopTrillSpan
 @end lilypond
 
-
 @noindent
 The first argument is the main note.  The pitch of the second is
 printed as a stemless note head in parentheses.
 
 
-@refcommands
+@predefined
 
 @code{\startTrillSpan},
 @funindex \startTrillSpan
@@ -758,10 +805,8 @@ printed as a stemless note head in parentheses.
 
 @seealso
 
-Snippets: @lsrdir{expressive}
-
-Internals Reference: @internalsref{TrillSpanner}.
-
-
+Music Glossary: @rglos{trill}
 
+Snippets: @lsrdir{Expressive,Expressive-marks}
 
+Internals Reference: @internalsref{TrillSpanner}