From: Han-Wen Nienhuys Date: Tue, 16 Mar 2004 01:12:27 +0000 (+0000) Subject: (Scheme tutorial): X-Git-Tag: release/2.1.32~30 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=a7a0b5664e78643a36047d43b9eb4611d256a836;p=lilypond.git (Scheme tutorial): new node. --- diff --git a/ChangeLog b/ChangeLog index e4b2cc184c..cc1871de76 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2004-03-16 Han-Wen Nienhuys + + * Documentation/user/changing-defaults.itely (Scheme tutorial): + new node. + 2004-03-16 Heikki Junes * Documentation/topdocs/INSTALL.texi: finish install orders for vim. @@ -17,6 +22,8 @@ 2004-03-15 Han-Wen Nienhuys + * VERSION (MY_PATCH_LEVEL): release 2.1.31. + * GNUmakefile.in: remove stray make out=www * input/test/bagpipe.ly (gcdg): octave fixes. diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index 842c74d678..79a7c805b3 100644 --- a/Documentation/user/changing-defaults.itely +++ b/Documentation/user/changing-defaults.itely @@ -3,119 +3,219 @@ @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::