X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finput.itely;h=c990b3ba4e3f4053ec02837f13d911effb575a1e;hb=f5528d083b22894a654ee5f904baf8bb2a2f1f9c;hp=081494939a3528e9eb0302549e572d44c2a9a1da;hpb=403be13c57d964e42f7ef860a8361ba07970e3ce;p=lilypond.git diff --git a/Documentation/user/input.itely b/Documentation/user/input.itely index 081494939a..c990b3ba4e 100644 --- a/Documentation/user/input.itely +++ b/Documentation/user/input.itely @@ -7,12 +7,12 @@ version that you are working on. See TRANSLATION for details. @end ignore -@c \version "2.11.51" +@c \version "2.12.0" -@node Input syntax -@chapter Input syntax +@node General input and output +@chapter General input and output -This section deals with general LilyPond input syntax issues, +This section deals with general LilyPond input and output issues, rather than specific notation. @menu @@ -99,10 +99,9 @@ input file. They may be placed inside or outside a @code{\score} block, and inside or outside the single music expression within a @code{\score} block. -@seealso +@seealso Learning Manual: - @rlearning{Working on input files}, @rlearning{Music expressions explained}, @rlearning{Score is a (single) compound musical expression}. @@ -185,6 +184,30 @@ the top of the file is inserted. @} @end example +@funindex \bookpart + +Pieces of music may be grouped into book parts using @code{\bookpart} +blocks. Book parts are separated by a page break, and can start with a +title, like the book itself, by specifying a @code{\header} block. + +@example +\bookpart @{ + \header @{ + title = "Book title" + subtitle = "First part" + @} + \score @{ @dots{} @} + @dots{} +@} +\bookpart @{ + \header @{ + subtitle = "Second part" + @} + \score @{ @dots{} @} + @dots{} +@} +@end example + @node File structure @subsection File structure @@ -194,6 +217,7 @@ the top of the file is inserted. @funindex \header @funindex \score @funindex \book +@funindex \bookpart A @code{.ly} file may contain any number of toplevel expressions, where a toplevel expression is one of the following: @@ -238,6 +262,11 @@ 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 @code{\bookpart} block. A book may be divided into several parts, +using @code{\bookpart} blocks, in order to ease the page breaking, +or to use different @code{\paper} settings in different parts. + @item A compound music expression, such as @example @@ -287,7 +316,7 @@ foo = @{ c4 d e d @} @end example This can be used later on in the file by entering @code{\foo}. The -name of an variable should have alphabetic characters only; no +name of a variable should have alphabetic characters only; no numbers, underscores or dashes. @end itemize @@ -325,11 +354,12 @@ A multi-line comment delimited by @code{%@{ .. %@}}. @end itemize -@seealso +@seealso Learning Manual: @rlearning{How LilyPond input files work}. + @node Titles and headers @section Titles and headers @@ -348,7 +378,8 @@ some pieces include a lot more information. @subsection Creating titles Titles are created for each @code{\score} block, as well as for the full -input file (or @code{\book} block). +input file (or @code{\book} block) and book parts (created by +@code{\bookpart} blocks). The contents of the titles are taken from the @code{\header} blocks. The header block for a book supports the following @@ -373,32 +404,32 @@ Subsubtitle, centered below the subtitle. @funindex poet @item poet -Name of the poet, flush-left below the subtitle. +Name of the poet, flush-left below the subsubtitle. + +@funindex instrument +@item instrument +Name of the instrument, centered below the subsubtitle. Also +centered at the top of pages (other than the first page). @funindex composer @item composer -Name of the composer, flush-right below the subtitle. +Name of the composer, flush-right below the subsubtitle. @funindex meter @item meter Meter string, flush-left below the poet. -@funindex opus -@item opus -Name of the opus, flush-right below the composer. - @funindex arranger @item arranger -Name of the arranger, flush-right below the opus. - -@funindex instrument -@item instrument -Name of the instrument, centered below the arranger. Also -centered at the top of pages (other than the first page). +Name of the arranger, flush-right below the composer. @funindex piece @item piece -Name of the piece, flush-left below the instrument. +Name of the piece, flush-left below the meter. + +@funindex opus +@item opus +Name of the opus, flush-right below the arranger. @cindex page breaks, forcing @funindex breakbefore @@ -428,13 +459,13 @@ may use any @ref{Formatting text}, commands in the header. \book { \header { dedication = "dedicated to me" - title = \markup \center-align { "Title first line" "Title second line, + title = \markup \center-column { "Title first line" "Title second line, longer" } subtitle = "the subtitle," subsubtitle = #(string-append "subsubtitle LilyPond version " (lilypond-version)) poet = "Poet" - composer = \markup \center-align { "composer" \small "(1847-1973)" } + composer = \markup \center-column { "composer" \small "(1847-1973)" } texttranslator = "Text Translator" meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge "r" } @@ -498,14 +529,14 @@ Note that the music expression must come before the @code{\header}. } @end lilypond -@funindex printallheaders +@funindex print-all-headers @noindent You may change this behavior (and print all the headers when defining @code{\header} inside @code{\score}) by using @example \paper@{ - printallheaders=##t + print-all-headers = ##t @} @end example @@ -635,12 +666,14 @@ 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. -@predefined +@predefined @funindex \label -@code{\label} +@code{\label}, @funindex \page-ref -@code{\page-ref} +@code{\page-ref}. +@endpredefined + @node Table of contents @subsection Table of contents @@ -744,16 +777,17 @@ tocAct = } @end lilypond -@seealso +@seealso Init files: @file{../ly/@/toc@/-init@/.ly}. -@predefined +@predefined @funindex \table-of-contents -@code{\table-of-contents} +@code{\table-of-contents}, @funindex \tocItem -@code{\tocItem} +@code{\tocItem}. +@endpredefined @node Working with input files @@ -859,11 +893,13 @@ them will be lost on installing a new version of LilyPond. Some simple examples of using @code{\include} are shown in @rlearning{Scores and parts}. + @seealso Learning Manual: @rlearning{Other sources of information}, @rlearning{Scores and parts}. + @knownissues If an included file is given a name which is the same as one in @@ -1083,8 +1119,8 @@ expression will cause @emph{all} tagged sections to be removed, as the first filter will remove all tagged sections except the one named, and the second filter will remove even that tagged section. -@seealso +@seealso Learning Manual: @rlearning{Organizing pieces with variables}. @@ -1092,6 +1128,7 @@ Notation Reference: @ref{Automatic part combining}, @ref{Including LilyPond files}. + @ignore @c This warning is more general than this placement implies. @c Rests are not merged whether or not they come from tagged sections. @@ -1171,22 +1208,38 @@ portuguese = \lyricmode { @end lilypond To enter a single character for which the Unicode escape sequence -is known but which is not available in the editor being used, enter +is known but which is not available in the editor being used, use +@code{\char ##xhhhh} within a @code{\markup} block, where +@code{hhhh} is the hexadecimal code for the character required. +For example, @code{\char ##x03BE} enters the Unicode U+03BE +character, which has the Unicode name @qq{Greek Small Letter Xi}. +Any Unicode hexadecimal code may be substituted, and if all special +characters are entered in this format it is not necessary to save +the input file in UTF-8 format. Of course, a font containing all +such encoded characters must be installed and available to LilyPond. + +The following example shows UTF-8 coded characters being used in +four places -- in a rehearsal mark, as articulation text, in lyrics +and as stand-alone text below the score: -@example -#(ly:export (ly:wide-char->utf-8 #x03BE)) -@end example - -where in this example @code{x03BE} is the hexadecimal code for the -Unicode U+03BE character, which has the Unicode name @qq{Greek Small -Letter Xi}. Any Unicode hexadecimal code may be substituted, and -if all special characters are entered in this format it is not -necessary to save the input file in UTF-8 format. +@lilypond[quote,verbatim] +\score { + \relative c'' { + c1 \mark \markup { \char ##x03EE } + c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } } + } + \addlyrics { O \markup { \concat{ Ph \char ##x0153 be! } } } +} +\markup { "Copyright 2008" \char ##x00A9 } +@end lilypond -@knownissues +To enter the copyright sign in the copyright notice use: -The @code{ly:export} format may be used in text within @code{\mark} or -@code{\markup} commands but not in lyrics. +@example +\header @{ + copyright = \markup @{ \char ##x00A9 "2008" @} +@} +@end example @node Displaying LilyPond notation @subsection Displaying LilyPond notation @@ -1268,6 +1321,7 @@ For more information on output formats, see @rprogram{Invoking lilypond}. @funindex skipTypesetting +@funindex showFirstLength @funindex showLastLength When entering or copying music, usually only the music near the end (where @@ -1285,7 +1339,9 @@ showLastLength = R1*5 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 +of magnitude quicker than rendering it completely. When working on the +beginning of a score you have already typeset (e.g. to add a new part), +the @code{showFirstLength} property may be useful as well. Skipping parts of a score can be controlled in a more fine-grained fashion with the property @code{Score.skipTypesetting}. When it is @@ -1337,6 +1393,7 @@ settings. Therefore the midi file should not have more than 15 staves * What goes into the MIDI output?:: * Repeats in MIDI:: * Controlling MIDI dynamics:: +* Percussion in MIDI:: @end menu @node Creating MIDI files @@ -1392,13 +1449,13 @@ The name should be chosen from the list in @ref{MIDI instruments}. @example \new Staff @{ - \set Staff.midiInstrument = "glockenspiel" + \set Staff.midiInstrument = #"glockenspiel" @var{...notes...} @} @end example @example -\new Staff \with @{midiInstrument = "cello"@} @{ +\new Staff \with @{midiInstrument = #"cello"@} @{ @var{...notes...} @} @end example @@ -1546,6 +1603,7 @@ player that supports pitch bend.) @item Dynamic marks @item Crescendi, decrescendi over multiple notes @item Tempo changes entered with a tempo marking +@item Lyrics @end itemize @unnumberedsubsubsec Unsupported in MIDI @@ -1562,8 +1620,6 @@ The following items of notation have no effect on the MIDI output: @item Crescendi, decrescendi over a single note @item Tremolos entered with @q{@code{:}[@var{number}]} @item Figured bass -@c TODO Check Lyrics -@item Lyrics @end itemize @@ -1645,7 +1701,7 @@ found, or calls the default function otherwise. \score { \new Staff { - \set Staff.midiInstrument = "cello" + \set Staff.midiInstrument = #"cello" \set Score.dynamicAbsoluteVolumeFunction = #myDynamics \new Voice { \relative c'' { @@ -1838,8 +1894,8 @@ to the same values as the previous example. @ignore @c Delete when satisfied this is adequately covered elsewhere -td -@node Microtones in MIDI -@subsection Microtones in MIDI +@n ode Microtones in MIDI +@s ubsection Microtones in MIDI @cindex microtones in MIDI @@ -1866,4 +1922,34 @@ copied out and compiled to test microtones in your MIDI player. @end ignore +@node Percussion in MIDI +@subsection Percussion in MIDI + +Percussion instruments are generally notated in a @code{DrumStaff} +context and when notated in this way they are outputted correctly +to MIDI channel@tie{}10, but some pitched percussion instruments, +like the xylophone, marimba, vibraphone, timpani, etc., are +treated like @qq{normal} instruments and music for these instruments +should be entered in a normal @code{Staff} context, not a +@code{DrumStaff} context, to obtain the correct MIDI output. + +Some non-pitched percussion sounds included in the general MIDI +standard, like melodic tom, taiko drum, synth drum, etc., cannot +be reached via MIDI channel@tie{}10, so the notation for such +instruments should also be entered in a normal @code{Staff} +context, using suitable normal pitches. + +Many percussion instruments are not included in the general MIDI +standard, e.g. castanets. The easiest, although unsatisfactory, +method of producing some MIDI output when writing for such +instruments is to substitute the nearest sound from the standard +set. + +@c TODO Expand with examples, and any other issues + +@knownissues + +Because the general MIDI standard does not contain rim shots, the +sidestick is used for this purpose instead. +