]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/input.itely
Merge branch 'master' of ssh+git://git.sv.gnu.org/srv/git/lilypond
[lilypond.git] / Documentation / user / input.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
3 @ignore
4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5
6     When revising a translation, copy the HEAD committish of the
7     version that you are working on.  See TRANSLATION for details.
8 @end ignore
9
10 @node Input syntax
11 @chapter Input syntax
12
13 This section deals with general lilypond input syntax issues,
14 rather than specific notation.
15
16 FIXME: don't complain about anything in this chapter.  It's still
17 under heavy development.
18
19 @menu
20 * Input files::                 
21 * Common syntax issues TODO name?::  
22 * Other stuffs TODO move?::     
23 @end menu
24
25
26 @node Input files
27 @section Input files
28
29 The main format of input for LilyPond are text files.  By convention,
30 these files end with @code{.ly}.
31
32 @menu
33 * File structure::              
34 * A single music expression::   
35 * Multiple scores in a book::   
36 * Extracting fragments of notation::  
37 * Including LilyPond files::    
38 * Text encoding::               
39 * Different editions from one source::  
40 @end menu
41
42
43 @node File structure
44 @subsection File structure
45
46 A @code{.ly} file contains any number of toplevel expressions, where a
47 toplevel expression is one of the following
48
49 @itemize
50 @item
51 An output definition, such as @code{\paper}, @code{\midi}, and
52 @code{\layout}.  Such a definition at the toplevel changes the default
53 settings for the block entered.
54
55 @item
56 A direct scheme expression, such as
57 @code{#(set-default-paper-size "a7" 'landscape)} or
58 @code{#(ly:set-option 'point-and-click #f)}.
59
60 @item
61 A @code{\header} block.  This sets the global header block.  This
62 is the block containing the definitions for book-wide settings, like
63 composer, title, etc.
64
65 @item
66 A @code{\score} block.  This score will be collected with other
67 toplevel scores, and combined as a single @code{\book}.
68
69 This behavior can be changed by setting the variable
70 @code{toplevel-score-handler} at toplevel.  The default handler is
71 defined in the init file @file{scm/@/lily@/.scm}.
72
73 The @code{\score} must begin with a music expression, and may
74 contain only one music expression.
75
76 @item
77 A @code{\book} block logically combines multiple movements
78 (i.e., multiple @code{\score} blocks) in one document.  If there are
79 a number of @code{\scores}, one output file will be created for
80 each @code{\book} block, in which all corresponding movements are
81 concatenated.  The only reason to explicitly specify @code{\book} blocks
82 in a @code{.ly} file is if you wish multiple output files from a single
83 input file.  One exception is within lilypond-book documents, where you
84 explicitly have to add a @code{\book} block if you want more than a
85 single @code{\score} or @code{\markup} in the same example.
86
87 This behavior can be changed by setting the variable
88 @code{toplevel-book-handler} at toplevel.  The default handler is
89 defined in the init file @file{scm/@/lily@/.scm}.
90
91 @item
92 A compound music expression, such as
93 @example
94 @{ c'4 d' e'2 @}
95 @end example
96
97 This will add the piece in a @code{\score} and format it in a
98 single book together with all other toplevel @code{\score}s and music
99 expressions.  In other words, a file containing only the above
100 music expression will be translated into
101
102 @example
103 \book @{
104   \score @{
105     \new Staff @{
106       \new Voice @{
107         @{ c'4 d' e'2 @}
108       @}
109     @}
110   @}
111         \layout @{ @}
112         \header @{ @}
113 @}
114 @end example
115
116 This behavior can be changed by setting the variable
117 @code{toplevel-music-handler} at toplevel.  The default handler is
118 defined in the init file @file{scm/@/lily@/.scm}.
119
120 @item
121 A markup text, a verse for example
122 @example
123 \markup @{
124    2.  The first line verse two.
125 @}
126 @end example
127
128 Markup texts are rendered above, between or below the scores or music
129 expressions, wherever they appear.
130
131 @cindex variables
132
133 @item
134 An variable, such as
135 @example
136 foo = @{ c4 d e d @}
137 @end example
138
139 This can be used later on in the file by entering @code{\foo}.  The
140 name of an variable should have alphabetic characters only; no
141 numbers, underscores or dashes.
142
143 @end itemize
144
145 The following example shows three things that may be entered at
146 toplevel
147
148 @example
149 \layout @{
150   % movements are non-justified by default
151   ragged-right = ##t
152 @}
153
154 \header @{
155    title = "Do-re-mi"
156 @}
157
158 @{ c'4 d' e2 @}
159 @end example
160
161
162 At any point in a file, any of the following lexical instructions can
163 be entered:
164
165 @itemize
166 @item @code{\version}
167 @item @code{\include}
168 @item @code{\sourcefilename}
169 @item @code{\sourcefileline}
170
171 @end itemize
172
173
174 @node A single music expression
175 @subsection A single music expression
176
177 A @code{\score} must contain a single music expression.  However,
178 this music expression may be of any size.  Recall that music
179 expressions may be included inside other expressions to form
180 larger expressions.  All of these examples are single music
181 expressions; note the curly braces @{ @} or angle brackets <<
182 >> at the beginning and ending of the music.
183
184 @example
185 @{ c'4 c' c' c' @}
186 @end example
187
188 @lilypond[ragged-right,verbatim,quote]
189 {
190   { c'4 c' c' c'}
191   { d'4 d' d' d'}
192 }
193 @end lilypond
194
195 @lilypond[ragged-right,verbatim,quote]
196 <<
197   \new Staff { c'4 c' c' c' }
198   \new Staff { d'4 d' d' d' }
199 >>
200 @end lilypond
201
202 @example
203 @{
204   \new GrandStaff <<
205     \new StaffGroup <<
206       \new Staff @{ \flute @}
207       \new Staff @{ \oboe @}
208     >>
209     \new StaffGroup <<
210       \new Staff @{ \violinI @}
211       \new Staff @{ \violinII @}
212     >>
213   >>
214 @}
215 @end example
216
217
218 @node Multiple scores in a book
219 @subsection Multiple scores in a book
220
221 @funindex \book
222 @cindex movements, multiple
223
224 A document may contain multiple pieces of music and texts.  Examples
225 of these are an etude book, or an orchestral part with multiple
226 movements.  Each movement is entered with a @code{\score} block,
227
228 @example
229 \score @{
230   @var{..music..}
231 @}
232 @end example
233
234 and texts are entered with a @code{\markup} block,
235
236 @example
237 \markup @{
238   @var{..text..}
239 @}
240 @end example
241
242 @funindex \book
243
244 All the movements and texts which appear in the same @code{.ly} file 
245 will normally be typeset in the form of a single output file. 
246
247 @example
248 \score @{
249   @var{..}
250 @}
251 \markup @{
252   @var{..}
253 @}
254 \score @{
255   @var{..}
256 @}
257 @end example
258
259 However, if you want multiple output files from the same @code{.ly}
260 file, then you can add multiple @code{\book} blocks, where each such
261 @code{\book} block will result in a separate output.  If you do not
262 specify any @code{\book} block in the file, LilyPond will implicitly
263 treat the full file as a single @code{\book} block, see @ref{File
264 structure}.  One important exception is within lilypond-book documents,
265 where you explicitly have to add a @code{\book} block, otherwise only
266 the first @code{\score} or @code{\markup} will appear in the output.
267
268 The header for each piece of music can be put inside the @code{\score}
269 block.  The @code{piece} name from the header will be printed before
270 each movement.  The title for the entire book can be put inside the
271 @code{\book}, but if it is not present, the @code{\header} which is at
272 the top of the file is inserted.
273
274 @example
275 \header @{
276   title = "Eight miniatures"
277   composer = "Igor Stravinsky"
278 @}
279 \score @{
280   @dots{}
281   \header @{ piece = "Romanze" @}
282 @}
283 \markup @{
284    ..text of second verse..
285 @}
286 \markup @{
287    ..text of third verse..
288 @}
289 \score @{
290   @dots{}
291   \header @{ piece = "Menuetto" @}
292 @}
293 @end example
294
295 @node Extracting fragments of notation
296 @subsection Extracting fragments of notation
297
298 It is possible to quote small fragments of a large score directly from
299 the output.  This can be compared to clipping a piece of a paper score
300 with scissors.
301
302 This is done by definining the measures that need to be cut out
303 separately.  For example, including the following definition
304
305
306 @verbatim
307 \layout {
308   clip-regions
309   = #(list
310       (cons
311        (make-rhythmic-location 5 1 2)
312        (make-rhythmic-location 7 3 4)))
313 }       
314 @end verbatim
315
316 @noindent
317 will extract a fragment starting halfway the fifth measure, ending in
318 the seventh measure.  The meaning of @code{5 1 2} is: after a 1/2 note
319 in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7.
320
321 More clip regions can be defined by adding more pairs of
322 rhythmic-locations to the list. 
323
324 In order to use this feature, LilyPond must be invoked with
325 @code{-dclip-systems}.  The clips are output as EPS files, and are
326 converted to PDF and PNG if these formats are switched on as well.
327
328 For more information on output formats, see @rprogram{Invoking lilypond}.
329
330 @seealso
331
332 Examples: @lsr{non-notation,clip-systems.ly}
333
334
335 @node Including LilyPond files
336 @subsection Including LilyPond files
337
338 @funindex \include
339 @cindex including files
340
341 A large project may be split up into separate files.  To refer to another
342 file, use
343
344 @example
345 \include "otherfile.ly"
346 @end example
347
348 The line @code{\include "file.ly"} is equivalent to pasting the contents
349 of file.ly into the current file at the place where you have the
350 \include.  For example, for a large project you might write separate files
351 for each instrument part and create a @q{full score} file which brings
352 together the individual instrument files.
353
354 The initialization of LilyPond is done in a number of files that are
355 included by default when you start the program, normally transparent to the
356 user.  Run lilypond --verbose to see a list of paths and files that Lily
357 finds.
358
359 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
360 VERSION is in the form @q{2.6.1}) are on the path and available to
361 @code{\include}.  Files in the
362 current working directory are available to \include, but a file of the same
363 name in LilyPond's installation takes precedence.  Files are
364 available to \include from directories in the search path specified as an
365 option when invoking @code{lilypond --include=DIR} which adds DIR to the
366 search path.
367
368 The @code{\include} statement can use full path information, but with the Unix
369 convention @code{/} rather than the DOS/Windows @code{\}.  For example,
370 if @file{stuff.ly} is located one directory higher than the current working
371 directory, use
372
373 @example
374 \include "../stuff.ly"
375 @end example
376
377
378 @node Text encoding
379 @subsection Text encoding
380
381 LilyPond uses the Pango library to format multi-lingual texts, and
382 does not perform any input-encoding conversions.  This means that any
383 text, be it title, lyric text, or musical instruction containing
384 non-ASCII characters, must be utf-8.  The easiest way to enter such text is
385 by using a Unicode-aware editor and saving the file with utf-8 encoding.  Most
386 popular modern editors have utf-8 support, for example, vim, Emacs,
387 jEdit, and GEdit do.
388
389 @c  Currently not working
390 @ignore
391 Depending on the fonts installed, the following fragment shows Hebrew
392 and Cyrillic lyrics,
393
394 @cindex Cyrillic
395 @cindex Hebrew
396 @cindex ASCII, non
397
398 @li lypondfile[fontload]{utf-8.ly}
399
400 The @TeX{} backend does not handle encoding specially at all.  Strings
401 in the input are put in the output as-is.  Extents of text items in the
402 @TeX{} backend, are determined by reading a file created via the
403 @file{texstr} backend,
404
405 @example
406 lilypond -dbackend=texstr input/les-nereides.ly
407 latex les-nereides.texstr
408 @end example
409
410 The last command produces @file{les-nereides.textmetrics}, which is
411 read when you execute
412
413 @example
414 lilypond -dbackend=tex input/les-nereides.ly
415 @end example
416
417 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
418 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
419 interpreting non-ASCII strings.
420
421 @end ignore
422
423 To use a Unicode escape sequence, use
424
425 @example
426 #(ly:export (ly:wide-char->utf-8 #x2014))
427 @end example
428
429
430 @seealso
431
432 @lsr{text,utf-8.ly}
433
434
435 @node Different editions from one source
436 @subsection Different editions from one source
437
438 @funindex \tag
439 @cindex tag
440
441 The @code{\tag} command marks music expressions with a name.  These
442 tagged expressions can be filtered out later.  With this mechanism it
443 is possible to make different versions of the same music source.
444
445 In the following example, we see two versions of a piece of music, one
446 for the full score, and one with cue notes for the instrumental part
447
448 @example
449 c1
450 <<
451   \tag #'part <<
452     R1 \\
453     @{
454       \set fontSize = #-1
455       c4_"cue" f2 g4 @}
456   >>
457   \tag #'score R1
458 >>
459 c1
460 @end example
461
462 The same can be applied to articulations, texts, etc.: they are
463 made by prepending
464 @example
465 -\tag #@var{your-tag}
466 @end example
467 to an articulation, for example,
468 @example
469 c1-\tag #'part ^4
470 @end example
471
472 This defines a note with a conditional fingering indication.
473
474 @cindex keepWithTag
475 @cindex removeWithTag
476 By applying the @code{\keepWithTag} and @code{\removeWithTag}
477 commands, tagged expressions can be filtered.  For example,
478 @example
479 <<
480   @var{the music}
481   \keepWithTag #'score @var{the music}
482   \keepWithTag #'part @var{the music}
483 >>
484 @end example
485 would yield
486
487 @lilypondfile[ragged-right,quote]{tag-filter.ly}
488
489 The arguments of the @code{\tag} command should be a symbol
490 (such as @code{#'score} or @code{#'part}), followed by a
491 music expression.  It is possible to put multiple tags on
492 a piece of music with multiple @code{\tag} entries,
493
494 @example
495   \tag #'original-part \tag #'transposed-part @dots{}
496 @end example
497
498
499 @seealso
500
501 Examples: @lsr{parts,tag@/-filter@/.ly}
502
503
504 @refbugs
505
506 Multiple rests are not merged if you create the score with both tagged
507 sections.
508
509
510 @node Common syntax issues TODO name?
511 @section Common syntax issues TODO name?
512
513 @menu
514 * Up and down::                 
515 * Distances and measurements MAYBE MOVE::  
516 @end menu
517
518 @node Up and down
519 @subsection Up and down
520
521 TODO: everything
522
523 By default, lilypnod does a pretty jazz'n job of picking
524 directions.  But in some cases, it may be desirable to force a
525 direction.
526
527 @verbatim
528 -
529 ^ _
530 @end verbatim
531
532 Also cover
533 #UP
534 #DOWN
535 #LEFT
536 #RIGHT.
537
538 Maybe rename section to "directions".
539
540
541 @node Distances and measurements MAYBE MOVE
542 @subsection Distances and measurements MAYBE MOVE
543
544 DISCUSS after working on other sections.
545
546 TODO: staff spaces, #UP #DOWN #LEFT #RIGHT.  Maybe move into tweaks?
547
548
549
550
551
552 @node Other stuffs TODO move?
553 @section Other stuffs TODO move?
554
555
556 @menu
557 * Displaying LilyPond notation::  
558 * Skipping corrected music::    
559 * context list FIXME::          
560 * another thing FIXME::         
561 * Input modes FIXME::           
562 @end menu
563
564 @node Displaying LilyPond notation
565 @subsection Displaying LilyPond notation
566
567 @funindex \displayLilyMusic
568 Displaying a music expression in LilyPond notation can be
569 done using the music function @code{\displayLilyMusic}.  For example,
570
571 @example
572 @{
573   \displayLilyMusic \transpose c a, @{ c e g a bes @}
574 @}
575 @end example
576
577 will display
578
579 @example
580 @{ a, cis e fis g @}
581 @end example
582
583 By default, LilyPond will print these messages to the console along
584 with all the other messages.  To split up these messages and save
585 the results of @code{\display@{STUFF@}}, redirect the output to
586 a file.
587
588 @example
589 lilypond file.ly >display.txt
590 @end example
591
592
593 @node Skipping corrected music
594 @subsection Skipping corrected music
595
596
597 @funindex skipTypesetting
598 @funindex showLastLength
599
600 When entering or copying music, usually only the music near the end (where
601 you
602 are adding notes) is interesting to view and correct.  To speed up
603 this correction process, it is possible to skip typesetting of all but
604 the last few measures.  This is achieved by putting
605
606 @verbatim
607 showLastLength = R1*5
608 \score { ... }
609 @end verbatim
610
611 @noindent
612 in your source file.  This will render only the last 5 measures
613 (assuming 4/4 time signature) of every @code{\score} in the input
614 file.  For longer pieces, rendering only a small part is often an order
615 of magnitude quicker than rendering it completely
616
617 Skipping parts of a score can be controlled in a more fine-grained
618 fashion with the property @code{Score.skipTypesetting}.  When it is
619 set, no typesetting is performed at all.
620
621 This property is also used to control output to the MIDI file.  Note that
622 it skips all events, including tempo and instrument changes.  You have
623 been warned.
624
625 @lilypond[quote,fragment,ragged-right,verbatim]
626 \relative c'' {
627   c8 d
628   \set Score.skipTypesetting = ##t
629   e e e e e e e e
630   \set Score.skipTypesetting = ##f
631   c d b bes a g c2 }
632 @end lilypond
633
634 In polyphonic music, @code{Score.skipTypesetting} will affect all
635 voices and staves, saving even more time.
636
637
638 @node context list FIXME
639 @subsection context list FIXME
640
641 >> > > - list of contexts: my *danger unmaintainable* 
642 >> > > alarm just went off.  I'm 
643
644 I knew it would... And leaving out some of them is perfectly fine
645 with me.
646 I do think that a list like this, with the main contexts and a
647 brief
648 description of  what they do (perhaps also with a note about what
649 default
650 behaviour is associated with each of them, but this may be
651 unmanageable),
652 should be there, and then we could simply list the remaining ones
653 without
654 further explanation and with links to the IR.
655
656
657 The Master Of All Contexts
658 ==========================
659
660     * Score
661         This is the top level notation context. No other context
662 can
663         contain a Score context. This context handles the
664         administration of time signatures. It also makes sure that
665         items such as clefs, time signatures, and key-signatures
666 are
667         aligned across staves.
668         You cannot explicitly instantiate a Score context (since
669 it is
670         not contained in any other context). It is instantiated
671         automatically when an output definition (a \score or
672 \layout
673         block) is processed. 
674         (it should also be made clear somewhere what the
675 difference is between
676         \score and \Score).
677
678 Top-level contexts: Staff containers
679 ====================================
680     * StaffGroup
681         Groups staves while adding a bracket on the left side,
682         grouping the staves together. The bar lines of the
683 contained
684         staves are connected vertically. StaffGroup only consists
685 of a
686         collection of staves, with a bracket in front and spanning
687 bar
688         lines.
689     * ChoirStaff
690         Identical to StaffGroup except that the contained staves
691 are
692         not connected vertically.
693     * GrandStaff
694         A group of staves, with a brace on the left side, grouping
695 the
696         staves together. The bar lines of the contained staves are
697         connected vertically.
698     * PianoStaff
699         Just like GrandStaff but with a forced distance between
700 the
701         staves, so cross staff beaming and slurring can be used.
702     * DrumStaff
703         Handles typesetting for percussion. Can contain DrumVoice
704     * InnerStaffGroup
705     * InnerChoirStaff
706
707 Staff-level contexts
708 ====================
709     * Staff
710         Handles clefs, bar lines, keys, accidentals. It can
711 contain
712         Voice contexts.
713     * RhythmicStaff
714         Like Staff but for printing rhythms. Pitches are
715         ignored; the notes are printed on one line.
716     * TabStaff
717         Context for generating tablature. By default lays the
718 music
719         expression out as a guitar tablature, printed on six
720 lines.
721     * VaticanaStaff
722         Same as Staff, except that it is accommodated for
723         typesetting a piece in gregorian style. 
724     * MensuralStaff
725         Same as Staff, except that it is accommodated for
726         typesetting a piece in mensural style. 
727
728 Voice-level (bottom) contexts
729 =============================
730 What is generated by default here?  The voice-level contexts
731 initiate
732 certain properties and start engravers. 
733
734     * Voice 
735         Corresponds to a voice on a staff. This context handles
736 the
737         conversion of dynamic signs, stems, beams, super- and
738         subscripts, slurs, ties, and rests.
739         You have to instantiate this explicitly if you want to
740 have
741         multiple voices on the same staff. 
742         Bottom context.
743     * VaticanaVoice
744         Same as Voice, except that it is accommodated for
745         typesetting a piece in gregorian style.  
746     * MensuralVoice
747         Same as Voice, except that it is accommodated for
748         typesetting a piece in mensural style. 
749     * Lyrics
750         Corresponds to a voice with lyrics. Handles the printing
751 of a
752         single line of lyrics.
753         Bottom context.
754     * DrumVoice
755         A voice on a percussion staff.
756     * FiguredBass
757          
758     * ChordNames
759         Typesets chord names.  This context is a `bottom' context;
760 it
761         cannot contain other contexts.
762
763 ------------------------------
764 Then the following, which I don't know what to do with:
765
766     * TabVoice
767     * GregorianTranscriptionVoice
768     * GregorianTranscriptionStaff
769
770     * FretBoards
771         Engraves fretboards from chords. Not easy... Not
772 documented.
773     * NoteNames
774
775     * CueVoice Not documented
776     * Global
777         Hard coded entry point for LilyPond. Cannot be tuned.
778     * Devnull
779         Silently discards all musical information given to this
780 context.
781
782
783 @node another thing FIXME
784 @subsection another thing FIXME
785
786 Another thing that is needed, is an overview of the various naming
787 conventions: 
788
789     scheme functions: lowercase-with-hyphens (incl. one-word
790 names)
791     scheme functions: ly:plus-scheme-style
792     music events, music classes and music properties:
793 as-scheme-functions
794     Grob interfaces: scheme-style
795     backend properties: scheme-style (but X and Y!)
796     contexts (and MusicExpressions and grobs): Capitalized or
797 CamelCase
798     context properties: lowercaseFollowedByCamelCase
799     engravers:
800 Capitalized_followed_by_lowercase_and_with_underscores
801
802 Which of these are conventions and which are rules?
803 Which are rules of the underlying language, and which are
804 LP-specific?
805
806
807 @node Input modes FIXME
808 @subsection Input modes FIXME
809
810 \notemode
811
812 \notemode turns the front end of LilyPond into note mode
813 (which is the default parsing mode).
814 It's certainly useful in certain situations, for example if you
815 are in \lyricmode or \chordmode or ... and want to insert
816 something that only can be done with \notemode syntax.
817
818 See for example
819 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00418.html
820 http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00218.html
821 http://lists.gnu.org/archive/html/lilypond-user/2006-12/msg00236.html
822 http://lists.gnu.org/archive/html/lilypond-user/2006-11/msg00061.html
823
824
825 \chords
826 \drums
827 \fretmode ?
828
829
830
831