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::
+* 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.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
(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
+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
+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.
expressions, wherever they appear.
@cindex variables
-@cindex identifiers
@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
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
+@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,
+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.
@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
+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
+separately. For example, including the following definition
@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
+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
+@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}.
+For more information on output formats, see @rprogram{Invoking lilypond}.
@seealso
-Examples: @inputfileref{input/regression/,clip-systems.ly}
+Examples: @lsr{non-notation,clip-systems.ly}
@node Including LilyPond files
@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
@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
@section Titles and headers
@menu
* Creating titles::
* Custom titles::
+* Reference to page numbers::
+* Table of contents::
@end menu
}
@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
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
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