X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fnon-music.itely;h=db12f12116d2c1cd714410316926b2ba46290f66;hb=41e45dd730c075e78065dfa78e5e54be664d905e;hp=853df046ee49e106eac256735f0cfd8117813a19;hpb=2f987c0bacf1706f9bcc1b4f31f7e81732f28e03;p=lilypond.git diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely index 853df046ee..db12f12116 100644 --- a/Documentation/user/non-music.itely +++ b/Documentation/user/non-music.itely @@ -14,464 +14,16 @@ @node Non-musical notation @chapter Non-musical notation -This section deals with general lilypond issues, rather than +This section deals with general LilyPond issues, rather than specific notation. @menu -* Input files:: * Titles and headers:: * MIDI output:: -* Displaying LilyPond notation:: -* Skipping corrected music:: +* other midi:: @end menu -@node Input files -@section Input files - -The main format of input for LilyPond are text files. By convention, -these files end with @samp{.ly}. - -@menu -* File structure (introduction):: -* File structure:: -* A single music expression:: -* Multiple scores in a book:: -* Extracting fragments of notation:: -* Including LilyPond files:: -* Text encoding:: -@end menu - - -@node File structure (introduction) -@subsection File structure (introduction) - -A basic example of a lilypond input file is - -@example -\version "2.11.15" -\score @{ - @{ @} % this is a single music expression; - % all the music goes in here. - \header @{ @} - \layout @{ @} - \midi @{ @} -@} -@end example - -@noindent -There are many variations of this basic pattern, but this -example serves as a useful starting place. - -The major part of this manual is concerned with entering various -forms of music in LilyPond. However, many music expressions are not -valid input on their own, for example, a @code{.ly} file containing -only a note -@example -c'4 -@end example - -@noindent -will result in a parsing error. Instead, music should be inside other -expressions, which may be put in a file by themselves. Such -expressions are called toplevel expressions; see @ref{File structure}, for -a list of all such expressions. - - -@node File structure -@subsection File structure - -A @code{.ly} file contains any number of toplevel expressions, where a -toplevel expression is one of the following - -@itemize @bullet -@item -An output definition, such as @code{\paper}, @code{\midi}, and -@code{\layout}. Such a definition at the toplevel changes the default -settings for the block entered. - -@item -A direct scheme expression, such as -@code{#(set-default-paper-size "a7" 'landscape)} or -@code{#(ly:set-option 'point-and-click #f)}. - -@item -A @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 -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}. - -The @code{\score} must begin with a music expression, and may -contain only one music expression. - -@item -A @code{\book} block logically combines multiple movements -(i.e., multiple @code{\score} blocks) in one document. If there are -a number of @code{\scores}, one output file will be created for -each @code{\book} block, in which all corresponding movements are -concatenated. The only reason to explicitly specify @code{\book} blocks -in a @code{.ly} file is if you wish multiple output files from a single -input file. One exception is within lilypond-book documents, where you -explicitly have to add a @code{\book} block if you want more than a -single @code{\score} or @code{\markup} in the same example. - -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 format it in a -single book together with all other toplevel @code{\score}s and music -expressions. In other words, a file containing only the above -music expression will be translated into - -@example -\book @{ - \score @{ - \new Staff @{ - \new Voice @{ - @{ c'4 d' e'2 @} - @} - @} - @} - \layout @{ @} - \header @{ @} -@} -@end example - -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}. - -@item -A markup text, a verse for example -@example -\markup @{ - 2. The first line verse two. -@} -@end example - -Markup texts are rendered above, between or below the scores or music -expressions, wherever they appear. - -@cindex variables -@cindex identifiers - -@item -An identifier, such as -@example -foo = @{ c4 d e d @} -@end example - -This can be used later on in the file by entering @code{\foo}. The -name of an identifier should have alphabetic characters only; no -numbers, underscores or dashes. - -@end itemize - -The following example shows three things that may be entered at -toplevel - -@example -\layout @{ - % movements are non-justified by default - ragged-right = ##t -@} - -\header @{ - title = "Do-re-mi" -@} - -@{ c'4 d' e2 @} -@end example - - -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{\sourcefilename} -@item @code{\sourcefileline} - -@end itemize - - -@node A single music expression -@subsection A single music expression - -A @code{\score} must contain a single music expression. However, -this music expression may be of any size. Recall that music -expressions may be included inside other expressions to form -larger expressions. All of these examples are single music -expressions; note the curly braces @{ @} or angle brackets << ->> at the beginning and ending of the music. - -@example -@{ c'4 c' c' c' @} -@end example - -@lilypond[ragged-right,verbatim,quote] -{ - { c'4 c' c' c'} - { d'4 d' d' d'} -} -@end lilypond - -@lilypond[ragged-right,verbatim,quote] -<< - \new Staff { c'4 c' c' c' } - \new Staff { d'4 d' d' d' } ->> -@end lilypond - -@example -@{ - \new GrandStaff << - \new StaffGroup << - \new Staff @{ \flute @} - \new Staff @{ \oboe @} - >> - \new StaffGroup << - \new Staff @{ \violinI @} - \new Staff @{ \violinII @} - >> - >> -@} -@end example - - -@node Multiple scores in a book -@subsection Multiple scores in a book - -@funindex \book -@cindex movements, multiple - -A document may contain multiple pieces of music and texts. Examples -of these are an etude book, or an orchestral part with multiple -movements. Each movement is entered with a @code{\score} block, - -@example -\score @{ - @var{..music..} -@} -@end example - -and texts are entered with a @code{\markup} block, - -@example -\markup @{ - @var{..text..} -@} -@end example - -@funindex \book - -All the movements and texts which appear in the same @code{.ly} file -will normally be typeset in the form of a single output file. - -@example -\score @{ - @var{..} -@} -\markup @{ - @var{..} -@} -\score @{ - @var{..} -@} -@end example - -However, if you want multiple output files from the same @code{.ly} -file, then you can add multiple @code{\book} blocks, where each such -@code{\book} block will result in a separate output. If you do not -specify any @code{\book} block in the file, LilyPond will implicitly -treat the full file as a single @code{\book} block, see @ref{File -structure}. One important exception is within lilypond-book documents, -where you explicitly have to add a @code{\book} block, otherwise only -the first @code{\score} or @code{\markup} will appear in the output. - -The header for each piece of music can be put inside the @code{\score} -block. The @code{piece} name from the header will be printed before -each movement. The title for the entire book can be put inside the -@code{\book}, but if it is not present, the @code{\header} which is at -the top of the file is inserted. - -@example -\header @{ - title = "Eight miniatures" - composer = "Igor Stravinsky" -@} -\score @{ - @dots{} - \header @{ piece = "Romanze" @} -@} -\markup @{ - ..text of second verse.. -@} -\markup @{ - ..text of third verse.. -@} -\score @{ - @dots{} - \header @{ piece = "Menuetto" @} -@} -@end example - -@node Extracting fragments of notation -@subsection Extracting fragments of notation - -It is possible to quote small fragments of a large score directly from -the output. This can be compared to clipping a piece of a paper score -with scissors. - -This is done by definining the measures that need to be cut out -separately. For example, including the following definition - - -@verbatim -\layout { - clip-regions - = #(list - (cons - (make-rhythmic-location 5 1 2) - (make-rhythmic-location 7 3 4))) -} -@end verbatim - -@noindent -will extract a fragment starting halfway the fifth measure, ending in -the seventh measure. The meaning of @code{5 1 2} is: after a 1/2 note -in measure 5, and @code{7 3 4} after 3 quarter notes in measure 7. - -More clip regions can be defined by adding more pairs of -rhythmic-locations to the list. - -In order to use this feature, LilyPond must be invoked with -@code{-dclip-systems}. The clips are output as EPS files, and are -converted to PDF and PNG if these formats are switched on as well. - -For more information on output formats, see @rprogram{Invoking lilypond}. - -@seealso - -Examples: @lsr{non-notation,clip-systems.ly} - - -@node Including LilyPond files -@subsection Including LilyPond files - -@funindex \include -@cindex including files - -A large project may be split up into separate files. To refer to another -file, use - -@example -\include "otherfile.ly" -@end example - -The line @code{\include "file.ly"} is equivalent to pasting the contents -of file.ly into the current file at the place where you have the -\include. For example, for a large project you might write separate files -for each instrument part and create a @q{full score} file which brings -together the individual instrument files. - -The initialization of LilyPond is done in a number of files that are -included by default when you start the program, normally transparent to the -user. Run lilypond --verbose to see a list of paths and files that Lily -finds. - -Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where -VERSION is in the form @q{2.6.1}) are on the path and available to -@code{\include}. Files in the -current working directory are available to \include, but a file of the same -name in LilyPond's installation takes precedence. Files are -available to \include from directories in the search path specified as an -option when invoking @code{lilypond --include=DIR} which adds DIR to the -search path. - -The @code{\include} statement can use full path information, but with the Unix -convention @samp{/} rather than the DOS/Windows @samp{\}. For example, -if @file{stuff.ly} is located one directory higher than the current working -directory, use - -@example -\include "../stuff.ly" -@end example - - -@node Text encoding -@subsection Text encoding - -LilyPond uses the Pango library to format multi-lingual texts, and -does not perform any input-encoding conversions. This means that any -text, be it title, lyric text, or musical instruction containing -non-ASCII characters, must be utf-8. The easiest way to enter such text is -by using a Unicode-aware editor and saving the file with utf-8 encoding. Most -popular modern editors have utf-8 support, for example, vim, Emacs, -jEdit, and GEdit do. - -@c Currently not working -@ignore -Depending on the fonts installed, the following fragment shows Hebrew -and Cyrillic lyrics, - -@cindex Cyrillic -@cindex Hebrew -@cindex ASCII, non - -@li lypondfile[fontload]{utf-8.ly} - -The @TeX{} backend does not handle encoding specially at all. Strings -in the input are put in the output as-is. Extents of text items in the -@TeX{} backend, are determined by reading a file created via the -@file{texstr} backend, - -@example -lilypond -dbackend=texstr input/les-nereides.ly -latex les-nereides.texstr -@end example - -The last command produces @file{les-nereides.textmetrics}, which is -read when you execute - -@example -lilypond -dbackend=tex input/les-nereides.ly -@end example - -Both @file{les-nereides.texstr} and @file{les-nereides.tex} need -suitable LaTeX wrappers to load appropriate La@TeX{} packages for -interpreting non-ASCII strings. - -@end ignore - -To use a Unicode escape sequence, use - -@example -#(ly:export (ly:wide-char->utf-8 #x2014)) -@end example - - -@seealso - -@lsr{text,utf-8.ly} - - - @node Titles and headers @section Titles and headers @@ -740,7 +292,7 @@ composer flush right on a single line. A particular place of a score can be marked using the @code{\label} command, either at top-level or inside music. This label can then be -refered to in a markup, to get the number of the page where the marked +referred to in a markup, to get the number of the page where the marked point is placed, using the @code{\page-ref} markup command. @lilypond[verbatim,line-width=11.0\cm] @@ -770,14 +322,14 @@ is not known; @end enumerate The reason why a gauge is needed is that, at the time markups are -interpreted, the page breaking has not yet occured, so the page numbers +interpreted, the page breaking has not yet occurred, so the page numbers are not yet known. To work around this issue, the actual markup interpretation is delayed to a later time; however, the dimensions of the markup have to be known before, so a gauge is used to decide these dimensions. If the book has between 10 and 99 pages, it may be "00", ie. a two digit number. -@refcommands +@predefined @funindex \label @code{\label} @@ -813,10 +365,10 @@ top-level, or inside a music expression. @end verbatim The markups which are used to format the table of contents are defined -in the @code{\paper} block. The default ones are @code{tocTitleMarkup}, +in the @code{\paper} block. The default ones are @code{tocTitleMarkup}, for formatting the title of the table, and @code{tocItemMarkup}, for formatting the toc elements, composed of the element title and page -number. These variables may be changed by the user: +number. These variables may be changed by the user: @verbatim \paper { @@ -825,19 +377,19 @@ number. These variables may be changed by the user: \fill-line { \null "Table des matières" \null } \hspace #1 } - %% use larfer font size + %% use larger font size tocItemMarkup = \markup \large \fill-line { \fromproperty #'toc:text \fromproperty #'toc:page } } @end verbatim -Note how the toc element text and page number are refered to in +Note how the toc element text and page number are referred to in the @code{tocItemMarkup} definition. New commands and markups may also be defined to build more elaborated table of contents: -@itemize @bullet +@itemize @item first, define a new markup variable in the @code{\paper} block @item then, define a music function which aims at adding a toc element using this markup paper variable. @@ -890,7 +442,7 @@ tocAct = Init files: @file{ly/@/toc@/-init@/.ly}. -@refcommands +@predefined @funindex \table-of-contents @code{\table-of-contents} @@ -914,7 +466,7 @@ what was entered. This is convenient for checking the music; octaves that are off or accidentals that were mistyped stand out very much when listening to the MIDI output. -@refbugs +@knownissues Many musically interesting effects, such as swing, articulation, slurring, etc., are not translated to midi. @@ -931,6 +483,7 @@ output. Players that are known to work include * Creating MIDI files:: * MIDI block:: * MIDI instrument names:: +* What goes into the MIDI? FIXME:: @end menu @node Creating MIDI files @@ -954,11 +507,11 @@ to a score, for example, The tempo can be specified using the @code{\tempo} command within the actual music, see @ref{Metronome marks}. An alternative, which does not result in a metronome mark in the printed score, is shown in the example -above. In this example the tempo of quarter notes is set to 72 beats per +above. In this example the tempo of quarter notes is set to 72 beats per minute. This kind of tempo -specification can not take dotted note lengths as an argument. In this -case, break the dotted notes into smaller units. For example, a tempo +specification can not take dotted note lengths as an argument. In this +case, break the dotted notes into smaller units. For example, a tempo of 90 dotted quarter notes per minute can be specified as 270 eighth notes per minute @@ -1011,7 +564,7 @@ in the @code{\midi@{@}} section. @end example -@refbugs +@knownissues Unterminated (de)crescendos will not render properly in the midi file, resulting in silent passages of music. The workaround is to explicitly @@ -1051,7 +604,7 @@ enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block. The MIDI block is analogous to the layout block, but it is somewhat -simpler. The @code{\midi} block is similar to @code{\layout}. It can contain +simpler. The @code{\midi} block is similar to @code{\layout}. It can contain context definitions. @@ -1082,82 +635,59 @@ the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"}) instrument is used. -@c Yes, this is a cop-out; this info doesn't belong in the Scheme -@c chapter, but I'm not certain where to stick it. -@c I think I'll eventually split this chapter into a "paper/layout" -@c chapter and a "misc issues" chapter. -gp -@node Displaying LilyPond notation -@section Displaying LilyPond notation - -@funindex \displayLilyMusc -Displaying a music expression in LilyPond notation can be -done using the music function @code{\displayLilyMusic}. For example, +@node What goes into the MIDI? FIXME +@subsection What goes into the MIDI? FIXME -@example -@{ - \displayLilyMusic \transpose c a, @{ c e g a bes @} -@} -@end example - -will display +@menu +* Repeats and MIDI:: +@end menu -@example -@{ a, cis e fis g @} -@end example +@node Repeats and MIDI +@subsubsection Repeats and MIDI + +@cindex expanding repeats +@funindex \unfoldRepeats + +With a little bit of tweaking, all types of repeats can be present +in the MIDI output. This is achieved by applying the +@code{\unfoldRepeats} music function. This function changes all +repeats to unfold repeats. + +@lilypond[quote,verbatim,fragment,line-width=8.0\cm] +\unfoldRepeats { + \repeat tremolo 8 {c'32 e' } + \repeat percent 2 { c''8 d'' } + \repeat volta 2 {c'4 d' e' f'} + \alternative { + { g' a' a' g' } + {f' e' d' c' } + } +} +\bar "|." +@end lilypond -By default, LilyPond will print these messages to the console along -with all the other messages. To split up these messages and save -the results of @code{\display@{STUFF@}}, redirect the output to -a file. +When creating a score file using @code{\unfoldRepeats} for MIDI, +it is necessary to make two @code{\score} blocks: one for MIDI +(with unfolded repeats) and one for notation (with volta, tremolo, +and percent repeats). For example, @example -lilypond file.ly >display.txt +\score @{ + @var{..music..} + \layout @{ .. @} +@} +\score @{ + \unfoldRepeats @var{..music..} + \midi @{ .. @} +@} @end example -@node Skipping corrected music -@section Skipping corrected music - - -@funindex skipTypesetting -@funindex showLastLength - -When entering or copying music, usually only the music near the end (where -you -are adding notes) is interesting to view and correct. To speed up -this correction process, it is possible to skip typesetting of all but -the last few measures. This is achieved by putting +@node other midi +@section other midi -@verbatim -showLastLength = R1*5 -\score { ... } -@end verbatim - -@noindent -in your source file. This will render only the last 5 measures -(assuming 4/4 time signature) of every @code{\score} in the input -file. For longer pieces, rendering only a small part is often an order -of magnitude quicker than rendering it completely - -Skipping parts of a score can be controlled in a more fine-grained -fashion with the property @code{Score.skipTypesetting}. When it is -set, no typesetting is performed at all. - -This property is also used to control output to the MIDI file. Note that -it skips all events, including tempo and instrument changes. You have -been warned. - -@lilypond[quote,fragment,ragged-right,verbatim] -\relative c'' { - c8 d - \set Score.skipTypesetting = ##t - e e e e e e e e - \set Score.skipTypesetting = ##f - c d b bes a g c2 } -@end lilypond +Micro tones are also exported to the MIDI file. -In polyphonic music, @code{Score.skipTypesetting} will affect all -voices and staves, saving even more time.