]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/internals.itely
(Composite_music): new transpose syntax,
[lilypond.git] / Documentation / user / internals.itely
1 @c -*-texinfo-*-
2 @c Note:
3 @c
4 @c A menu is needed before every deeper *section nesting of @nodes
5 @c Run M-x texinfo-all-menus-update
6 @c to automagically fill in these menus
7 @c before saving changes
8
9
10 @node Advanced Topics
11 @chapter Advanced Topics
12
13
14 When translating the input to notation, there are number of distinct
15 phases.  We list them here:
16
17 @c todo: moved from refman. 
18
19 The purpose of LilyPond is explained informally by the term `music
20 typesetter'.  This is not a fully correct name: Not only does the
21 program print musical symbols, it also makes aesthetic decisions.
22 Symbols and their placements are @emph{generated} from a high-level
23 musical description.  In other words, LilyPond would be best described
24 to be a `music compiler' or `music to notation compiler'.
25
26 LilyPond is linked to GUILE, GNU's Scheme library for extension
27 programming.  The Scheme library provides the glue that holds together
28 the low-level routines and separate modules which are written in C++.
29
30 When lilypond is run to typeset sheet music, the following happens:
31
32 @itemize @bullet
33 @item GUILE initialization: Various scheme files are read.
34
35 @item Parsing: First standard @code{ly} initialization files are read,
36 then the user @file{ly} file is read.
37
38 @item Interpretation: The music in the file is processed `in playing
39 order', i.e., the order that you use to read sheet music, or the
40 order in which notes are played.  The result of this step is a
41 typesetting specification.
42
43 @item Typesetting: The typesetting specification is solved: positions
44 and formatting is calculated.
45
46 @item The visible results ("virtual ink") are written to the output file.
47 @end itemize
48
49 During these stages different types of data play the the main role:
50 During parsing, @strong{Music} objects are created.  During the
51 interpretation, @strong{contexts} are constructed, and with these
52 contexts a network of @strong{graphical objects} (`grobs') is
53 created.  These grobs contain unknown variables, and the network forms a
54 set of equations.  After solving the equations and filling in these
55 variables, the printed output is written to an output file.
56
57 These threemanship of tasks (parsing, translating, typesetting) and
58 data-structures (music, context, graphical objects) permeates the entire
59 design of the program.
60
61
62 @table @b
63
64 @item Parsing
65
66 The @code{ly} file is read and converted to a list of @code{Scores}, which
67 each contain @code{Music} and paper/midi-definitions.  Here @code{Music},
68 @code{Pitch}, and @code{Duration} objects are created.
69
70 @item Interpreting music
71 @cindex interpreting music
72
73 All music events are `read' in the same order as they would be played
74 (or read from paper).  At every step of the interpretation, musical
75 events are delivered to interpretation contexts,
76 @cindex engraver
77 which use them to build @code{Grob}s (or MIDI objects for MIDI output).
78
79 In this stage @code{Music_iterators} do a traversal of the @code{Music}
80 structure.  The music events thus encountered are reported to
81 @code{Translator}s, a set of objects that collectively form interpretation
82 contexts.
83
84 @item Prebreaking
85 @cindex prebreaking
86
87 At places where line breaks may occur, clefs and bars are prepared for
88 a possible line break. 
89
90 @item Preprocessing
91 @cindex preprocessing
92
93 In this stage, all information that is needed to determine line breaking
94 is computed. 
95
96 @item Break calculation
97
98 The lines and horizontal positions of the columns are determined.
99
100 @item Breaking
101
102 Relations between all grobs are modified to reflect line breaks: When a
103 spanner, e.g. a slur, crosses a line break, then the spanner is `broken
104 into pieces'; for every line that the spanner is in, a copy of the grob
105 is made.  A substitution process redirects all grob references so that
106 each spanner grob will only reference other grobs in the same line.
107
108 @item Outputting
109
110 All vertical dimensions and spanning objects are computed, and all grobs
111 are output, line by line.  The output is encoded in the form of
112 @code{Molecule}s
113
114 @end table
115
116 The data types that are mentioned here are all discussed in this
117 section.
118
119
120 @c FIXME: Note entry vs Music entry at top level menu is confusing.
121 @c . {Music entry}
122 @menu
123 * Interpretation context::      
124 * Syntactic details::           
125 * Lexical details::             
126 * Output details::              
127 @end menu
128
129
130 @node Interpretation context
131 @section Interpretation context
132
133 @menu
134 * Creating contexts::           
135 * Default contexts::            
136 * Context properties::          
137 * Engravers and performers::    
138 * Changing context definitions::  
139 * Defining new contexts::       
140 @end menu
141
142
143 Interpretation contexts are objects that only exist during a run of
144 LilyPond.  During the interpretation phase of LilyPond (when it prints
145 @code{interpreting music} to standard output), the music expression in
146 a @code{\score} block is interpreted in time order.  This is the same
147 order that humans hear and play the music.
148
149 During this interpretation, the interpretation context holds the
150 state for the current point within the music.  It contains information
151 like
152
153 @itemize @bullet
154 @item What notes are playing at this point?
155
156 @item What symbols will be printed at this point?
157
158 @item What is the current key signature, time signature, point within
159 the measure, etc.?
160 @end itemize
161
162 Contexts are grouped hierarchically: A @internalsref{Voice} context is
163 contained in a @internalsref{Staff} context (because a staff can contain
164 multiple voices at any point), a @internalsref{Staff} context is contained in
165 @internalsref{Score}, @internalsref{StaffGroup}, or
166 @internalsref{ChoirStaff} context.
167
168 Contexts associated with sheet music output are called @emph{notation
169 contexts}, those for sound output are called @emph{performance
170 contexts}.  The default definitions of the standard notation and
171 performance contexts can be found in @file{ly/engraver-init.ly} and
172 @file{ly/performer-init.ly}, respectively.
173
174
175 @node Creating contexts
176 @subsection Creating contexts
177 @cindex @code{\context}
178 @cindex context selection
179
180 Contexts for a music expression can be selected manually, using the
181 following music expression.
182
183 @example
184 \context @var{contexttype} [= @var{contextname}] @var{musicexpr}
185 @end example
186
187 @noindent
188 This instructs lilypond to interpret @var{musicexpr} within the context
189 of type @var{contexttype} and with name @var{contextname}.  If this
190 context does not exist, it will be created.  
191
192 @lilypond[verbatim,singleline]
193 \score {
194   \notes \relative c'' {
195     c4 <d4 \context Staff = "another" e4> f
196   }
197 }
198 @end lilypond
199
200 @noindent
201 In this example, the @code{c} and @code{d} are printed on the
202 default staff.  For the @code{e}, a context Staff called
203 @code{another} is specified; since that does not exist, a new
204 context is created.  Within @code{another}, a (default) Voice context
205 is created for the @code{e4}.  When all music referring to a
206 context is finished, the context is ended as well.  So after the
207 third quarter, @code{another} is removed.
208
209
210 @node Default contexts
211 @subsection Default contexts
212
213 Most music expressions don't need an explicit @code{\context}
214 declaration: they inherit the notation context from their parent.  Each
215 note is a music expression, and as you can see in the following example,
216 only the sequential music enclosing the three notes has an explicit context. 
217
218 @lilypond[verbatim,singleline]
219 \score { \notes \context Voice = goUp { c'4 d' e' } } 
220 @end lilypond
221
222 There are some quirks that you must keep in mind when dealing with
223 defaults:
224
225 First, every top level music is interpreted by the Score context; in other
226 words, you may think of @code{\score} working like
227
228 @example
229 \score @{
230   \context Score @var{music}
231 @}
232 @end example
233
234 Second, contexts are created automatically to be able to interpret the
235 music expressions.  Consider the following example.
236
237 @lilypond[verbatim, singleline]
238 \score { \context Score \notes { c'4 ( d' )e' } }
239 @end lilypond
240
241 @noindent
242 The sequential music is interpreted by the Score context initially
243 (notice that the @code{\context} specification is redundant), but when a
244 note is encountered, contexts are setup to accept that note.  In this
245 case, a Thread, Voice, and Staff context are created.  The rest of the
246 sequential music is also interpreted with the same Thread, Voice, and
247 Staff context, putting the notes on the same staff, in the same voice.
248
249 This is a convenient mechanism, but do not expect opening chords to work
250 without @code{\context}.  For every note, a separate staff is
251 instantiated.
252
253 @cindex explicit context
254 @cindex starting with chords
255 @cindex chords, starting with
256
257 @lilypond[verbatim, singleline]
258 \score { \notes <c'4 es'> } 
259 @end lilypond
260
261 Of course, if the chord is preceded by a normal note in sequential
262 music, the chord will be interpreted by the Thread of the preceding
263 note:
264
265 @lilypond[verbatim,singleline]
266 \score { \notes { c'4 <c'4 es'> } }
267 @end lilypond
268
269
270 @node Context properties
271 @subsection Context properties
272
273 Notation contexts have properties.  These properties are from
274 the @file{.ly} file using the following expression:
275 @cindex @code{\property}
276
277 @example
278 \property @var{contextname}.@var{propname} = @var{value}
279 @end example
280
281 @noindent
282 Sets the @var{propname} property of the context @var{contextname} to the
283 specified Scheme expression @var{value}.  All @var{propname} and
284 @var{contextname} are strings, which are typically unquoted.
285
286 Properties that are set in one context are inherited by all of the
287 contained contexts.  This means that a property valid for the
288 @internalsref{Voice} context can be set in the @internalsref{Score} context
289 (for example) and thus take effect in all @internalsref{Voice} contexts.
290
291 @cindex @code{Current}
292 If you don't wish to specify the name of the context in the
293 @code{\property}-expression itself, you can refer to the abstract context
294 name, @code{Current}.  The @code{Current} context is the latest
295 used context.  This will typically mean the @internalsref{Thread}
296 context, but you can force another context with the
297 @code{\property}-command.  Hence the expressions
298
299 @example
300 \property @var{contextname}.@var{propname} = @var{value}
301 @end example
302
303 @noindent
304 and
305
306 @example
307 \context @var{contextname}
308 \property Current.@var{propname} = @var{value}
309 @end example
310
311 @noindent
312 do the same thing.
313 The main use for this is in macros -- allowing the specification of a
314 property-setting without restriction to a specific context.
315
316 Properties can be unset using the following expression:
317
318 @example
319 \property @var{contextname}.@var{propname} \unset
320 @end example
321
322 @cindex properties, unsetting
323 @cindex @code{\unset} 
324
325 @noindent
326 This removes the definition of @var{propname} in @var{contextname}.  If
327 @var{propname} was not defined in @var{contextname} (but was inherited
328 from a higher context), then this has no effect.
329
330 @refbugs
331
332 The syntax of @code{\unset} is asymmetric: @code{\property \unset} is not
333 the inverse of @code{\property \set}.
334
335
336 @node Engravers and performers
337 @subsection Engravers and performers
338
339 [TODO]
340
341 Basic building blocks of translation are called engravers; they are
342 special C++ classes.
343
344
345 @node Changing context definitions
346 @subsection Changing context definitions
347 @cindex context definition
348 @cindex translator definition
349
350 The most common way to define a context is by extending an existing
351 context.  You can change an existing context from the paper block by
352 first initializing a translator with an existing context identifier:
353
354 @example
355 \paper @{
356   \translator @{
357     @var{context-identifier}
358   @}
359 @}
360 @end example
361
362 @noindent
363 Then you can add and remove engravers using the following syntax:
364
365 @example
366 \remove @var{engravername}
367 \consists @var{engravername}
368 @end example
369
370 @noindent
371 Here @var{engravername} is a string, the name of an engraver in the
372 system.
373
374 @lilypond[verbatim,singleline]
375 \score {
376   \notes {
377     c'4 c'4
378   }
379   \paper {
380     \translator {
381       \StaffContext
382       \remove Clef_engraver
383     }
384   }
385 }
386 @end lilypond
387
388 @cindex engraver
389
390 You can also set properties in a translator definition.  The syntax is as
391 follows:
392
393 @example
394 @var{propname} = @var{value}
395 @var{propname} \set @var{grob-propname} = @var{pvalue}
396 @var{propname} \override @var{grob-propname} = @var{pvalue}
397 @var{propname} \revert @var{grob-propname} 
398 @end example
399
400 @noindent
401 @var{propname} is a string, @var{grob-propname} a symbol, @var{value}
402 and @code{pvalue} are Scheme expressions.  These types of property
403 assignments happen before interpretation starts, so a @code{\property}
404 command will override any predefined settings.
405
406 To simplify editing translators, all standard contexts have standard
407 identifiers called @var{name}@code{Context}, e.g. @code{StaffContext},
408 @code{VoiceContext}; see @file{ly/engraver-init.ly}.
409
410
411 @node Defining new contexts
412 @subsection Defining new contexts
413
414 If you want to build a context from scratch, you must also supply the
415 following extra information:
416
417 @itemize @bullet
418 @item A name, specified by @code{\name @var{contextname}}.
419
420 @item A cooperation module.  This is specified by @code{\type
421 @var{typename}}.
422 @end itemize
423
424 This is an example:
425
426 @example
427 \translator @code{
428   \type "Engraver_group_engraver"
429   \name "SimpleStaff"
430   \alias "Staff"
431   \consists "Staff_symbol_engraver"
432   \consists "Note_head_engraver"
433   \consistsend "Axis_group_engraver"
434 }@
435 @end example
436
437 @noindent
438 The argument of @code{\type} is the name for a special engraver that
439 handles cooperation between simple engravers such as
440 @code{Note_head_engraver} and @code{Staff_symbol_engraver}.  Alternatives
441 for this engraver are the following:
442
443 @table @code
444 @cindex @code{Engraver_group_engraver}
445
446 @item @code{Engraver_group_engraver}  
447 The standard cooperation engraver.
448
449 @cindex @code{Score_engraver}
450 @item @code{Score_engraver}  
451 This is a cooperation module that should be in the top level context.
452 @end table 
453
454 Other modifiers are
455
456 @itemize @bullet
457 @item @code{\alias} @var{alternate-name}:
458 This specifies a different name.  In the above example,
459 @code{\property Staff.X = Y} will also work on @code{SimpleStaff}s
460
461 @item @code{\consistsend} @var{engravername}:
462 Analogous to @code{\consists}, but makes sure that
463 @var{engravername} is always added to the end of the list of
464 engravers.
465
466 Some engraver types need to be at the end of the list; this
467 insures they stay there even if a user adds or removes engravers.
468 End-users generally don't need this command.
469     
470 @item @code{\accepts} @var{contextname}:
471 Add @var{contextname} to the list of contexts this context can
472 contain in the context hierarchy.  The first listed context is the
473 context to create by default.
474
475 @item @code{\denies}:
476 The opposite of @code{\accepts}.  Added for
477 completeness, but is never used in practice.
478
479 @item @code{\name} @var{contextname}:
480 This sets the type name of the context, e.g. @internalsref{Staff},
481 @internalsref{Voice}.  If the name is not specified, the translator won't do
482 anything. 
483 @end itemize
484
485 In the @code{\paper} block, it is also possible to define translator
486 identifiers.  Like other block identifiers, the identifier can only
487 be used as the very first item of a translator.  In order to define
488 such an identifier outside of @code{\score}, you must do
489
490 @example 
491 \paper @{
492   foo = \translator @{ @dots{} @}
493 @}
494 \score @{
495   \notes @{
496     @dots{}
497   @}
498   \paper @{
499     \translator @{ \foo @dots{} @}
500   @}
501 @} 
502 @end example 
503
504 @cindex paper types, engravers, and pre-defined translators
505
506       
507 @node Syntactic details
508 @section Syntactic details
509 @cindex Syntactic details
510
511 This section describes details that were too boring to be put elsewhere.
512
513 @menu
514 * Identifiers::                 
515 * Music expressions::           
516 * Manipulating music expressions::  
517 * Assignments::                 
518 * Lexical modes::               
519 * Ambiguities::                 
520 @end menu
521
522 @c .  {Identifiers}
523 @node Identifiers
524 @subsection Identifiers
525 @cindex Identifiers
526
527 @ignore
528 What has this section got to do with identifiers?
529 It seems more appropriate in the introduction to Chapter 4,
530 "Internals".
531
532   /MB
533 @end ignore
534
535 All of the information in a LilyPond input file is internally
536 represented as a Scheme value.  In addition to normal Scheme data types
537 (such as pair, number, boolean, etc.), LilyPond has a number of
538 specialized data types,
539
540 @itemize @bullet
541 @item Input
542 @item c++-function
543 @item Music
544 @item Identifier
545 @item Translator_def
546 @item Duration
547 @item Pitch
548 @item Score
549 @item Music_output_def
550 @item Moment (rational number)
551 @end itemize
552
553 LilyPond also includes some transient object types.  Objects of these
554 types are built during a LilyPond run, and do not `exist' per se within
555 your input file.  These objects are created as a result of your input
556 file, so you can include commands in the input to manipulate them,
557 during a LilyPond run.
558
559 @itemize @bullet
560 @item Grob: short for `Graphical object'.
561
562 @item Molecule: Device-independent page output object,
563 including dimensions.  Produced by some Grob functions.
564
565 @item Translator: An object that produces audio objects or Grobs.  This is
566 not yet user-accessible.
567
568 @item Font_metric: An object representing a font.
569 @end itemize
570
571
572 @node Music expressions
573 @subsection Music expressions
574 @cindex music expressions
575
576 Music in LilyPond is entered as a music expression.  Notes, rests, lyric
577 syllables are music expressions, and you can combine music expressions
578 to form new ones, for example by enclosing a list of expressions in
579 @code{\sequential @{ @}} or @code{< >}.  In the following example, a
580 compound expression is formed out of the quarter note @code{c} and a
581 quarter note @code{d}:
582
583 @example 
584 \sequential @{ c4 d4 @} 
585 @end example 
586
587 @cindex Sequential music
588 @cindex @code{\sequential}
589 @cindex sequential music
590 @cindex @code{<}
591 @cindex @code{>}
592 @cindex Simultaneous music
593 @cindex @code{\simultaneous}
594
595 The two basic compound music expressions are simultaneous and
596 sequential music.
597
598 @example
599 \sequential @code{@{} @var{musicexprlist} @code{@}}
600 \simultaneous @code{@{} @var{musicexprlist} @code{@}}
601 @end example
602
603 For both, there is a shorthand:
604
605 @example
606 @code{@{} @var{musicexprlist} @code{@}}
607 @end example
608
609 @noindent
610 for sequential and
611
612 @example
613 @code{<} @var{musicexprlist} @code{>}
614 @end example
615
616 @noindent
617 for simultaneous music.
618 In principle, the way in which you nest sequential and simultaneous to
619 produce music is not relevant.  In the following example, three chords
620 are expressed in two different ways:
621
622 @lilypond[fragment,verbatim,center]
623 \notes \context Voice {
624   <a c'> <b d'> <c' e'>
625   < { a b c' } { c' d' e' } >
626 }
627 @end lilypond
628
629 Other compound music expressions include
630
631 @example
632 \repeat @var{expr}
633 \transpose @var{from} @var{to} @var{expr}
634 \apply @var{func} @var{expr}
635 \context @var{type} = @var{id} @var{expr}
636 \times @var{fraction} @var{expr}
637 @end example
638
639
640 @c . {Manipulating music expressions}
641 @node Manipulating music expressions
642 @subsection Manipulating music expressions
643
644 The @code{\apply} mechanism gives you access to the internal
645 representation of music.  You can write Scheme-functions that operate
646 directly on it.  The syntax is 
647
648 @example
649 \apply #@var{func} @var{music}
650 @end example
651
652 @noindent
653 This means that @var{func} is applied to @var{music}.  The function
654 @var{func} should return a music expression.
655
656 This example replaces the text string of a script.  It also shows a dump
657 of the music it processes, which is useful if you want to know more
658 about how music is stored.
659
660 @lilypond[verbatim,singleline]
661 #(define (testfunc x)
662   (if (equal? (ly:get-mus-property x 'text) "foo")
663       (ly:set-mus-property! x 'text "bar"))
664   ;; recurse
665   (ly:set-mus-property! x 'elements
666     (map testfunc (ly:get-mus-property x 'elements)))
667   (display x)
668   x)
669
670 \score {
671   \notes
672   \apply #testfunc { c'4_"foo" }
673
674 @end lilypond
675
676 For more information on what is possible, see the automatically
677 generated documentation.
678
679 Directly accessing internal representations is dangerous: The
680 implementation is subject to changes, so you should avoid this feature
681 if possible.
682
683 A final example is a function that reverses a piece of music in time:
684
685 @lilypond[verbatim,singleline]
686 #(define (reverse-music music)
687   (let* ((elements (ly:get-mus-property music 'elements))
688          (reversed (reverse elements))
689          (span-dir (ly:get-mus-property music 'span-direction)))
690     (ly:set-mus-property! music 'elements reversed)
691     (if (ly:dir? span-dir)
692         (ly:set-mus-property! music 'span-direction (- span-dir)))
693     (map reverse-music reversed)
694     music))
695
696 music = \notes { c'4 d'4( e'4 f'4 }
697
698 \score {
699   \context Voice {
700     \music
701     \apply #reverse-music \music
702   }
703 }
704 @end lilypond
705
706 More examples are given in the distributed example files in
707 @code{input/test/}.
708
709 @c .   {Assignments}
710 @node Assignments
711 @subsection Assignments
712 @cindex Assignments
713
714 Identifiers allow objects to be assigned to names during the parse
715 stage.  To assign an identifier, use @var{name}@code{=}@var{value}.
716 To refer to an identifier, precede its name with a backslash:
717 `@code{\}@var{name}'.  @var{value} is any valid Scheme value or any of
718 the input-types listed above.  Identifier assignments can appear at top
719 level in the LilyPond file, but also in @code{\paper} blocks.
720
721 An identifier can be created with any string for its name, but you will
722 only be able to refer to identifiers whose names begin with a letter,
723 being entirely alphabetical.  It is impossible to refer to an identifier
724 whose name is the same as the name of a keyword.
725
726 The right hand side of an identifier assignment is parsed completely
727 before the assignment is done, so it is allowed to redefine an
728 identifier in terms of its old value, e.g.
729
730 @example
731 foo = \foo * 2.0
732 @end example
733
734 When an identifier is referenced, the information it points to is
735 copied.  For this reason, an identifier reference must always be the
736 first item in a block.
737
738 @example
739 \paper @{
740   foo = 1.0
741   \paperIdent % wrong and invalid
742 @}
743 @end example
744
745 @example
746 \paper @{
747   \paperIdent % correct
748   foo = 1.0
749 @}
750 @end example
751
752
753 @c .  {Lexical modes}
754 @node Lexical modes
755 @subsection Lexical modes
756 @cindex Lexical modes
757 @cindex input mode
758 @cindex mode, input 
759 @cindex @code{\notes}
760 @cindex @code{\chords}
761 @cindex @code{\lyrics}
762
763 To simplify entering notes, lyrics, and chords, LilyPond has three
764 special input modes in addition to the default mode: note, lyrics, and
765 chords mode.  These input modes change the way that normal, unquoted
766 words are interpreted: For example, the word @code{cis} may be
767 interpreted as a C-sharp, as a lyric syllable `cis' or as a C-sharp
768 major triad respectively.
769
770 A mode switch is entered as a compound music expression
771
772 @example
773 @code{\notes} @var{musicexpr}
774 @code{\chords} @var{musicexpr}
775 @code{\lyrics} @var{musicexpr}
776 @end example
777
778 @noindent
779 In each of these cases, these expressions do not add anything to the
780 meaning of their arguments.  They just instruct the parser in what mode
781 to parse their arguments.
782
783 Different input modes may be nested.
784
785
786 @c .  {Ambiguities}
787 @node Ambiguities
788 @subsection Ambiguities
789 @cindex ambiguities
790 @cindex grammar
791
792 The grammar contains a number of ambiguities.  We hope to resolve them at
793 some time.
794
795 @itemize @bullet
796 @item The assignment
797
798 @example 
799 foo = bar 
800 @end example 
801
802 @noindent
803 is interpreted as the string identifier assignment.  However,
804 it can also be interpreted as making a string identifier @code{\foo}
805 containing @code{"bar"}, or a music identifier @code{\foo} containing
806 the syllable `bar'.  The former interpretation is chosen.
807
808 @item If you do a nested repeat like
809
810 @example 
811 \repeat @dots{}
812 \repeat @dots{}
813 \alternative 
814 @end example 
815
816 @noindent
817 then it is ambiguous to which @code{\repeat} the
818 @code{\alternative} belongs.  This is the classic if-then-else
819 dilemma.  It may be solved by using braces.
820 @end itemize
821
822
823 @c .  {Lexical details}
824 @node Lexical details
825 @section Lexical details
826
827 Even more boring details, now on the lexical side of the input parser.
828
829 @menu
830 * Direct Scheme::               
831 * Reals::                       
832 * Strings::                     
833 @end menu
834
835
836 @node Direct Scheme
837 @subsection Direct Scheme
838 @cindex Scheme
839 @cindex GUILE
840 @cindex Scheme, in-line code
841 @cindex accessing Scheme
842 @cindex evaluating Scheme
843 @cindex LISP
844
845 LilyPond internally uses GUILE, a Scheme-interpreter.  Scheme is a
846 language from the LISP family.  You can learn more about Scheme at
847 @uref{http://www.scheme.org}.  It is used to represent data throughout
848 the whole program.  The hash-sign (@code{#}) accesses GUILE directly: The
849 code following the hash-sign is evaluated as Scheme.  The boolean value
850 @var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
851 @code{##t}.
852
853 LilyPond contains a Scheme interpreter (the GUILE library) for
854 internal use.  In some places, Scheme expressions also form valid syntax:
855 Wherever it is allowed,
856
857 @example
858 #@var{scheme}
859 @end example
860
861 @noindent
862 evaluates the specified Scheme code.  Example:
863
864 @example
865 \property Staff.TestObject \override #'foobar = #(+ 1 2)
866 @end example
867
868 @code{\override} expects two Scheme expressions.
869 The first one is a symbol (@code{foobar}), the second one
870 an integer (namely, 3).
871
872 In-line Scheme may be used at the top level.  In this case the result is
873 discarded.
874
875 Scheme is a full-blown programming language, and a full discussion is
876 outside the scope of this document.  Interested readers are referred to
877 the website @uref{http://www.schemers.org/} for more information on
878 Scheme.
879
880
881 @node Reals
882 @subsection Reals
883 @cindex real numbers
884
885 Formed from an optional minus sign and a sequence of digits followed
886 by a @emph{required} decimal point and an optional exponent such as
887 @code{-1.2e3}.  Reals can be built up using the usual operations:
888 `@code{+}', `@code{-}', `@code{*}', and
889 `@code{/}', with parentheses for grouping.
890
891 @cindex @code{\mm}
892 @cindex @code{\in}
893 @cindex @code{\cm}
894 @cindex @code{\pt}
895 @cindex dimensions
896
897 A real constant can be followed by one of the dimension keywords:
898 @code{\mm} @code{\pt}, @code{\in}, or @code{\cm}, for millimeters,
899 points, inches and centimeters, respectively.  This converts the number
900 that is the internal representation of that dimension.
901
902
903 @node Strings
904 @subsection Strings
905 @cindex string
906 @cindex concatenate
907
908 Begins and ends with the @code{"} character.  To include a @code{"}
909 character in a string write @code{\"}.  Various other backslash
910 sequences have special interpretations as in the C language.  A string
911 that contains no spaces can be written without the quotes.  Strings can
912 be concatenated with the @code{+} operator.
913
914
915 @c .  {Output details}
916 @node Output details
917 @section Output details
918
919 LilyPond's default output format is @TeX{}.  Using the option @option{-f}
920 (or @option{--format}) other output formats can be selected also, but
921 currently none of them reliably work.
922
923 At the beginning of the output file, various global parameters are defined.
924 It also contains a large @code{\special} call to define PostScript routines
925 to draw items not representable with @TeX{}, mainly slurs and ties.  A DVI
926 driver must be able to understand such embedded PostScript, or the output
927 will be rendered incompletely.
928
929 Then the file @file{lilyponddefs.tex} is loaded to define the macros used
930 in the code which follows.  @file{lilyponddefs.tex} includes various other
931 files, partially depending on the global parameters.
932
933 Now the music is output system by system (a `system' consists of all
934 staves belonging together).  From @TeX{}'s point of view, a system is an
935 @code{\hbox} which contains a lowered @code{\vbox} so that it is centered
936 vertically on the baseline of the text.  Between systems,
937 @code{\interscoreline} is inserted vertically to have stretchable space.
938 The horizontal dimension of the @code{\hbox} is given by the
939 @code{linewidth} parameter from LilyPond's @code{\paper} block (using the
940 natural line width if its value is@w{ }@minus{}1).
941
942 After the last system LilyPond emits a stronger variant of
943 @code{\interscoreline} only if the macro @code{\lilypondpaperlastpagefill}
944 is not defined (flushing the systems to the top of the page).  You can
945 avoid that manually by saying
946
947 @example
948 \def\lilypondpaperlastpagefill@{1@}
949 @end example
950
951 @noindent
952 or by setting the variable @code{lastpagefill} in LilyPond's @code{\paper}
953 block.
954
955 It is possible to fine-tune the vertical offset further by defining the
956 macro @code{\lilypondscoreshift}.  Example:
957
958 @example
959 \def\lilypondscoreshift@{0.25\baselineskip@}
960 @end example
961
962 @noindent
963 @code{\baselineskip} is the distance from one text line to the next.
964
965 The code produced by LilyPond can be used by both @TeX{} and La@TeX{}.
966
967 Here an example how to embed a small LilyPond file @code{foo.ly} into
968 running La@TeX{} text without using the @code{lilypond-book} script
969 (@pxref{Integrating text and music with lilypond-book}).
970
971 @example
972 \documentclass@{article@}
973
974 \def\lilypondpaperlastpagefill@{@}
975 \lineskip 5pt
976 \def\lilypondscoreshift@{0.25\baselineskip@}
977
978 \begin@{document@}
979 This is running text which includes an example music file
980 \input@{foo.tex@}
981 right here.
982 \end@{document@}
983 @end example
984
985 The file @file{foo.tex} has been simply produced with
986
987 @example
988 lilypond foo.ly
989 @end example
990
991 It is important to set the @code{indent} parameter to zero in the
992 @code{\paper} block of @file{foo.ly}.
993
994 The call to @code{\lineskip} assures that there is enough vertical space
995 between the LilyPond box and the surrounding text lines.
996
997 @c EOF