-@node Scheme tutorial
-@section Scheme tutorial
-
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
-
-LilyPond uses the Scheme programming language, both as part of the
-input syntax, and as internal mechanism to glue together modules of
-the program. This section is a very brief overview of entering data in
-Scheme.@footnote{If you want to know more about Scheme, see
-@uref{http://www.schemers.org}.}
-
-The most basic thing of a language is data: numbers, character
-strings, lists, etc. Here is a list of data types that are relevant to
-LilyPond input.
-
-@table @asis
-@item Booleans
- Boolean values are True or False. The Scheme for True is @code{#t}
- and False is @code{#f}.
-@item Numbers
- Numbers are entered in the standard fashion,
- @code{1} is the (integer) number one, while @code{-1.5} is a
- floating point number (a non-integer number).
-@item Strings
- Strings are enclosed in double quotes,
- @example
- "this is a string"
- @end example
-
- Strings may span several lines
- @example
- "this
- is
- a string"
- @end example
-
- Quotation marks and newlines can also be added with so-called escape
- sequences. The string @code{a said "b"} is entered as
- @example
- "a said \"b\""
- @end example
-
- Newlines and backslashes are escaped with @code{\n} and @code{\\}
-respectively.
-@end table
-
-
-In a music file, snippets of Scheme code are introduced with the hash
-mark @code{#}. So, the previous examples translated in LilyPond are
-
-@example
- ##t ##f
- #1 #-1.5
- #"this is a string"
- #"this
- is
- a string"
-@end example
-
-For the rest of this section, we will assume that the data is entered
-in a music file, so we add @code{#}s everywhere.
-
-Scheme can be used to do calculations. It uses @emph{prefix}
-syntax. Adding 1 and 2 is written as @code{(+ 1 2)} rather than the
-traditional 1+2.
-
-@lisp
- #(+ 1 2)
- @result{} #3
-@end lisp
-
-The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
-is @code{3}. Calculations may be nested; the result of a function may
-be used for another calculation.
-
-@lisp
- #(+ 1 (* 3 4))
- @result{} #(+ 1 12)
- @result{} #13
-@end lisp
-
-These calculations are examples of evaluations; an expression like
-@code{(* 3 4)} is replaced by its value @code{12}. A similar thing
-happens with variables. After defining a variable
-
-@example
- twelve = #12
-@end example
-
-variables can also be used in expressions, here
-
-@example
- twentyFour = #(* 2 twelve)
-@end example
-
-the number 24 is stored in the variable @code{twentyFour}.
-
-The @emph{name} of a variable is also an expression, similar to a
-number or a string. It is entered as
-
-@example
- #'twentyFour
-@end example
-
-The quote mark @code{'} prevents Scheme interpreter from substituting
-@code{24} for the @code{twentyFour}. Instead, we get the name
-@code{twentyFour}.
-
-This syntax will be used very frequently, since many of the layout
-tweaks involve assigning (Scheme) values to internal variables, for
-example
-
-@example
- \override Stem #'thickness = #2.6
-@end example
-
-This instruction adjusts the appearance of stems. The value @code{2.6}
-is put into a the @code{thickness} variable of a @code{Stem}
-object. This makes stems almost twice as thick as their normal size.
-To distinguish between variables defined in input files (like
-@code{twentyFour} in the example above), and internal variables, we
-will call the latter ``properties.'' So, the stem object has a
-@code{thickness} property.
-
-Two-dimensional offsets (X and Y coordinates) as well as object sizes
-(intervals with a left and right point) are entered as @code{pairs}. A
-pair@footnote{In Scheme terminology, the pair is called @code{cons},
-and its two elements are called car and cdr respectively.} is entered
-as @code{(first . second)} and, like symbols, they must be quoted,
-
-@example
- \override TextScript #'extra-offset = #'(1 . 2)
-@end example
-
-This assigns the pair (1, 2) to @code{extra-offset} variable of the
-TextScript object. This moves the object 1 staff space to the right,
-and 2 spaces up.
-
-The two elements of a pair may be arbitrary values, for example
-
-@example
- #'(1 . 2)
- #'(#t . #f)
- #'("blah-blah" . 3.14159265)
-@end example
-
-A list is entered by enclosing its elements in parentheses, and adding
-a quote. For example,
-@example
- #'(1 2 3)
- #'(1 2 "string" #f)
-@end example
-
-We have been using lists all along. A calculation, like @code{(+ 1
-2)} is also a list (containing the symbol @code{+} and the numbers 1
-and 2). Normally lists are interpreted as calculations, and the Scheme
-interpreter substitutes the outcome of the calculation. To enter a
-list, we stop evaluation. This is done by quoting the list with a
-quote @code{'} symbol. For calculations, do not use a quote.
-
-Inside a quoted list or pair, there is no need to quote anymore. The
-following is a pair of symbols, a list of symbols and a list of lists
-respectively,
-
-@example
- #'(stem . head)
- #'(staff clef key-signature)
- #'((1) (2))
-@end example
-
-@node File structure
-@section File structure
-
-The following items may be present in a @file{.ly} file at toplevel
-
-@itemize @bullet
-@item An output definition, such as @code{\bookpaper}, @code{\midi}
-and @code{\paper}. Such a definition at toplevel changes the default
-settings for the block entered.
-
-@item An @code{\header} block. This sets the global header block. This
-is the block containing the definitions for book-wide settings, like
-composer, title, etc.
-
-@item An @code{\addquote} statement. See @ref{Quoting other voices}
-for more information.
-
-@item A @code{\score} block. This score will be collected with other
-toplevel scores, and combined as a single @code{\book}.
-
-This behavior can be changed by setting the variable
-@code{toplevel-score-handler} at toplevel. The default handler is
-defined in the init file @file{scm/lily.scm}.
-
-@item A @code{\book} block formats the block
-
-This behavior can be changed by setting the variable
-@code{toplevel-book-handler} at toplevel. The default handler is
-defined in the init file @file{scm/lily.scm}.
-
-
-@item A compound music expression, such as
-@example
- @{ c'4 d' e'2 @}
-@end example
-
-This will add the piece in a @code{\score}, and formats it into a
-single book together with all other toplevel @code{\score}s and music
-expressions.
-
-This behavior can be changed by setting the variable
-@code{toplevel-music-handler} at toplevel. The default handler is
-defined in the init file @file{scm/lily.scm}.
-
-@end itemize
-
-The following example shows three things which may be entered at
-toplevel
-@verbatim
- \paper {
- % movements are non-justified by default
- raggedright = ##t
- }
-
- \header {
- title = "Do-re-mi"
- }
-
- { c'4 d' e2 }
-@end verbatim
-
-
-At any point in a file, any of the following lexical instructions can
-be entered:
-
-@itemize @bullet
-@item @code{\version}
-@item @code{\include}
-@item @code{\encoding}
-@item @code{\renameinput}
-@end itemize
-
-