@chapter Changing defaults
-The default output
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+The purpose of LilyPond's design is to provide the finest output
+quality as a default. Nevertheless, it may happen that you need to
+change that default layout. The layout is controlled through a large
+number of proverbial ``knobs and switches.'' This chapter does not
+list each and every knob. Rather, it outlines what groups of controls
+are available, and how to tune them.
+
+Which controls are available for tuning is described in a separate
+document, the @internalsref{Program reference} manual. This manual
+lists all different variables, functions and options available in
+LilyPond. It is available as a HTML document, which is available
+@uref{http://lilypond.org/doc/Documentation/user/out-www/lilypond-internals/,on-line},
+but is also included with the LilyPond documentation package.
+
+There are X areas where the default settings may be changed:
+@itemize @bullet
+@item Output: changing the appearance of individual
+ objects
+@item Context: changing the translation from music events to
+ notation
+@item Global layout: changing the appearance of the spacing, line
+ breaks and page dimensions.
+@end itemize
+Then, there are separate systems for typesetting text (like
+@emph{ritardando}) and selecting different fonts. This chapter also
+discusses these.
+Internally, LilyPond uses Scheme (a LISP dialect) to provide
+infrastructure. Since overriding layout decisions in effect
+accesses the program internals, it is necessary to learn a (very
+small) subset of Scheme. That is why this chapter starts with
+a short tutorial on entering numbers, lists, strings and symbols in
+Scheme.
+@menu
+* Scheme tutorial::
+* Setting variables::
+* Fine tuning layout::
+* Tuning output::
+* Text markup::
+* Global layout::
+* Interpretation context::
+* Output details::
+@end menu
+@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 LilyPondese 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 variables, for example
+@example
+ \override Stem #'thickness = #2.5
+@end example
+This instruction adjusts the appearance of stems. The value @code{2.5}
+is put into a the @code{thickness} variable of a @code{Stem}
+object. This makes stems almost twice as thick as their normal size.
+
+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
-TODO: reorganise.
+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.
-@menu
-* Scheme integration::
-* Setting variables::
-* Fine tuning layout::
-* Tuning output::
-* Text markup::
-* Global layout::
-* Interpretation context::
-* Output details::
-@end menu
+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
-@node Scheme integration
-@section Scheme integration
+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). For entering lists, use a quote @code{'} and for
+calculations, do not use a quote.
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
+Inside a quoted list or pair, there is no need to quote anymore. The
+following is a pair and a list of symbols respectively.
+@example
+ #'(stem . head)
+ #'(staff clef key-signature)
+@end example
-LilyPond internally uses GUILE, a Scheme-interpreter, to represent
-data throughout the whole program, and glue together different program
-modules. For advanced usage, it is sometimes necessary to access and
-program the Scheme interpreter.
-
-Scheme is a full-blown programming language, from the LISP
-family. and a full discussion is outside the scope of this document.
-Interested readers are referred to the website
-@uref{http://www.schemers.org/} for more information on Scheme.
-
-The GUILE library for extension is documented at
-@uref{http://www.gnu.org/software/guile}.
-@ifinfo
-When it is installed, the following link should take you to its manual
-@ref{(guile.info)guile}
-@end ifinfo
@menu
* Inline Scheme::
projects / lilypond.git / commitdiff