Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@c \version "2.15.17"
@node General input and output
@chapter General input and output
* Working with input files::
* Controlling output::
* MIDI output::
+* Extracting musical information::
@end menu
@{ c'4 d' e'2 @}
@}
@}
+ \layout @{ @}
@}
- \layout @{ @}
- \header @{ @}
+ \paper @{ @}
+ \header @{ @}
@}
@end example
@item After every command or variable, i.e. every item that
begins with a @code{\} sign.
@item After every item that is to be interpreted as a Scheme
-expression, i.e. every item that begins with a @code{#} sign.
+expression, i.e. every item that begins with a @code{#}@tie{}sign.
@item To separate all elements of a Scheme expression.
@item In @code{lyricmode} to separate all the terms in both
@code{\override} and @code{\set} commands. In particular, spaces
@node Creating titles headers and footers
-@subsection Creating titles, headers, and footers
+@subsection Creating titles headers and footers
@menu
* Title blocks explained::
@node Custom headers footers and titles
-@subsection Custom headers, footers, and titles
+@subsection Custom headers footers and titles
@c TODO: somewhere put a link to header spacing info
@c (you'll have to explain it more in NR 4).
}
@end lilypond
+@seealso
+Notation Reference:
+@ref{Title blocks explained}.
+
@node Custom layout for headers and footers
@unnumberedsubsubsec Custom layout for headers and footers
@item @code{evenFooterMarkup}
@end itemize
-These markup variables are discussed in
-@ref{Default layout of book and score title blocks}.
-
The following example centers page numbers at the bottom of every
page. First, the default settings for @code{oddHeaderMarkup} and
@code{evenHeaderMarkup} are removed by defining each as a @emph{null}
}
@end lilypond
+@seealso
+Notation Reference:
+@ref{Title blocks explained},
+@ref{Default layout of book and score title blocks}.
+
@node Reference to page numbers
@subsection Reference to page numbers
@node Table of contents
@subsection Table of contents
-A table of contents is included using the @code{\markuplines \table-of-contents}
+A table of contents is included using the @code{\markuplist \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
+\markuplist \table-of-contents
\pageBreak
\tocItem \markup "First score"
(add-toc-item! 'tocActMarkup text))
\book {
- \markuplines \table-of-contents
+ \markuplist \table-of-contents
\tocAct \markup { Atto Primo }
\tocItem \markup { Coro. Viva il nostro Alcide }
\tocItem \markup { Cesare. Presti omai l'Egizzia terra }
}
\book {
- \markuplines \table-of-contents
+ \markuplist \table-of-contents
\tocItem \markup { Allegro }
\tocItem \markup { Largo }
\markup \null
@menu
* Including LilyPond files::
* Different editions from one source::
-* Text encoding::
-* Displaying LilyPond notation::
+* Special characters::
@end menu
must all be relative to the directory containing the main file,
not the directory containing the included file. However,
this behavior can be changed by passing the option
-@code{-drelative-includes} option at the command line
+@option{-drelative-includes} option at the command line
(or by adding @code{#(ly:set-option 'relative-includes #t)}
at the top of the main input file). With @code{relative-includes}
set, the path for each @code{\include} command will be taken
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
LilyPond's installation files, LilyPond's file from the
installation files takes precedence.
-
@node Different editions from one source
@subsection Different editions from one source
-Several mechanisms are available to facilitate the generation
-of different versions of a score from the same music source.
-Variables are perhaps most useful for combining lengthy sections
-of music and/or annotation in various ways, while tags are more
-useful for selecting one from several alternative shorter sections
-of music. Whichever method is used, separating the notation from
-the structure of the score will make it easier to change the
-structure while leaving the notation untouched.
+Several methods can be used to generate different versions of a score
+from the same music source. Variables are perhaps the most useful for
+combining lengthy sections of music and/or annotation. Tags are more
+useful for selecting one section from several alternative shorter
+sections of music, and can also be used for splicing pieces of music
+together at different points.
+
+Whichever method is used, separating the notation from the structure of
+the score will make it easier to change the structure while leaving the
+notation untouched.
@menu
* Using variables::
@funindex \tag
@funindex \keepWithTag
@funindex \removeWithTag
+@funindex \pushToTag
+@funindex \appendToTag
@cindex tag
@cindex keep tagged music
@cindex remove tagged music
+@cindex splice into tagged music
The @code{\tag #'@var{partA}} command marks a music expression
with the name @var{partA}.
the first filter will remove all tagged sections except the one
named, and the second filter will remove even that tagged section.
+Sometimes you want to splice some music at a particular place in an
+existing music expression. You can use @code{\pushToTag} and
+@code{\appendToTag} for adding material at the front or end of the
+@code{elements} of an existing music construct. Not every music
+construct has @code{elements}, but sequential and simultaneous music are
+safe bets:
+
+@lilypond[verbatim,quote]
+test = { \tag #'here { \tag #'here <<c''>> } }
+
+{
+ \pushToTag #'here c'
+ \pushToTag #'here e'
+ \pushToTag #'here g' \test
+ \appendToTag #'here c'
+ \appendToTag #'here e'
+ \appendToTag #'here g' \test
+}
+@end lilypond
+
+Both commands get a tag, the material to splice in at every occurence of
+the tag, and the tagged expression. The commands make sure to
+copy everything that they change so that the original @code{\test}
+retains its meaning.
@seealso
Learning Manual:
Notation Reference:
@ref{Including LilyPond files}.
+@node Special characters
+@subsection Special characters
+
+@cindex special characters
+@cindex non-ASCII characters
+
+@menu
+* Text encoding::
+* Unicode::
+* ASCII aliases::
+@end menu
+
+
@node Text encoding
-@subsection Text encoding
+@unnumberedsubsubsec Text encoding
-@cindex Unicode
@cindex UTF-8
-@cindex non-ASCII characters
LilyPond uses the character repertoire defined by the Unicode
consortium and ISO/IEC 10646. This defines a unique name and
\addlyrics { \portuguese }
@end lilypond
+
+@node Unicode
+@unnumberedsubsubsec Unicode
+
+@cindex Unicode
+
To enter a single character for which the Unicode code point is
known but which is not available in the editor being used, use
either @code{\char ##xhhhh} or @code{\char #dddd} within a
@}
@end example
-@node Displaying LilyPond notation
-@subsection Displaying LilyPond notation
-@funindex \displayLilyMusic
-Displaying a music expression in LilyPond notation can be
-done with the music function @code{\displayLilyMusic} but only when
-using the command line. For example,
+@node ASCII aliases
+@unnumberedsubsubsec ASCII aliases
-@example
-@{
- \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
-@}
-@end example
+A list of ASCII aliases for special characters can be included:
-will display
+@lilypond[quote,verbatim]
+\paper {
+ #(include-special-characters)
+}
-@example
-@{ a,4 cis e fis g @}
-@end example
+\markup "&flqq; – &OE;uvre incomplète… &frqq;"
-By default, LilyPond will print these messages to the console
-along with all the other LilyPond compilation messages. To split
-up these messages and save the results of @code{\display@{STUFF@}},
-redirect the output to a file.
+\score {
+ \new Staff { \repeat unfold 9 a'4 }
+ \addlyrics {
+ This is al -- so wor -- kin'~in ly -- rics: –_&OE;…
+ }
+}
-@example
-lilypond file.ly >display.txt
-@end example
+\markup \column {
+ "The replacement can be disabled:"
+ "– &OE; …"
+ \override #'(replacement-alist . ()) "– &OE; …"
+}
+@end lilypond
+
+You can also make your own aliases, either globally:
+
+@lilypond[quote,verbatim]
+\paper {
+ #(add-text-replacements!
+ '(("100" . "hundred")
+ ("dpi" . "dots per inch")))
+}
+\markup "A 100 dpi."
+@end lilypond
+
+or locally:
+
+@lilypond[quote,verbatim]
+\markup \replace #'(("100" . "hundred")
+ ("dpi" . "dots per inch")) "A 100 dpi."
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{List of special characters}.
+
+Installed Files:
+@file{ly/text-replacements.ly}.
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
+@option{-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}.
Download and extract the zip file. Copy the @code{lilyfonts}
directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
-information, see @rlearning{Other sources of information}.
-Move the existing @code{fonts} directory to @code{fonts_orig} and
-move the @code{lilyfonts} directory to @code{fonts}. Simply move
-@code{fonts_orig} back to @code{fonts} to revert back to Feta.
+information, see @rlearning{Other sources of information}. Rename the
+existing @code{fonts} directory to @code{fonts_orig} and the
+@code{lilyfonts} directory to @code{fonts}. To revert back to Feta,
+reverse the process.
@seealso
Learning Manual: @rlearning{Other sources of information}.
@knownissues
-
-Gonville cannot be used to typeset @q{Ancient Music} notation. Please
-refer to the author's website for more information on this and other
-specifics including licensing of Gonville.
+Gonville cannot be used to typeset @q{Ancient Music} notation and it is
+likely newer glyphs in later releases of LilyPond may not exist in the
+Gonville font family. Please refer to the author's website for more
+information on these and other specifics, including licensing of
+Gonville.
@node MIDI output
more realistic MIDI output is available by means of
@ref{The Articulate script}.
-@c TODO Check this
-The midi output allocates a channel for each staff, and one for global
-settings. Therefore the midi file should not have more than 15 staves
-(or 14 if you do not use drums). Other staves will remain silent.
+The MIDI output allocates a channel for each staff, and reserves channel
+10 for drums. There are only 16 MIDI channels per device, so if the
+score contains more than 15 staves, MIDI channels will be reused.
@menu
* Creating MIDI files::
@snippets
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{changing-midi-output-to-one-channel-per-voice.ly}
@knownissues
Articulate shortens chords and some music (esp. organ music) could
sound worse.
+
+
+@node Extracting musical information
+@section Extracting musical information
+
+In addition to creating graphical output and MIDI, LilyPond can
+display musical information as text.
+
+@menu
+* Displaying LilyPond notation::
+* Displaying scheme music expressions::
+* Saving music events to a file::
+@end menu
+
+@node Displaying LilyPond notation
+@subsection Displaying LilyPond notation
+
+@funindex \displayLilyMusic
+Displaying a music expression in LilyPond notation can be
+done with the music function @code{\displayLilyMusic}. To see the
+output, you will typically want to call LilyPond using the command
+line. For example,
+
+@example
+@{
+ \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
+will display
+
+@example
+@{ a,4 cis e fis g @}
+@end example
+
+By default, LilyPond will print these messages to the console
+along with all the other LilyPond compilation messages. To split
+up these messages and save the results of @code{\display@{STUFF@}},
+redirect the output to a file.
+
+@example
+lilypond file.ly >display.txt
+@end example
+
+@funindex \void
+Note that Lilypond does not just display the music expression, but
+also interprets it (since @code{\displayLilyMusic} returns it in
+addition to displaying it). This is convenient since you can just
+insert @code{\displayLilyMusic} into existing music in order to get
+information about it. If you don't actually want Lilypond to
+interpret the displayed music as well as display it, use @code{\void}
+in order to have it ignored:
+
+@example
+@{
+ \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
+
+@node Displaying scheme music expressions
+@subsection Displaying scheme music expressions
+
+See @rextend{Displaying music expressions}.
+
+
+@node Saving music events to a file
+@subsection Saving music events to a file
+
+Music events can be saved to a file on a per-staff basis by
+including a file in your main score.
+
+@example
+\include "event-listener.ly"
+@end example
+
+This will create file(s) called @file{FILENAME-STAFFNAME.notes} or
+@file{FILENAME-unnamed-staff.notes} for each staff. Note that if
+you have multiple unnamed staves, the events for all staves will
+be mixed together in the same file. The output looks like this:
+
+@example
+0.000 note 57 4 p-c 2 12
+0.000 dynamic f
+0.250 note 62 4 p-c 7 12
+0.500 note 66 8 p-c 9 12
+0.625 note 69 8 p-c 14 12
+0.750 rest 4
+0.750 breathe
+@end example
+
+The syntax is a tab-delimited line, with two fixed fields on each
+line followed by optional parameters.
+
+@example
+@var{time} @var{type} @var{...params...}
+@end example
+
+This information can easily be read into other programs such as
+python scripts, and can be very useful for researchers wishing to
+perform musical analysis or playback experiments with LilyPond.
+
+
+@knownissues
+
+Not all lilypond music events are supported by
+@file{event-listener.ly}. It is intended to be a well-crafted
+@qq{proof of concept}. If some events that you want to see are
+not included, copy @file{event-listener.ly} into your lilypond
+directory and modify the file so that it outputs the information
+you want.
projects / lilypond.git / blobdiff