@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
@c A menu is needed before every deeper *section nesting of @node's; run
@c M-x texinfo-all-menus-update
@section Input files
The main format of input for LilyPond are text files. By convention,
-these files end with ``@code{.ly}''.
+these files end with @samp{.ly}.
@menu
-* File structure (introduction)::
-* Multiple scores in a book::
-* Extracting fragments of notation::
* File structure::
* A single music expression::
+* Multiple scores in a book::
+* Extracting fragments of notation::
* Including LilyPond files::
* Text encoding::
+* Different editions from one source::
@end menu
-@node File structure (introduction)
-@subsection File structure (introduction)
-
-A basic example of a lilypond input file is
-
-@example
-\version "2.9.13"
-\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. The next section enumerates
-them all.
-
-
-@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
-
-The movements and texts are combined together in a @code{\book} block,
-like
-
-@example
-\book @{
- \score @{
- @var{..}
- @}
- \markup @{
- @var{..}
- @}
- \score @{
- @var{..}
- @}
-@}
-@end example
-
-
-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
-\book @{
- \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 @ref{Invoking lilypond}.
-
-@seealso
-
-Examples: @inputfileref{input/regression/,clip-systems.ly}
-
-
@node File structure
@subsection File structure
@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}, a single output file will be created
-in which all movements are concatenated.
+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
Markup texts are rendered above, between or below the scores or music
expressions, wherever they appear.
+@cindex variables
+
@item
-An identifier, such as
+An variable, 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
+name of an variable should have alphabetic characters only; no
numbers, underscores or dashes.
@end itemize
@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
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 ``full score'' file which brings
+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
finds.
Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
-VERSION is in the form ``2.6.1'') are on the path and available to
+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
search path.
The @code{\include} statement can use full path information, but with the Unix
-convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
+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
@file{texstr} backend,
@example
-lilypond -b texstr input/les-nereides.ly
+lilypond -dbackend=texstr input/les-nereides.ly
latex les-nereides.texstr
@end example
read when you execute
@example
-lilypond -b tex input/les-nereides.ly
+lilypond -dbackend=tex input/les-nereides.ly
@end example
Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
@seealso
-@inputfileref{input/regression,utf-8.ly}
+@lsr{text,utf-8.ly}
+
+
+@node Different editions from one source
+@subsection Different editions from one source
+@funindex \tag
+@cindex tag
+
+The @code{\tag} command marks music expressions with a name. These
+tagged expressions can be filtered out later. With this mechanism it
+is possible to make different versions of the same music source.
+
+In the following example, we see two versions of a piece of music, one
+for the full score, and one with cue notes for the instrumental part
+
+@example
+c1
+<<
+ \tag #'part <<
+ R1 \\
+ @{
+ \set fontSize = #-1
+ c4_"cue" f2 g4 @}
+ >>
+ \tag #'score R1
+>>
+c1
+@end example
+
+The same can be applied to articulations, texts, etc.: they are
+made by prepending
+@example
+-\tag #@var{your-tag}
+@end example
+to an articulation, for example,
+@example
+c1-\tag #'part ^4
+@end example
+
+This defines a note with a conditional fingering indication.
+
+@cindex keepWithTag
+@cindex removeWithTag
+By applying the @code{\keepWithTag} and @code{\removeWithTag}
+commands, tagged expressions can be filtered. For example,
+@example
+<<
+ @var{the music}
+ \keepWithTag #'score @var{the music}
+ \keepWithTag #'part @var{the music}
+>>
+@end example
+would yield
+
+@lilypondfile[ragged-right,quote]{tag-filter.ly}
+
+The arguments of the @code{\tag} command should be a symbol
+(such as @code{#'score} or @code{#'part}), followed by a
+music expression. It is possible to put multiple tags on
+a piece of music with multiple @code{\tag} entries,
+
+@example
+ \tag #'original-part \tag #'transposed-part @dots{}
+@end example
+
+
+@seealso
+
+Examples: @lsr{parts,tag@/-filter@/.ly}
+
+
+@refbugs
+
+Multiple rests are not merged if you create the score with both tagged
+sections.
@node Titles and headers
@menu
* Creating titles::
* Custom titles::
+* Reference to page numbers::
+* Table of contents::
@end menu
@node Creating titles
@subsection Creating titles
-Titles are created for each @code{\score} block, and over a
-@code{\book}.
+Titles are created for each @code{\score} block, as well as for the full
+input file (or @code{\book} block).
The contents of the titles are taken from the @code{\header} blocks.
The header block for a book supports the following
@end table
Here is a demonstration of the fields available. Note that you
-may use any @ref{Text markup} commands in the header.
+may use any @ref{Text markup}, commands in the header.
@lilypond[quote,verbatim,line-width=11.0\cm]
\paper {
The default footer is empty, except for the first page, where the
@code{copyright} field from @code{\header} is inserted, and the last
page, where @code{tagline} from @code{\header} is added. The default
-tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
+tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
printed parts are good PR for us, so please leave the tagline if you
can.}
@table @code
@funindex bookTitleMarkup
@item bookTitleMarkup
- This is the title put over an entire @code{\book} block. Typically,
- it has the composer and the title of the piece
+ This is the title added at the top of the entire output document.
+Typically, it has the composer and the title of the piece
@funindex scoreTitleMarkup
@item scoreTitleMarkup
- This is the title put over a @code{\score} block within a
-@code{\book}. Typically, it has the name of the movement (@code{piece}
-field).
+ This is the title put over a @code{\score} block. Typically, it has
+the name of the movement (@code{piece} field).
@funindex oddHeaderMarkup
@item oddHeaderMarkup
}
@end verbatim
+@node Reference to page numbers
+@subsection Reference to page numbers
+
+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
+point is placed, using the @code{\page-ref} markup command.
+
+@lilypond[verbatim,line-width=11.0\cm]
+\header { tagline = ##f }
+\book {
+ \label #'firstScore
+ \score {
+ {
+ c'1
+ \pageBreak \mark A \label #'markA
+ c'
+ }
+ }
+
+ \markup { The first score begins on page \page-ref #'firstScore "0" "?" }
+ \markup { Mark A is on page \page-ref #'markA "0" "?" }
+}
+@end lilypond
+The @code{\page-ref} markup command takes three arguments:
+@enumerate
+@item the label, a scheme symbol, eg. @code{#'firstScore};
+@item a markup that will be used as a gauge to estimate the dimensions
+of the markup;
+@item a markup that will be used in place of the page number if the label
+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
+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
+
+@funindex \label
+@code{\label}
+@funindex \page-ref
+@code{\page-ref}
+
+@node Table of contents
+@subsection Table of contents
+A table of contents is included using the @code{\markuplines \table-of-contents}
+command. The elements which should appear in the table of contents are
+entered with the @code{\tocItem} command, which may be used either at
+top-level, or inside a music expression.
+
+@verbatim
+\markuplines \table-of-contents
+\pageBreak
+
+\tocItem \markup "First score"
+\score {
+ {
+ c' % ...
+ \tocItem \markup "Some particular point in the first score"
+ d' % ...
+ }
+}
+
+\tocItem \markup "Second score"
+\score {
+ {
+ e' % ...
+ }
+}
+@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},
+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:
+
+@verbatim
+\paper {
+ %% Translate the toc title into French:
+ tocTitleMarkup = \markup \huge \column {
+ \fill-line { \null "Table des matières" \null }
+ \hspace #1
+ }
+ %% use larfer 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
+the @code{tocItemMarkup} definition.
+
+New commands and markups may also be defined to build more elaborated
+table of contents:
+@itemize @bullet
+@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.
+@end itemize
+
+In the following example, a new style is defined for entering act names
+in the table of contents of an opera:
+
+@verbatim
+\paper {
+ tocActMarkup = \markup \large \column {
+ \hspace #1
+ \fill-line { \null \italic \fromproperty #'toc:text \null }
+ \hspace #1
+ }
+}
+
+tocAct =
+#(define-music-function (parser location text) (markup?)
+ (add-toc-item! 'tocActMarkup text))
+@end verbatim
+
+@lilypond[line-width=11.0\cm]
+\header { tagline = ##f }
+\paper {
+ tocActMarkup = \markup \large \column {
+ \hspace #1
+ \fill-line { \null \italic \fromproperty #'toc:text \null }
+ \hspace #1
+ }
+}
+
+tocAct =
+#(define-music-function (parser location text) (markup?)
+ (add-toc-item! 'tocActMarkup text))
+
+\book {
+ \markuplines \table-of-contents
+ \tocAct \markup { Atto Primo }
+ \tocItem \markup { Coro. Viva il nostro Alcide }
+ \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
+ \tocAct \markup { Atto Secondo }
+ \tocItem \markup { Sinfonia }
+ \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
+ \markup \null
+}
+@end lilypond
+
+@seealso
+
+Init files: @file{ly/@/toc@/-init@/.ly}.
+
+@refcommands
+
+@funindex \table-of-contents
+@code{\table-of-contents}
+@funindex \tocItem
+@code{\tocItem}
@node MIDI output
@section MIDI output
@example
\score @{
@var{...music...}
- \midi @{ @}
+ \midi @{
+ \context @{
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 72 4)
+ @}
+ @}
@}
@end example
-FIXME
-
-The tempo is specified using the @code{\tempo} command. In this
-example the tempo of quarter notes is set to 72 beats per minute.
+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
+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
+of 90 dotted quarter notes per minute can be specified as 270 eighth
+notes per minute
+@example
+tempoWholesPerMinute = #(ly:make-moment 270 8)
+@end example
If there is a @code{\midi} command in a @code{\score}, only MIDI will
be produced. When notation is needed too, a @code{\layout} block must
\context @{
\Voice
\remove "Dynamic_performer"
- \remove "Span_dynamic_performer"
@}
@}
@end example
will.
+MIDI output is only created when the @code{\midi} command is within
+a @code{\score} block. If you put it within an explicitly instantiated
+context ( i.e. @code{\new Score} ) the file will fail. To solve this,
+enclose the @code{\new Score} and the @code{\midi} in a @code{\score} block.
+
+@example
+\score @{
+ \new Score @{ @dots{}notes@dots{} @}
+ \midi
+@}
+@end example
+
+
@node MIDI block
@subsection MIDI block
@cindex MIDI 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.
@node Displaying LilyPond notation
@section Displaying LilyPond notation
-@funindex \displayLilyMusc
+@funindex \displayLilyMusic
Displaying a music expression in LilyPond notation can be
done using the music function @code{\displayLilyMusic}. For example,
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
+the last few measures. This is achieved by putting
@verbatim
showLastLength = R1*5
@end verbatim
@noindent
-in your source file. This will render only the last 5 measures
+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
+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
+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]
projects / lilypond.git / blobdiff