Doc: Updates to CG, Extending, LM and Paper-defaults.ly

[lilypond.git] / Documentation / extending / scheme-tutorial.itely

diff --git a/Documentation/extending/scheme-tutorial.itely b/Documentation/extending/scheme-tutorial.itely
index e34ea9afdbc265d53abbd8cb0b16ebcd31f41081..f8f23a5fa4510fb32ccace3a55a1ca41134e9494 100644 (file)
--- a/Documentation/extending/scheme-tutorial.itely
+++ b/Documentation/extending/scheme-tutorial.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.15.20"
+@c \version "2.19.22"

 
 @node Scheme tutorial
 @chapter Scheme tutorial
 
 @node Scheme tutorial
 @chapter Scheme tutorial


@@ -72,7 +72,7 @@ see @rlearning{Other sources of information}.  Alternatively, Windows
 users may simply choose @q{Run} from the Start menu and enter
 @q{guile}.
 
 users may simply choose @q{Run} from the Start menu and enter
 @q{guile}.
 

-However, a hands-on Scheme sandbox with all of Lilypond loaded is
+However, a hands-on Scheme sandbox with all of LilyPond loaded is

 available with this command line:
 @example
 lilypond scheme-sandbox
 available with this command line:
 @example
 lilypond scheme-sandbox


@@ -209,7 +209,15 @@ For a complete listing see the Guile reference guide,
 There are also compound data types in Scheme.  The  types commonly used in
 LilyPond programming include pairs, lists, alists, and hash tables.
 
 There are also compound data types in Scheme.  The  types commonly used in
 LilyPond programming include pairs, lists, alists, and hash tables.
 

-@subheading Pairs
+@menu
+* Pairs::
+* Lists::
+* Association lists (alists)::
+* Hash tables::
+@end menu
+
+@node Pairs
+@unnumberedsubsubsec Pairs

 
 The foundational compound data type of Scheme is the @code{pair}.  As
 might be expected from its name, a pair is two values glued together.
 
 The foundational compound data type of Scheme is the @code{pair}.  As
 might be expected from its name, a pair is two values glued together.


@@ -250,7 +258,7 @@ Scheme procedures @code{car} and @code{cdr}, respectively.
 
 @lisp
 guile> (define mypair (cons 123 "hello there")
 
 @lisp
 guile> (define mypair (cons 123 "hello there")

-... )
+@dots{} )

 guile> (car mypair)
 123
 guile> (cdr mypair)
 guile> (car mypair)
 123
 guile> (cdr mypair)


@@ -264,11 +272,13 @@ Note:  @code{cdr} is pronounced "could-er", according Sussman and
 Abelson, see
 @uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
 
 Abelson, see
 @uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
 

-@subheading Lists
+@node Lists
+@unnumberedsubsubsec Lists

 
 

-A very common Scheme data structure is the @emph{list}.  Formally, a
-list is defined as either the empty list (represented as @code{'()},
-or a pair whose @code{cdr} is a list.
+A very common Scheme data structure is the @emph{list}.  Formally,
+a @q{proper} list is defined to be either the empty list with its
+input form @code{'()} and length@tie{}0, or a pair whose
+@code{cdr} in turn is a shorter list.

 
 There are many ways of creating lists.  Perhaps the most common is
 with the @code{list} procedure:
 
 There are many ways of creating lists.  Perhaps the most common is
 with the @code{list} procedure:


@@ -294,7 +304,8 @@ Lists are a central part of Scheme.  In, fact, Scheme is considered
 a dialect of lisp, where @q{lisp} is an abbreviation for
 @q{List Processing}.  Scheme expressions are all lists.
 
 a dialect of lisp, where @q{lisp} is an abbreviation for
 @q{List Processing}.  Scheme expressions are all lists.
 

-@subheading Association lists (alists)
+@node Association lists (alists)
+@unnumberedsubsubsec Association lists (alists)

 
 A special type of list is an @emph{association list} or @emph{alist}.
 An alist is used to store data for easy retrieval.
 
 A special type of list is an @emph{association list} or @emph{alist}.
 An alist is used to store data for easy retrieval.


@@ -318,7 +329,8 @@ guile>
 
 Alists are widely used in LilyPond to store properties and other data.
 
 
 Alists are widely used in LilyPond to store properties and other data.
 

-@subheading Hash tables
+@node Hash tables
+@unnumberedsubsubsec Hash tables

 
 A data structure that is used occasionally in LilyPond.  A hash table
 is similar to an array, but the indexes to the array can be any type
 
 A data structure that is used occasionally in LilyPond.  A hash table
 is similar to an array, but the indexes to the array can be any type


@@ -488,7 +500,14 @@ Scheme procedures are executable scheme expressions that return a
 value resulting from their execution.  They can also manipulate
 variables defined outside of the procedure.
 
 value resulting from their execution.  They can also manipulate
 variables defined outside of the procedure.
 

-@subheading Defining procedures
+@menu
+* Defining procedures::
+* Predicates::
+* Return values::
+@end menu
+
+@node Defining procedures
+@unnumberedsubsubsec Defining procedures

 
 Procedures are defined in Scheme with define
 
 
 Procedures are defined in Scheme with define
 


@@ -514,7 +533,8 @@ guile> (average 3 12)
 15/2
 @end lisp
 
 15/2
 @end lisp
 

-@subheading Predicates
+@node Predicates
+@unnumberedsubsubsec Predicates

 
 Scheme procedures that return boolean values are often called
 @emph{predicates}.  By convention (but not necessity), predicate names
 
 Scheme procedures that return boolean values are often called
 @emph{predicates}.  By convention (but not necessity), predicate names


@@ -528,7 +548,8 @@ guile> (less-than-ten? 15)
 #f
 @end lisp
 
 #f
 @end lisp
 

-@subheading Return values
+@node Return values
+@unnumberedsubsubsec Return values

 
 Scheme procedures always return a return value, which is the value
 of the last expression executed in the procedure.  The return
 
 Scheme procedures always return a return value, which is the value
 of the last expression executed in the procedure.  The return


@@ -554,14 +575,20 @@ statement in the let block:
 
 @lisp
 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
 
 @lisp
 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))

-... (+ (* x y) (/ z x)))
+@dots{} (+ (* x y) (/ z x)))

 508
 @end lisp
 
 @node Scheme conditionals
 @subsection Scheme conditionals
 
 508
 @end lisp
 
 @node Scheme conditionals
 @subsection Scheme conditionals
 

-@subheading if
+@menu
+* if::
+* cond::
+@end menu
+
+@node if
+@unnumberedsubsubsec if

 
 Scheme has an @code{if} procedure:
 
 
 Scheme has an @code{if} procedure:
 


@@ -581,14 +608,15 @@ guile> (if (> a b) "a is greater than b" "a is not greater than b")
 "a is not greater than b"
 @end lisp
 
 "a is not greater than b"
 @end lisp
 

-@subheading cond
+@node cond
+@unnumberedsubsubsec cond

 
 Another conditional procedure in scheme is @code{cond}:
 
 @example
 (cond (test-expression-1 result-expression-sequence-1)
       (test-expression-2 result-expression-sequence-2)
 
 Another conditional procedure in scheme is @code{cond}:
 
 @example
 (cond (test-expression-1 result-expression-sequence-1)
       (test-expression-2 result-expression-sequence-2)

-      ...
+      @dots{}

       (test-expression-n result-expression-sequence-n))
 @end example
 
       (test-expression-n result-expression-sequence-n))
 @end example
 


@@ -611,6 +639,7 @@ guile> (cond ((< a b) "a is less than b")
 * LilyPond Scheme syntax::
 * LilyPond variables::
 * Input variables and Scheme::
 * LilyPond Scheme syntax::
 * LilyPond variables::
 * Input variables and Scheme::

+* Importing Scheme in LilyPond::

 * Object properties::
 * LilyPond compound variables::
 * Internal music representation::
 * Object properties::
 * LilyPond compound variables::
 * Internal music representation::


@@ -632,7 +661,7 @@ Now LilyPond's input is structured into tokens and expressions, much
 like human language is structured into words and sentences.  LilyPond
 has a lexer that recognizes tokens (literal numbers, strings, Scheme
 elements, pitches and so on), and a parser that understands the syntax,
 like human language is structured into words and sentences.  LilyPond
 has a lexer that recognizes tokens (literal numbers, strings, Scheme
 elements, pitches and so on), and a parser that understands the syntax,

-@ruser{LilyPond grammar}.  Once it knows that a particular syntax rule
+@rcontrib{LilyPond grammar}.  Once it knows that a particular syntax rule

 applies, it executes actions associated with it.
 
 The hash mark@tie{}@code{#} method of embedding Scheme is a natural fit
 applies, it executes actions associated with it.
 
 The hash mark@tie{}@code{#} method of embedding Scheme is a natural fit


@@ -651,7 +680,7 @@ feasible.
 
 Another way to call the Scheme interpreter from LilyPond is the use of
 dollar@tie{}@code{$} instead of a hash mark for introducing Scheme
 
 Another way to call the Scheme interpreter from LilyPond is the use of
 dollar@tie{}@code{$} instead of a hash mark for introducing Scheme

-expressions.  In this case, Lilypond evaluates the code right after the
+expressions.  In this case, LilyPond evaluates the code right after the

 lexer has read it.  It checks the resulting type of the Scheme
 expression and then picks a token type (one of several
 @code{xxx_IDENTIFIER} in the syntax) for it.  It creates a @emph{copy}
 lexer has read it.  It checks the resulting type of the Scheme
 expression and then picks a token type (one of several
 @code{xxx_IDENTIFIER} in the syntax) for it.  It creates a @emph{copy}


@@ -659,15 +688,24 @@ of the value and uses that for the value of the token.  If the value of
 the expression is void (Guile's value of @code{*unspecified*}), nothing
 at all is passed to the parser.
 
 the expression is void (Guile's value of @code{*unspecified*}), nothing
 at all is passed to the parser.
 

-This is, in fact, exactly the same mechanism that Lilypond employs when
+This is, in fact, exactly the same mechanism that LilyPond employs when

 you call any variable or music function by name, as @code{\name}, with
 you call any variable or music function by name, as @code{\name}, with

-the only difference that its end is determined by the Lilypond lexer
+the only difference that the name is determined by the LilyPond lexer

 without consulting the Scheme reader, and thus only variable names
 without consulting the Scheme reader, and thus only variable names

-consistent with the current Lilypond mode are accepted.
+consistent with the current LilyPond mode are accepted.
+
+The immediate action of @code{$} can lead to surprises, see
+@ref{Importing Scheme in LilyPond}.  Using @code{#} where the
+parser supports it is usually preferable.  Inside of music expressions,
+expressions created using @code{#} @emph{are} interpreted as
+music.  However, they are @emph{not} copied before use.  If they are
+part of some structure that might still get used, you may need to use
+@code{ly:music-deep-copy} explicitly.

 
 

-The immediate action of @code{$} can lead to surprises, @ref{Input
-variables and Scheme}.  Using @code{#} where the parser supports it is
-usually preferable.
+@funindex $@@
+@funindex #@@
+There are also @q{list splicing} operators @code{$@@} and @code{#@@}
+that insert all elements of a list in the surrounding context.

 
 Now let's take a look at some actual Scheme code.  Scheme procedures can
 be defined in LilyPond input files:
 
 Now let's take a look at some actual Scheme code.  Scheme procedures can
 be defined in LilyPond input files:


@@ -693,11 +731,11 @@ as follows:
 @end example
 
 For the rest of this section, we will assume that the data is entered
 @end example
 
 For the rest of this section, we will assume that the data is entered

-in a music file, so we add@tie{}@code{#}s at the beginning of each Scheme
+in a music file, so we add a @code{#} at the beginning of each Scheme

 expression.
 
 All of the top-level Scheme expressions in a LilyPond input file can
 expression.
 
 All of the top-level Scheme expressions in a LilyPond input file can

-be combined into a single Scheme expression by the use of the
+be combined into a single Scheme expression by use of the

 @code{begin} statement:
 
 @example
 @code{begin} statement:
 
 @example


@@ -735,8 +773,8 @@ twentyFour = #(* 2 twelve)
 which would result in the number 24 being stored in the
 LilyPond (and Scheme) variable @code{twentyFour}.
 
 which would result in the number 24 being stored in the
 LilyPond (and Scheme) variable @code{twentyFour}.
 

-The usual way to refer to Lilypond variables, @ref{LilyPond Scheme
-syntax}, is to call them using a backslash, i.e., @code{\twentyFour}.
+The usual way to refer to LilyPond variables is to call them using a
+backslash, i.e., @code{\twentyFour} (see @ref{LilyPond Scheme syntax}).

 Since this creates a copy of the value for most of LilyPond's internal
 types, in particular music expressions, music functions don't usually
 create copies of material they change.  For this reason, music
 Since this creates a copy of the value for most of LilyPond's internal
 types, in particular music expressions, music functions don't usually
 create copies of material they change.  For this reason, music


@@ -783,7 +821,7 @@ traLaLa = @{ c'4 d'4 @}
 is internally converted to a Scheme definition:
 
 @example
 is internally converted to a Scheme definition:
 
 @example

-(define traLaLa @var{Scheme value of `@code{... }'})
+(define traLaLa @var{Scheme value of `@code{@dots{}}'})

 @end example
 
 This means that LilyPond variables and Scheme variables may be freely
 @end example
 
 This means that LilyPond variables and Scheme variables may be freely


@@ -800,7 +838,7 @@ traLaLa = { c'4 d'4 }
 #(define twice
   (make-sequential-music newLa))
 
 #(define twice
   (make-sequential-music newLa))
 

-{ \twice }
+\twice

 @end lilypond
 
 @c Due to parser lookahead
 @end lilypond
 
 @c Due to parser lookahead


@@ -812,6 +850,11 @@ reads @code{#} and the following Scheme expression @emph{without}
 evaluating it, so it can go ahead with the assignment, and
 @emph{afterwards} execute the Scheme code without problem.
 
 evaluating it, so it can go ahead with the assignment, and
 @emph{afterwards} execute the Scheme code without problem.
 

+@node Importing Scheme in LilyPond
+@subsection Importing Scheme in LilyPond
+@funindex $
+@funindex #
+

 The above example shows how to @q{export} music expressions from the
 input to the Scheme interpreter.  The opposite is also possible.  By
 placing it after @code{$}, a Scheme
 The above example shows how to @q{export} music expressions from the
 input to the Scheme interpreter.  The opposite is also possible.  By
 placing it after @code{$}, a Scheme


@@ -820,14 +863,14 @@ Instead of defining @code{\twice}, the example above could also have
 been written as
 
 @example
 been written as
 
 @example

-...
-@{ $(make-sequential-music (list newLa)) @}
+@dots{}
+$(make-sequential-music newLa)

 @end example
 
 You can use @code{$} with a Scheme expression anywhere you could use
 @code{\@var{name}} after having assigned the Scheme expression to a
 variable @var{name}.  This replacement happens in the @q{lexer}, so
 @end example
 
 You can use @code{$} with a Scheme expression anywhere you could use
 @code{\@var{name}} after having assigned the Scheme expression to a
 variable @var{name}.  This replacement happens in the @q{lexer}, so

-Lilypond is not even aware of the difference.
+LilyPond is not even aware of the difference.

 
 One drawback, however, is that of timing.  If we had been using @code{$}
 instead of @code{#} for defining @code{newLa} in the above example, the
 
 One drawback, however, is that of timing.  If we had been using @code{$}
 instead of @code{#} for defining @code{newLa} in the above example, the


@@ -835,15 +878,35 @@ following Scheme definition would have failed because @code{traLaLa}
 would not yet have been defined.  For an explanation of this timing
 problem, @ref{LilyPond Scheme syntax}.
 
 would not yet have been defined.  For an explanation of this timing
 problem, @ref{LilyPond Scheme syntax}.
 

-In any case, evaluation of Scheme code happens in the parser at latest.
-If you need it to be executed at a later point of time, @ref{Void scheme
-functions}, or store it in a macro:
+@funindex $@@
+@funindex #@@
+A further convenience can be the @q{list splicing} operators @code{$@@}
+and @code{#@@} for inserting the elements of a list in the surrounding
+context.  Using those, the last part of the example could have been
+written as
+
+@example
+@dots{}
+@{ #@@newLa @}
+@end example
+
+Here, every element of the list stored in @code{newLa} is taken in
+sequence and inserted into the list, as if we had written
+
+@example
+@{ #(first newLa) #(second newLa) @}
+@end example
+
+Now in all of these forms, the Scheme code is evaluated while the
+input is still being consumed, either in the lexer or in the parser.
+If you need it to be executed at a later point of time, check out
+@ref{Void scheme functions}, or store it in a procedure:

 
 @example
 #(define (nopc)
   (ly:set-option 'point-and-click #f))
 
 
 @example
 #(define (nopc)
   (ly:set-option 'point-and-click #f))
 

-...
+@dots{}

 #(nopc)
 @{ c'4 @}
 @end example
 #(nopc)
 @{ c'4 @}
 @end example


@@ -867,7 +930,7 @@ the alist with both a key and a value.  The LilyPond syntax for doing
 this is:
 
 @example
 this is:
 
 @example

-\override Stem #'thickness = #2.6
+\override Stem.thickness = #2.6

 @end example
 
 This instruction adjusts the appearance of stems.  An alist entry
 @end example
 
 This instruction adjusts the appearance of stems.  An alist entry


@@ -892,14 +955,23 @@ while @code{twentyFour} is a variable.
 @node LilyPond compound variables
 @subsection LilyPond compound variables
 
 @node LilyPond compound variables
 @subsection LilyPond compound variables
 

-@subheading Offsets
+@menu
+* Offsets::
+* Fractions::
+* Extents::
+* Property alists::
+* Alist chains::
+@end menu
+
+@node Offsets
+@unnumberedsubsubsec Offsets

 
 Two-dimensional offsets (X and Y coordinates) are stored as @emph{pairs}.
 The @code{car} of the offset is the X coordinate, and the @code{cdr} is
 the Y coordinate.
 
 @example
 
 Two-dimensional offsets (X and Y coordinates) are stored as @emph{pairs}.
 The @code{car} of the offset is the X coordinate, and the @code{cdr} is
 the Y coordinate.
 
 @example

-\override TextScript #'extra-offset = #'(1 . 2)
+\override TextScript.extra-offset = #'(1 . 2)

 @end example
 
 This assigns the pair @code{(1 . 2)} to the @code{extra-offset}
 @end example
 
 This assigns the pair @code{(1 . 2)} to the @code{extra-offset}


@@ -909,7 +981,8 @@ this command moves the object 1 staff space to the right, and 2 spaces up.
 
 Procedures for working with offsets are found in @file{scm/lily-library.scm}.
 
 
 Procedures for working with offsets are found in @file{scm/lily-library.scm}.
 

-@subheading Fractions
+@node Fractions
+@unnumberedsubsubsec Fractions

 
 Fractions as used by LilyPond are again stored as @emph{pairs}, this
 time of unsigned integers.  While Scheme can represent rational numbers
 
 Fractions as used by LilyPond are again stored as @emph{pairs}, this
 time of unsigned integers.  While Scheme can represent rational numbers


@@ -919,7 +992,8 @@ no negative @q{fractions} in LilyPond's mind.  So @code{2/4} in LilyPond
 means @code{(2 . 4)} in Scheme, and @code{#2/4} in LilyPond means
 @code{1/2} in Scheme.
 
 means @code{(2 . 4)} in Scheme, and @code{#2/4} in LilyPond means
 @code{1/2} in Scheme.
 

-@subheading Extents
+@node Extents
+@unnumberedsubsubsec Extents

 
 Pairs are also used to store intervals, which represent a range of numbers
 from the minimum (the @code{car}) to the maximum (the @code{cdr}).
 
 Pairs are also used to store intervals, which represent a range of numbers
 from the minimum (the @code{car}) to the maximum (the @code{cdr}).


@@ -932,7 +1006,8 @@ Procedures for working with intervals are found in
 @file{scm/lily-library.scm}.  These procedures should be used when possible
 to ensure consistency of code.
 
 @file{scm/lily-library.scm}.  These procedures should be used when possible
 to ensure consistency of code.
 

-@subheading Property alists
+@node Property alists
+@unnumberedsubsubsec Property alists

 
 A property alist is a LilyPond data structure that is an alist whose
 keys are properties and whose values are Scheme expressions that give
 
 A property alist is a LilyPond data structure that is an alist whose
 keys are properties and whose values are Scheme expressions that give


@@ -940,7 +1015,8 @@ the desired value for the property.
 
 LilyPond properties are Scheme symbols, such as @code{'thickness}.
 
 
 LilyPond properties are Scheme symbols, such as @code{'thickness}.
 

-@subheading Alist chains
+@node Alist chains
+@unnumberedsubsubsec Alist chains

 
 An alist chain is a list containing property alists.
 
 
 An alist chain is a list containing property alists.
 


@@ -1029,7 +1105,7 @@ to create complicated music functions.
 
 When writing a music function it is often instructive to inspect how
 a music expression is stored internally.  This can be done with the
 
 When writing a music function it is often instructive to inspect how
 a music expression is stored internally.  This can be done with the

-music function @code{\displayMusic}
+music function @code{\displayMusic}.

 
 @example
 @{
 
 @example
 @{


@@ -1052,51 +1128,58 @@ will display
                   'text
                   "f"))
           'duration
                   'text
                   "f"))
           'duration

-          (ly:make-duration 2 0 1 1)
+          (ly:make-duration 2 0 1/1)

           'pitch
           (ly:make-pitch 0 0 0))))
 @end example
 
 By default, LilyPond will print these messages to the console along
 with all the other messages.  To split up these messages and save
           'pitch
           (ly:make-pitch 0 0 0))))
 @end example
 
 By default, LilyPond will print these messages to the console along
 with all the other messages.  To split up these messages and save

-the results of @code{\display@{STUFF@}}, redirect the output to
-a file.
+the results of @code{\display@{STUFF@}}, you can specify an optional
+output port to use:

 
 @example
 
 @example

-lilypond file.ly >display.txt
+@{
+  \displayMusic #(open-output-file "display.txt") @{ c'4\f @}
+@}

 @end example
 
 @end example
 

-With a combined bit of Lilypond and Scheme magic, you can actually
-let Lilypond direct just this output to a file of its own:
-
+This will overwrite a previous output file whenever it is called; if you
+need to write more than one expression, you would use a variable for
+your port and reuse it:

 @example
 @{
 @example
 @{

-  $(with-output-to-file "display.txt"
-      (lambda () #@{ \displayMusic @{ c'4\f @} #@}))
+  port = #(open-output-file "display.txt")
+  \displayMusic \port @{ c'4\f @}
+  \displayMusic \port @{ d'4 @}
+  #(close-output-port port)

 @}
 @end example
 
 @}
 @end example
 

+Guile's manual describes ports in detail.  Closing the port is actually
+only necessary if you need to read the file before LilyPond finishes; in
+the first example, we did not bother to do so.

 
 A bit of reformatting makes the above information easier to read:
 
 @example
 (make-music 'SequentialMusic
   'elements (list
 
 A bit of reformatting makes the above information easier to read:
 
 @example
 (make-music 'SequentialMusic
   'elements (list

-            (make-music 'NoteEvent
+             (make-music 'NoteEvent

                'articulations (list
                'articulations (list

-                              (make-music 'AbsoluteDynamicEvent
-                                'text
-                                "f"))
-              'duration (ly:make-duration 2 0 1 1)
-              'pitch    (ly:make-pitch 0 0 0))))
+                               (make-music 'AbsoluteDynamicEvent
+                                           'text
+                                           "f"))
+               'duration (ly:make-duration 2 0 1/1)
+               'pitch    (ly:make-pitch 0 0 0))))

 @end example
 
 @end example
 

-A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
-and its inner expressions are stored as a list in its @code{'elements}
-property.  A note is represented as a @code{NoteEvent} object (storing
-the duration and pitch properties) with attached information (in this
-case, an @code{AbsoluteDynamicEvent} with a @code{"f"} text property)
-stored in its @code{articulations} property.
+A @code{@{ @dots{} @}} music sequence has the name
+@code{SequentialMusic}, and its inner expressions are stored as a list
+in its @code{'elements} property.  A note is represented as a
+@code{NoteEvent} object (storing the duration and pitch properties) with
+attached information (in this case, an @code{AbsoluteDynamicEvent} with
+a @code{"f"} text property) stored in its @code{articulations} property.

 
 @funindex{\void}
 @code{\displayMusic} returns the music it displays, so it will get
 
 @funindex{\void}
 @code{\displayMusic} returns the music it displays, so it will get


@@ -1106,9 +1189,11 @@ interpreted as well as displayed.  To avoid interpretation, write
 @node Music properties
 @subsection Music properties
 
 @node Music properties
 @subsection Music properties
 

+@ignore

 TODO -- make sure we delineate between @emph{music} properties,
 @emph{context} properties, and @emph{layout} properties.  These
 are potentially confusing.
 TODO -- make sure we delineate between @emph{music} properties,
 @emph{context} properties, and @emph{layout} properties.  These
 are potentially confusing.

+@end ignore

 
 Let's look at an example:
 
 
 Let's look at an example:
 


@@ -1119,7 +1204,7 @@ someNote = c'
 (make-music
   'NoteEvent
   'duration
 (make-music
   'NoteEvent
   'duration

-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)

   'pitch
   (ly:make-pitch 0 0 0))
 @end example
   'pitch
   (ly:make-pitch 0 0 0))
 @end example


@@ -1137,7 +1222,7 @@ someNote = <c'>
   (list (make-music
           'NoteEvent
           'duration
   (list (make-music
           'NoteEvent
           'duration

-          (ly:make-duration 2 0 1 1)
+          (ly:make-duration 2 0 1/1)

           'pitch
           (ly:make-pitch 0 0 0))))
 @end example
           'pitch
           (ly:make-pitch 0 0 0))))
 @end example


@@ -1155,13 +1240,13 @@ expression.
 (make-music
   'NoteEvent
   'duration
 (make-music
   'NoteEvent
   'duration

-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)

   'pitch
   (ly:make-pitch 0 0 0))
 @end example
 
 Then the note pitch is accessed through the @code{'pitch} property
   'pitch
   (ly:make-pitch 0 0 0))
 @end example
 
 Then the note pitch is accessed through the @code{'pitch} property

-of the @code{NoteEvent} object,
+of the @code{NoteEvent} object.

 
 @example
 #(display-scheme-music
 
 @example
 #(display-scheme-music


@@ -1171,7 +1256,7 @@ of the @code{NoteEvent} object,
 (ly:make-pitch 0 0 0)
 @end example
 
 (ly:make-pitch 0 0 0)
 @end example
 

-The note pitch can be changed by setting this @code{'pitch} property,
+The note pitch can be changed by setting this @code{'pitch} property.

 
 @funindex \displayLilyMusic
 
 
 @funindex \displayLilyMusic
 


@@ -1181,7 +1266,7 @@ The note pitch can be changed by setting this @code{'pitch} property,
        (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
 \displayLilyMusic \someNote
 ===>
        (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
 \displayLilyMusic \someNote
 ===>

-d'
+d'4

 @end example
 
 
 @end example
 
 


@@ -1206,7 +1291,7 @@ representation of the desired result.
                   'span-direction
                   -1))
           'duration
                   'span-direction
                   -1))
           'duration

-          (ly:make-duration 2 0 1 1)
+          (ly:make-duration 2 0 1/1)

           'pitch
           (ly:make-pitch 0 5 0))
         (make-music
           'pitch
           (ly:make-pitch 0 5 0))
         (make-music


@@ -1217,7 +1302,7 @@ representation of the desired result.
                   'span-direction
                   1))
           'duration
                   'span-direction
                   1))
           'duration

-          (ly:make-duration 2 0 1 1)
+          (ly:make-duration 2 0 1/1)

           'pitch
           (ly:make-pitch 0 5 0))))
 @end example
           'pitch
           (ly:make-pitch 0 5 0))))
 @end example


@@ -1226,7 +1311,7 @@ The bad news is that the @code{SlurEvent} expressions
 must be added @q{inside} the note (in its @code{articulations}
 property).
 
 must be added @q{inside} the note (in its @code{articulations}
 property).
 

-Now we examine the input,
+Now we examine the input.

 
 @example
 \displayMusic a'
 
 @example
 \displayMusic a'


@@ -1234,7 +1319,7 @@ Now we examine the input,
 (make-music
   'NoteEvent
   'duration
 (make-music
   'NoteEvent
   'duration

-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)

   'pitch
   (ly:make-pitch 0 5 0))))
 @end example
   'pitch
   (ly:make-pitch 0 5 0))))
 @end example


@@ -1242,13 +1327,13 @@ Now we examine the input,
 So in our function, we need to clone this expression (so that we have
 two notes to build the sequence), add a @code{SlurEvent} to the
 @code{'articulations} property of each one, and finally make a
 So in our function, we need to clone this expression (so that we have
 two notes to build the sequence), add a @code{SlurEvent} to the
 @code{'articulations} property of each one, and finally make a

-@code{SequentialMusic} with the two @code{EventChords}.  For adding to a
+@code{SequentialMusic} with the two @code{NoteEvent} elements.  For adding to a

 property, it is useful to know that an unset property is read out as
 @code{'()}, the empty list, so no special checks are required before we
 put another element at the front of the @code{articulations} property.
 
 @example
 property, it is useful to know that an unset property is read out as
 @code{'()}, the empty list, so no special checks are required before we
 put another element at the front of the @code{articulations} property.
 
 @example

-doubleSlur = #(define-music-function (parser location note) (ly:music?)
+doubleSlur = #(define-music-function (note) (ly:music?)

          "Return: @{ note ( note ) @}.
          `note' is supposed to be a single note."
          (let ((note2 (ly:music-deep-copy note)))
          "Return: @{ note ( note ) @}.
          `note' is supposed to be a single note."
          (let ((note2 (ly:music-deep-copy note)))


@@ -1266,14 +1351,14 @@ doubleSlur = #(define-music-function (parser location note) (ly:music?)
 @subsection Adding articulation to notes (example)
 
 The easy way to add articulation to notes is to merge two music
 @subsection Adding articulation to notes (example)
 
 The easy way to add articulation to notes is to merge two music

-expressions into one context, as explained in @ruser{Creating contexts}.
+expressions into one context.

 However, suppose that we want to write a music function that does this.
 This will have the additional advantage that we can use that music
 function to add an articulation (like a fingering instruction) to a
 single note inside of a chord which is not possible if we just merge
 independent music.
 
 However, suppose that we want to write a music function that does this.
 This will have the additional advantage that we can use that music
 function to add an articulation (like a fingering instruction) to a
 single note inside of a chord which is not possible if we just merge
 independent music.
 

-A @code{$variable} inside the @code{#@{...#@}} notation is like
+A @code{$variable} inside the @code{#@{@dots{}#@}} notation is like

 a regular @code{\variable} in classical LilyPond notation.  We
 know that
 
 a regular @code{\variable} in classical LilyPond notation.  We
 know that
 


@@ -1283,15 +1368,15 @@ know that
 
 @noindent
 will not work in LilyPond.  We could avoid this problem by attaching
 
 @noindent
 will not work in LilyPond.  We could avoid this problem by attaching

-the articulation to a fake note,
+the articulation to an empty chord,

 
 @example
 
 @example

-@{ << \music s1*0-.-> @}
+@{ << \music <> -. -> >> @}

 @end example
 
 @noindent
 but for the sake of this example, we will learn how to do this in
 @end example
 
 @noindent
 but for the sake of this example, we will learn how to do this in

-Scheme.  We begin by examining our input and desired output,
+Scheme.  We begin by examining our input and desired output.

 
 @example
 %  input
 
 @example
 %  input


@@ -1300,7 +1385,7 @@ Scheme.  We begin by examining our input and desired output,
 (make-music
   'NoteEvent
   'duration
 (make-music
   'NoteEvent
   'duration

-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)

   'pitch
   (ly:make-pitch -1 0 0))))
 =====
   'pitch
   (ly:make-pitch -1 0 0))))
 =====


@@ -1315,7 +1400,7 @@ Scheme.  We begin by examining our input and desired output,
           'articulation-type
           "accent"))
   'duration
           'articulation-type
           "accent"))
   'duration

-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)

   'pitch
   (ly:make-pitch -1 0 0))
 @end example
   'pitch
   (ly:make-pitch -1 0 0))
 @end example


@@ -1345,7 +1430,7 @@ from its name.  (this is good practice in other programming languages,
 too!)
 
 @example
 too!)
 
 @example

-"Add an accent..."
+"Add an accent@dots{}"

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -1424,7 +1509,7 @@ function (a matter of some syntactic sugar and a declaration of the type
 of its sole @q{real} argument).
 
 @example
 of its sole @q{real} argument).
 
 @example

-addAccent = #(define-music-function (parser location note-event)
+addAccent = #(define-music-function (note-event)

                                      (ly:music?)
   "Add an accent ArticulationEvent to the articulations of `note-event',
   which is supposed to be a NoteEvent expression."
                                      (ly:music?)
   "Add an accent ArticulationEvent to the articulations of `note-event',
   which is supposed to be a NoteEvent expression."


@@ -1435,7 +1520,7 @@ addAccent = #(define-music-function (parser location note-event)
   note-event)
 @end example
 
   note-event)
 @end example
 

-We may verify that this music function works correctly,
+We may verify that this music function works correctly:

 
 @example
 \displayMusic \addAccent c4
 
 @example
 \displayMusic \addAccent c4


@@ -1455,7 +1540,7 @@ We may verify that this music function works correctly,
 
 We have seen how LilyPond output can be heavily modified using
 commands like
 
 We have seen how LilyPond output can be heavily modified using
 commands like

-@code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
+@code{\override TextScript.extra-offset = ( 1 . -1)}.  But

 we have even more power if we use Scheme.  For a full explanation
 of this, see the @ref{Scheme tutorial}, and
 @ref{Interfaces for programmers}.
 we have even more power if we use Scheme.  For a full explanation
 of this, see the @ref{Scheme tutorial}, and
 @ref{Interfaces for programmers}.


@@ -1469,13 +1554,13 @@ TODO Find a simple example
 
 @ignore
 @lilypond[quote,verbatim,ragged-right]
 
 @ignore
 @lilypond[quote,verbatim,ragged-right]

-padText = #(define-music-function (parser location padding) (number?)
+padText = #(define-music-function (padding) (number?)

 #{
 #{

-  \once \override TextScript #'padding = #padding
+  \once \override TextScript.padding = #padding

 #})
 
 #})
 

-\relative c''' {
-  c4^"piu mosso" b a b
+\relative {
+  c'''4^"piu mosso" b a b

   \padText #1.8
   c4^"piu mosso" d e f
   \padText #2.6
   \padText #1.8
   c4^"piu mosso" d e f
   \padText #2.6


@@ -1492,17 +1577,17 @@ We can use it to create new commands:
 
 
 @lilypond[quote,verbatim,ragged-right]
 
 
 @lilypond[quote,verbatim,ragged-right]

-tempoPadded = #(define-music-function (parser location padding tempotext)
-  (number? string?)
+tempoPadded = #(define-music-function (padding tempotext)
+  (number? markup?)

 #{
 #{

-  \once \override Score.MetronomeMark #'padding = $padding
+  \once \override Score.MetronomeMark.padding = #padding

   \tempo \markup { \bold #tempotext }
 #})
 
   \tempo \markup { \bold #tempotext }
 #})
 

-\relative c'' {
+\relative {

   \tempo \markup { "Low tempo" }
   \tempo \markup { "Low tempo" }

-  c4 d e f g1
-  \tempoPadded #4.0 #"High tempo"
+  c''4 d e f g1
+  \tempoPadded #4.0 "High tempo"

   g4 f e d c1
 }
 @end lilypond
   g4 f e d c1
 }
 @end lilypond


@@ -1511,9 +1596,9 @@ tempoPadded = #(define-music-function (parser location padding tempotext)
 Even music expressions can be passed in:
 
 @lilypond[quote,verbatim,ragged-right]
 Even music expressions can be passed in:
 
 @lilypond[quote,verbatim,ragged-right]

-pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
+pattern = #(define-music-function (x y) (ly:music? ly:music?)

 #{
 #{

-  $x e8 a b $y b a e
+  #x e8 a b #y b a e

 #})
 
 \relative c''{
 #})
 
 \relative c''{