From c53d0cabdf9361e448cdd02a338aa5d696f4f466 Mon Sep 17 00:00:00 2001 From: Han-Wen Nienhuys Date: Sun, 7 Mar 2004 00:13:44 +0000 Subject: [PATCH] * Documentation/user/changing-defaults.itely (Changing defaults): new file. * Documentation/user/notation.itely (Notation manual): rename from refman.itely * Documentation/user/notation-appendices.itely (The Feta font): new file. * Documentation/user/advanced.itely: add aborted attempt for advanced topics manual. --- ChangeLog | 19 + Documentation/user/advanced.itely | 175 ++++ ...{running.itely => changing-defaults.itely} | 762 ++++++++------ Documentation/user/internals.itely | 966 ------------------ Documentation/user/introduction.itely | 5 +- Documentation/user/invoking.itexi | 1 + Documentation/user/lilypond.tely | 20 +- Documentation/user/literature.itely | 2 +- Documentation/user/music-glossary.tely | 2 +- ...ndices.itely => notation-appendices.itely} | 38 +- .../user/{refman.itely => notation.itely} | 94 +- .../user/programming-interface.itely | 510 +++++++++ Documentation/user/tutorial.itely | 4 +- make/lilypond.redhat.spec.in | 4 +- scm/define-markup-commands.scm | 2 +- scm/documentation-generate.scm | 51 +- scm/new-markup.scm | 37 + 17 files changed, 1332 insertions(+), 1360 deletions(-) create mode 100644 Documentation/user/advanced.itely rename Documentation/user/{running.itely => changing-defaults.itely} (71%) delete mode 100644 Documentation/user/internals.itely rename Documentation/user/{appendices.itely => notation-appendices.itely} (83%) rename Documentation/user/{refman.itely => notation.itely} (98%) create mode 100644 Documentation/user/programming-interface.itely diff --git a/ChangeLog b/ChangeLog index dcf795a3d0..d5b68ddb60 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,22 @@ +2004-03-07 Han-Wen Nienhuys + + * Documentation/user/changing-defaults.itely (Changing defaults): + new file. + + * Documentation/user/notation.itely (Notation manual): rename from + refman.itely + + * Documentation/user/notation-appendices.itely (The Feta font): + new file. + + * Documentation/user/advanced.itely: add aborted attempt for + advanced topics manual. + +2004-03-06 Han-Wen Nienhuys + + * scm/new-markup.scm: display Markups in sane format. Patch by + Nicolas Sceaux. + 2004-03-05 Jan Nieuwenhuizen * lily/main.cc: Cleanups. diff --git a/Documentation/user/advanced.itely b/Documentation/user/advanced.itely new file mode 100644 index 0000000000..33b0df372a --- /dev/null +++ b/Documentation/user/advanced.itely @@ -0,0 +1,175 @@ +@c UNUSED !! -*-texinfo-*- + +@node Advanced concepts +@section Advanced concepts + + +Although LilyPond was designed to produce standard music notation, its +architecture is flexible, and it is possible to manipulate the +translation from a @file{.ly} file to a PDF file in many ways. This +chapter discusses outlines the options for customization. + +Before we can explain what is possible, it it is necessary to +understand the general architecture of LilyPond. The following +diagram shows the different steps in producing a PDF file: + +@verbatim + + Parsing Interpretation Formatting + +.ly file -> Music -> Notation -> + + + Formatting Dumping Titling + + -> Typography -> .tex -> .pdf file + +@end verbatim + +@enumerate + +@item @emph{Parsing} means reading a file, and translating letters and + numbers into data structures. + +@item The central data structure is the @emph{Music} expression. It is +the structure that stores music events (notes, chords, lyric +syllables, etc.) and their combinations. + +@item In order to print a piece music, separate events have to be +synchronized. For example, notes that sound together must be combined +horizontally, while syllables must be combined on a line. This happens +in the @emph{interpretating} step. + +@item The result of @emph{interpreting} is @emph{notation}, a +collection of layout objects. + +@item The exact appearance of the layout objects is determined during +@emph{formatting}. For example, in this step spacing and beam slopes +are determined. + +@item After formatting, LilyPond dumps a @TeX{} file containing the +symbols and their offsets. + +@item In a final step, titles are added to the music, resulting in a +PostScript, DVI or PDF file. + +@end enumerate + +This chapter discusses Steps@tie{}1. to@tie{}4. Step@tie{}5 is +discussed in @ref{Tuning output}, while Step@tie{}6 is discussed in +@ref{Invoking LilyPond}. + +The diagram above shows how music typesetting has been split-up in +multiple subproblems. However, splitting up problems always produces +the new problem of putting together the subsolutions to these +subproblems. Therefore, we will start our advanced topics class with a +discussion of the programming language Scheme, which lubricates the +interactions between different modules of LilyPond. + + + +@section Scheme in LilyPond +@node Scheme in LilyPond + +LilyPond includes an interpreter for the programming language Scheme, +a member of the LISP family. This interpreter, +@uref{GUILE,http://www.gnu.org/software/guile/}, +forms the basis of the + +**************************************************************** + +@c -*-texinfo-*- +@c Note: +@c +@c A menu is needed before every deeper *section nesting of @nodes +@c Run M-x texinfo-all-menus-update +@c to automatically fill in these menus +@c before saving changes + + +@node Technical manual +@chapter Technical manual + + +When LilyPond is run, it reads music from a file, translates that into +notation, and outputs the result to a file. The most important steps +are the first three. Consequently, there are three important basic +concepts within LilyPond: music, translation and layout. The +following diagram illustrates the concepts, and list the terminology +associated with each step. + + +@verbatim + + +-------------+ Translation +----------+ + | | | | + | Music | ------------------> | Layout | + | | | | + +-------------+ +----------+ + + +Syntax: c4 \context \set #'padding = + \override + +Objects: Music expressions Contexts Layout object + Engravers (aka. Grob) + +Example objects: NoteEvent Voice NoteHead + Note_heads_engraver + +Example properties: #'pitch keySignature #'line-count + +User applications: none various tuning layout + +@end verbatim + +The objects passed around in LilyPond have @emph{properties}, +variables that can contain many different types of information. Users +can set these variables, to modify the default behavior. Since there +are three different main concepts, there are also three types of +properties: + +@cindex properties +@cindex concepts, main +@cindex context +@cindex music expressions +@cindex layout +@cindex grob + + +@table @b +@item Music properties +These are used internally, and most users will not see or use them. + +They use Scheme-style naming, i.e. lowercase words separated with +dashes: @code{pitch}, @code{tremolo-type}. + +@item Translation properties +These influence the translation process, and most users will encounter them +regularly. For example, beaming behavior is tuned with +@code{autoBeamSettings}. + +These use mixed-caps naming: @code{autoBeamSettings}, +@code{ignoreMelismata}. They are assigned as follows: +@example + \set ignoreMelismata = ... +@end example + +@item Layout properties +These are internally used in the formatting process. Consequently, to +tune formatting details, it is necessary to adjust these +properties. For example, some objects may be moved around vertically +by setting their @code{padding} property. + +These properties use Scheme-style naming: @code{c0-position}, +@code{break-align-symbol}. They most often assigned as follows: + +@example + \override Score.RehearsalMark #'break-align-symbol = ... +@end example + +@noindent +Here, @code{RehearsalMark} is the type of the layout object. + +@end table + diff --git a/Documentation/user/running.itely b/Documentation/user/changing-defaults.itely similarity index 71% rename from Documentation/user/running.itely rename to Documentation/user/changing-defaults.itely index e0395c30af..7d5fd57dcb 100644 --- a/Documentation/user/running.itely +++ b/Documentation/user/changing-defaults.itely @@ -1,15 +1,66 @@ -@node Using LilyPond -@chapter Using LilyPond +@c -*-texinfo-*- +@node Changing defaults +@chapter Changing defaults + +TODO: reorganise. + +@menu +* Scheme integration:: +* Setting variables:: +* Fine tuning layout:: +* Tuning output:: +* Text markup:: +* Global layout:: +* Interpretation context:: +* Output details:: +@end menu + + + +@node Scheme integration +@section Scheme integration + +@cindex Scheme +@cindex GUILE +@cindex Scheme, in-line code +@cindex accessing Scheme +@cindex evaluating Scheme +@cindex LISP + +LilyPond internally uses GUILE, a Scheme-interpreter, to represent +data throughout the whole program, and glue together different program +modules. For advanced usage, it is sometimes necessary to access and +program the Scheme interpreter. + +Scheme is a full-blown programming language, from the LISP +family. and a full discussion is outside the scope of this document. +Interested readers are referred to the website +@uref{http://www.schemers.org/} for more information on Scheme. + +The GUILE library for extension is documented at +@uref{http://www.gnu.org/software/guile}. +@ifinfo +When it is installed, the following link should take you to its manual +@ref{(guile.info)guile} +@end ifinfo @menu -* Setting variables:: -* Fine tuning layout:: -* Tuning output:: -* Text markup:: -* Global layout:: -* Sound:: +* Inline Scheme:: @end menu +@node Inline Scheme +@subsection Inline Scheme + +Scheme expressions can be entered in the input file by entering a +hash-sign (@code{#}). The expression following the hash-sign is +evaluated as Scheme. For example, the boolean value @var{true} is +@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t}, +and can be used in property assignments: +@example + \set Staff.autoBeaming = ##f +@end example + + @node Setting variables @section Setting variables @@ -253,15 +304,10 @@ layout property name: #'layout-property-name @end example -@seealso - -The introduction of the @ref{Technical manual} gives a more in-depth -treatment of the difference between translation and layout. @menu * Tuning objects:: * Constructing a tweak:: -* Applyoutput:: * Font selection:: @end menu @@ -526,44 +572,6 @@ Internals: the program reference also contains alphabetical lists of to tweak by browsing the internals document. -@node Applyoutput -@subsection Applyoutput - -The most versatile way of tuning an object is @code{\applyoutput}. Its -syntax is -@example -\applyoutput @var{proc} -@end example - -@noindent -where @var{proc} is a Scheme function, taking three arguments. - -When interpreted, the function @var{proc} is called for every layout -object found in the context, with the following arguments: -@itemize @bullet -@item the layout object itself, -@item the context where the layout object was created, and -@item the context where @code{\applyoutput} is processed. -@end itemize - - -In addition, the cause of the layout object, i.e. the music -expression or object that was responsible for creating it, is in the -object property @code{cause}. For example, for a note head, this is a -@internalsref{NoteHead} event, and for a @internalsref{Stem} object, -this is a @internalsref{NoteHead} object. - -Here is a simple example of @code{\applyoutput}; it blanks note-heads on the -center-line: -@example -(define (blanker grob grob-origin context) - (if (and (memq (ly:grob-property grob 'interfaces) - note-head-interface) - (eq? (ly:grob-property grob 'staff-position) 0)) - - (ly:grob-set-property! grob 'transparent #t))) -@end example - @node Font selection @@ -777,8 +785,6 @@ for formatting. @menu * Overview of text markup commands:: -* Markup construction in scheme:: -* Markup command definition:: @end menu @node Overview of text markup commands @@ -786,209 +792,6 @@ for formatting. @include markup-commands.tely -@node Markup construction in scheme -@subsection Markup construction in scheme - -@cindex defining markup commands - -The @code{markup} macro builds markup expressions in Scheme while -providing a LilyPond-like syntax. For example, -@example -(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world") - #:bigger #:line ("foo" "bar" "baz"))) -@end example - -@noindent -is equivalent to: -@example -\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @} - \bigger @{ foo bar baz @} > -@end example - -@noindent -This example exposes the main translation rules between regular -LilyPond markup syntax and scheme markup syntax, which are summed up -is this table: -@multitable @columnfractions .5 .5 -@item @b{LilyPond} @tab @b{Scheme} -@item @code{\command} @tab @code{#:command} -@item @code{\variable} @tab @code{variable} -@item @code{@{ ... @}} @tab @code{#:line ( ... )} -@item @code{\center-align < ... >} @tab @code{#:center ( ... )} -@item @code{string} @tab @code{"string"} -@item @code{#scheme-arg} @tab @code{scheme-arg} -@end multitable - -Besides, the whole scheme language is accessible inside the -@code{markup} macro: thus, one may use function calls inside -@code{markup} in order to manipulate character strings for -instance. This proves useful when defining new markup commands (see -@ref{Markup command definition}). - -@refbugs - -One can not feed the @code{#:line} (resp @code{#:center}, -@code{#:column}) command with a variable or the result of a function -call. Eg: -@lisp -(markup #:line (fun-that-returns-markups)) -@end lisp -is illegal. One should use the @code{make-line-markup} (resp -@code{make-center-markup}, @code{make-column-markup}) function -instead: -@lisp -(markup (make-line-markup (fun-that-returns-markups))) -@end lisp - -@node Markup command definition -@subsection Markup command definition - -New markup commands can be defined thanks to the @code{def-markup-command} scheme macro. -@lisp -(def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...) - (@var{arg1-type?} @var{arg2-type?} ...) - ..command body..) - - @var{argi}: i@var{th} command argument - @var{argi-type?}: a type predicate for the i@var{th} argument - @var{paper}: the `paper' definition - @var{props}: a list of alists, containing all active properties. -@end lisp - -As a simple example, we show how to add a @code{\smallcaps} command, -which selects @TeX{}'s small caps font. Normally, we could select the -small caps font as follows: - -@verbatim - \markup { \override #'(font-shape . caps) Text-in-caps } -@end verbatim - -This selects the caps font by setting the @code{font-shape} property to -@code{#'caps} for interpreting @code{Text-in-caps}. - -To make the above available as @code{\smallcaps} command, we have to -define a function using @code{def-markup-command}. The command should -take a single argument, of markup type. Therefore, the start of the -definition should read -@example - (def-markup-command (smallcaps paper props argument) (markup?) -@end example - -@noindent - -What follows is the content of the command: we should interpret -the @code{argument} as a markup, i.e. - -@example - (interpret-markup paper @dots{} argument) -@end example - -@noindent -This interpretation should add @code{'(font-shape . caps)} to the active -properties, so we substitute the the following for the @dots{} in the -above example: - -@example - (cons (list '(font-shape . caps) ) props) -@end example - -@noindent -The variable @code{props} is a list of alists, and we prepend to it by -consing a list with the extra setting. - -However, suppose that we are using a font that does not have a -small-caps variant. In that case, we have to fake the small caps font, -by setting a string in upcase, with the first letter a little larger: - -@example -#(def-markup-command (smallcaps paper props str) (string?) - "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" - (interpret-markup paper props - (make-line-markup - (map (lambda (s) - (if (= (string-length s) 0) - s - (markup #:large (string-upcase (substring s 0 1)) - #:translate (cons -0.6 0) - #:tiny (string-upcase (substring s 1))))) - (string-split str #\Space))))) -@end example - -The @code{smallcaps} command first splits its string argument into -tokens separated by spaces (@code{(string-split str #\Space)}); for -each token, a markup is built with the first letter made large and -upcased (@code{#:large (string-upcase (substring s 0 1))}), and a -second markup built with the following letters made tiny and upcased -(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond -introduces a space between markups on a line, the second markup is -translated to the left (@code{#:translate (cons -0.6 0) ...}). Then, -the markups built for each token are put in a line -(@code{(make-line-markup ...)}). Finally, the resulting markup is -passed to the @code{interpret-markup} function, with the @code{paper} -and @code{props} arguments. - -Finally, suppose that we are typesetting a recitative in an opera, and -we would like to define a command that will show character names in a -custom manner. Names should be printed with small caps and translated a -bit to the left and top. We will define a @code{\character} command -that takes into account the needed translation, and uses the newly -defined @code{\smallcaps} command: - -@verbatim -#(def-markup-command (character paper props name) (string?) - "Print the character name in small caps, translated to the left and - top. Syntax: \\character #\"name\"" - (interpret-markup paper props - (markup "" #:translate (cons -4 2) #:smallcaps name))) -@end verbatim - -There is one complication that needs explanation: texts above and below -the staff are moved vertically to be at a certain distance (the -@code{padding} property) from the staff and the notes. To make sure -that this mechanism does not annihilate the vertical effect of our -@code{#:translate}, we add an empty string (@code{""}) before the -translated text. Now the @code{""} will be put above the notes, and the -@code{name} is moved in relation to that empty string. The net effect is -that the text is moved to the upper left. - -The final result is as follows: -@verbatim -\score { - \notes { \fatText - c''^\markup \character #"Cleopatra" - e'^\markup \character #"Giulio Cesare" - } -} -@end verbatim - -@lilypond[raggedright] -#(def-markup-command (smallcaps paper props str) (string?) - "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" - (interpret-markup paper props - (make-line-markup - (map (lambda (s) - (if (= (string-length s) 0) - s - (markup #:large (string-upcase (substring s 0 1)) - #:translate (cons -0.6 0) - #:tiny (string-upcase (substring s 1))))) - (string-split str #\Space))))) - -#(def-markup-command (character paper props name) (string?) - "Print the character name in small caps, translated to the left and - top. Syntax: \\character #\"name\"" - (interpret-markup paper props - (markup "" #:translate (cons -4 0) #:smallcaps name))) - -\score { - \notes { \fatText - c''^\markup \character #"Cleopatra" - e'^\markup \character #"Giulio Cesare" - } -} -@end lilypond - - @node Global layout @section Global layout @@ -1396,89 +1199,428 @@ LilyPond has no concept of page layout, which makes it difficult to reliably choose page breaks in longer pieces. +@node Interpretation context +@section Interpretation context +@menu +* Creating contexts:: +* Default contexts:: +* Context properties:: +* Defining contexts:: +* Changing contexts locally:: +* Engravers and performers:: +* Defining new contexts:: +@end menu -@node Sound -@section Sound -@cindex Sound -Entered music can also be converted to MIDI output. The performance -is good enough for proof-hearing the music for errors. +Interpretation contexts are objects that only exist during program +run. During the interpretation phase (when @code{interpreting music} +is printed on the standard output), the music expression in a +@code{\score} block is interpreted in time order, the same order in +which we hear and play the music. During this phase, the interpretation +context holds the state for the current point within the music, for +example: +@itemize @bullet +@item What notes are playing at this point? -Ties, dynamics and tempo changes are interpreted. Dynamic marks, -crescendi and decrescendi translate into MIDI volume levels. Dynamic -marks translate to a fixed fraction of the available MIDI volume -range, crescendi and decrescendi make the volume vary linearly between -their two extremities. The fractions can be adjusted by -@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context. -For each type of MIDI instrument, a volume range can be defined. This -gives a basic equalizer control, which can enhance the quality of -the MIDI output remarkably. The equalizer can be controlled by -setting @code{instrumentEqualizer}. +@item What symbols will be printed at this point? -@refbugs +@item What is the current key signature, time signature, point within +the measure, etc.? +@end itemize -Many musically interesting effects, such as swing, articulation, -slurring, etc., are not translated to MIDI. +Contexts are grouped hierarchically: A @internalsref{Voice} context is +contained in a @internalsref{Staff} context (because a staff can contain +multiple voices at any point), a @internalsref{Staff} context is contained in +@internalsref{Score}, @internalsref{StaffGroup}, or +@internalsref{ChoirStaff} context. -Since slurs are not interpreted, @code{\lyricsto} and -@code{\addlyrics} sections will be interpreted wrongly. +Contexts associated with sheet music output are called @emph{notation +contexts}, those for sound output are called @emph{performance +contexts}. The default definitions of the standard notation and +performance contexts can be found in @file{ly/engraver-init.ly} and +@file{ly/performer-init.ly}, respectively. -The MIDI output allocates a channel for each Staff, and one for global -settings. Hence, the MIDI file should not have more than 15 staves -(or 14 if you do not use drums). +@node Creating contexts +@subsection Creating contexts +@cindex @code{\context} +@cindex context selection -@menu -* MIDI block:: -* MIDI instrument names:: -@end menu +Contexts for a music expression can be selected manually, using one of +the following music expressions: + +@example +\new @var{contexttype} @var{musicexpr} +\context @var{contexttype} [= @var{contextname}] @var{musicexpr} +@end example + +@noindent +This means that @var{musicexpr} should be interpreted within a context +of type @var{contexttype} (with name @var{contextname} if specified). +If no such context exists, it will be created: +@lilypond[verbatim,raggedright] +\score { + \notes \relative c'' { + c4 <> f + } +} +@end lilypond -@node MIDI block -@subsection MIDI block -@cindex MIDI block +@noindent +In this example, the @code{c} and @code{d} are printed on the default +staff. For the @code{e}, a context @code{Staff} called @code{another} +is specified; since that does not exist, a new context is created. +Within @code{another}, a (default) Voice context is created for the +@code{e4}. A context is ended when when all music referring it has +finished, so after the third quarter, @code{another} is removed. +The @code{\new} construction creates a context with a +generated, unique @var{contextname}. An expression with +@code{\new} always leads to a new context. This is convenient +for creating multiple staffs, multiple lyric lines, etc. -The MIDI block is analogous to the paper block, but it is somewhat -simpler. The @code{\midi} block can contain: -@cindex MIDI block +When using automatic staff changes, automatic phrasing, etc., the +context names have special meanings, so @code{\new} cannot be +used. -@itemize @bullet - @item a @code{\tempo} definition, and - @item context definitions. -@end itemize -Assignments in the @code{\midi} block are not allowed. +@node Default contexts +@subsection Default contexts -A number followed by a period is interpreted as a real number, so -for setting the tempo for dotted notes, an extra space should be -inserted, for example: +Every top level music is interpreted by the @code{Score} context; in +other words, you may think of @code{\score} working like @example - \midi @{ \tempo 4 . = 120 @} +\score @{ + \context Score @var{music} +@} @end example +Music expressions inherit their context from the enclosing music +expression. Hence, it is not necessary to explicitly specify +@code{\context} for most expressions. In +the following example, only the sequential expression has an explicit +context. The notes contained therein inherit the @code{goUp} context +from the enclosing music expression. + +@lilypond[verbatim,raggedright] + \notes \context Voice = goUp { c'4 d' e' } +@end lilypond + + +Second, contexts are created automatically to be able to interpret the +music expressions. Consider the following example: + +@lilypond[verbatim,raggedright] + \score { \notes { c'4-( d' e'-) } } +@end lilypond + +@noindent +The sequential music is interpreted by the Score context initially, +but when a note is encountered, contexts are setup to accept that +note. In this case, a @code{Voice}, and @code{Staff} +context are created. The rest of the sequential music is also +interpreted with the same @code{Voice}, and +@code{Staff} context, putting the notes on the same staff, in the same +voice. + +@node Context properties +@subsection Context properties + +Contexts have properties. These properties are set from the @file{.ly} +file using the following expression: +@cindex context properties +@cindex properties, context + +@example +\set @var{contextname}.@var{propname} = @var{value} +@end example + +@noindent +Sets the @var{propname} property of the context @var{contextname} to +the specified Scheme expression @var{value}. Both @var{propname} and +@var{contextname} are strings, which can often be written unquoted. + +@cindex inheriting +Properties that are set in one context are inherited by all of the +contained contexts. This means that a property valid for the +@internalsref{Voice} context can be set in the @internalsref{Score} context +(for example) and thus take effect in all @internalsref{Voice} contexts. + +Properties can be unset using the following statement. +@example +\unset @var{contextname}.@var{propname} +@end example + +@cindex properties, unsetting +@cindex @code{\unset} + +@noindent +This removes the definition of @var{propname} in @var{contextname}. If +@var{propname} was not defined in @var{contextname} (but was inherited +from a higher context), then this has no effect. + +If @var{contextname} is left out, then it defaults to the current +``bottom'' context: this is a context like @internalsref{Voice} that +cannot contain any other contexts. + + +@node Defining contexts +@subsection Defining contexts @cindex context definition +@cindex translator definition + +The most common way to create a new context definition is by extending +an existing one. An existing context from the paper block is copied +by referencing a context identifier: + +@example +\paper @{ + \translator @{ + @var{context-identifier} + @} +@} +@end example + +@noindent +Every predefined context has a standard identifier. For example, the +@code{Staff} context can be referred to as @code{\StaffContext}. + +The context can then be modified by setting or changing properties, +e.g. +@example +\translator @{ + \StaffContext + Stem \set #'thickness = #2.0 + defaultBarType = #"||" +@} +@end example +These assignments happen before interpretation starts, so a property +command will override any predefined settings. + +@cindex engraver + +@refbugs + +It is not possible to collect multiple property assignments in a +variable, and apply to one @code{\translator} definition by +referencing that variable. + +@node Changing contexts locally +@subsection Changing contexts locally -Context definitions follow precisely the same syntax as within the -\paper block. Translation modules for sound are called performers. -The contexts for MIDI output are defined in @file{ly/performer-init.ly}. +Extending an existing context can also be done locally. A piece of +music can be interpreted in a changed context by using the following syntax -@node MIDI instrument names -@subsection MIDI instrument names +@example + \with @{ + @var{context modifications} + @} +@end example -@cindex instrument names -@cindex @code{Staff.midiInstrument} +These statements comes between @code{\new} or @code{\context} and the +music to be interpreted. The @var{context modifications} property +settings and @code{\remove}, @code{\consists} and @code{\consistsend} +commands. The syntax is similar to the @code{\translator} block. -The MIDI instrument name is set by the @code{Staff.midiInstrument} -property. The instrument name should be chosen from the list in -@ref{MIDI instruments}. +The following example shows how a staff is created with bigger spaces, +and without a @code{Clef_engraver}. + +@lilypond[relative=1,fragment,verbatim] +<< + \new Staff { c4 es4 g2 } + \new Staff \with { + \override StaffSymbol #'staff-space = #(magstep 1.5) + fontSize = #1.5 + \remove "Clef_engraver" + } { + c4 es4 g2 + } >> +@end lilypond @refbugs -If the selected string does not exactly match, then the default is -used, which is the Grand Piano. +The command @code{\with} has no effect on contexts that already +exist. + + +@node Engravers and performers +@subsection Engravers and performers + + +Each context is composed of a number of building blocks, or plug-ins +called engravers. An engraver is a specialized C++ class that is +compiled into the executable. Typically, an engraver is responsible +for one function: the @code{Slur_engraver} creates only @code{Slur} +objects, and the @code{Skip_event_swallow_translator} only swallows +(silently gobbles) @code{SkipEvent}s. + + + +@cindex engraver +@cindex plug-in + +An existing context definition can be changed by adding or removing an +engraver. The syntax for these operations is +@example +\consists @var{engravername} +\remove @var{engravername} +@end example + +@cindex @code{\consists} +@cindex @code{\remove} + +@noindent +Here @var{engravername} is a string, the name of an engraver in the +system. In the following example, the @code{Clef_engraver} is removed +from the Staff context. The result is a staff without a clef, where +the middle C is at its default position, the center line: + +@lilypond[verbatim,raggedright] +\score { + \notes { + c'4 f'4 + } + \paper { + \translator { + \StaffContext + \remove Clef_engraver + } + } +} +@end lilypond + +A list of all engravers is in the internal documentation, +see @internalsref{Engravers}. + +@node Defining new contexts +@subsection Defining new contexts + + +It is also possible to define new contexts from scratch. To do this, +you must define give the new context a name. In the following +example, a very simple Staff context is created: one that will put +note heads on a staff symbol. + +@example +\translator @{ + \type "Engraver_group_engraver" + \name "SimpleStaff" + \alias "Staff" + \consists "Staff_symbol_engraver" + \consists "Note_head_engraver" + \consistsend "Axis_group_engraver" +@} +@end example + +@noindent +The argument of @code{\type} is the name for a special engraver that +handles cooperation between simple engravers such as +@code{Note_head_engraver} and @code{Staff_symbol_engraver}. This +should always be @code{Engraver_group_engraver} (unless you are +defining a Score context from scratch, in which case +@code{Score_engraver} must be used). + +The complete list of context modifiers is the following: +@itemize @bullet +@item @code{\alias} @var{alternate-name}: +This specifies a different name. In the above example, +@code{\set Staff.X = Y} will also work on @code{SimpleStaff}s. + +@item @code{\consistsend} @var{engravername}: +Analogous to @code{\consists}, but makes sure that +@var{engravername} is always added to the end of the list of +engravers. + +Engravers that group context objects into axis groups or alignments +need to be at the end of the list. @code{\consistsend} insures that +engravers stay at the end even if a user adds or removes engravers. + +@item @code{\accepts} @var{contextname}: +This context can contains @var{contextname} contexts. The first +@code{\accepts} is created as a default context when events (e.g. notes +or rests) are encountered. + +@item @code{\denies}: +The opposite of @code{\accepts}. + +@item @code{\name} @var{contextname}: +This sets the type name of the context, e.g. @code{Staff}, +@code{Voice}. If the name is not specified, the translator will not +do anything. +@end itemize + +@c EOF + + + + +@node Output details +@section Output details + +The default output format is La@TeX{}, which should be run +through La@TeX{}. Using the option @option{-f} +(or @option{--format}) other output formats can be selected also, but +currently none of them work reliably. + +At the beginning of the output file, various global parameters are +defined. Then the file @file{lilyponddefs.tex} is loaded to define +the macros used in the code which follows. @file{lilyponddefs.tex} +includes various other files, partially depending on the global +parameters. + +Now the music is output system by system (a `system' consists of all +staves belonging together). From @TeX{}'s point of view, a system is an +@code{\hbox} which contains a lowered @code{\vbox} so that it is centered +vertically on the baseline of the text. Between systems, +@code{\interscoreline} is inserted vertically to have stretchable space. +The horizontal dimension of the @code{\hbox} is given by the +@code{linewidth} parameter from LilyPond's @code{\paper} block. + +After the last system LilyPond emits a stronger variant of +@code{\interscoreline} only if the macro +@code{\lilypondpaperlastpagefill} is not defined (flushing the systems +to the top of the page). You can avoid that by setting the variable +@code{lastpagefill} in LilyPond's @code{\paper} block. + +It is possible to fine-tune the vertical offset further by defining the +macro @code{\lilypondscoreshift}: + +@example +\def\lilypondscoreshift@{0.25\baselineskip@} +@end example + +@noindent +where @code{\baselineskip} is the distance from one text line to the next. + +Here an example how to embed a small LilyPond file @code{foo.ly} into +running La@TeX{} text without using the @code{lilypond-book} script +(@pxref{lilypond-book manual}): + +@example +\documentclass@{article@} + +\def\lilypondpaperlastpagefill@{@} +\lineskip 5pt +\def\lilypondscoreshift@{0.25\baselineskip@} + +\begin@{document@} +This is running text which includes an example music file +\input@{foo.tex@} +right here. +\end@{document@} +@end example + +The file @file{foo.tex} has been simply produced with + +@example + lilypond-bin foo.ly +@end example + +The call to @code{\lineskip} assures that there is enough vertical space +between the LilyPond box and the surrounding text lines. diff --git a/Documentation/user/internals.itely b/Documentation/user/internals.itely deleted file mode 100644 index b152463824..0000000000 --- a/Documentation/user/internals.itely +++ /dev/null @@ -1,966 +0,0 @@ -@c -*-texinfo-*- -@c Note: -@c -@c A menu is needed before every deeper *section nesting of @nodes -@c Run M-x texinfo-all-menus-update -@c to automatically fill in these menus -@c before saving changes - - -@node Technical manual -@chapter Technical manual - - -When LilyPond is run, it reads music from a file, translates that into -notation, and outputs the result to a file. The most important steps -are the first three. Consequently, there are three important basic -concepts within LilyPond: music, translation and layout. The -following diagram illustrates the concepts, and list the terminology -associated with each step. - - -@verbatim - - +-------------+ Translation +----------+ - | | | | - | Music | ------------------> | Layout | - | | | | - +-------------+ +----------+ - - -Syntax: c4 \context \set #'padding = - \override - -Objects: Music expressions Contexts Layout object - Engravers (aka. Grob) - -Example objects: NoteEvent Voice NoteHead - Note_heads_engraver - -Example properties: #'pitch keySignature #'line-count - -User applications: none various tuning layout - -@end verbatim - -The objects passed around in LilyPond have @emph{properties}, -variables that can contain many different types of information. Users -can set these variables, to modify the default behavior. Since there -are three different main concepts, there are also three types of -properties: - -@cindex properties -@cindex concepts, main -@cindex context -@cindex music expressions -@cindex layout -@cindex grob - - -@table @b -@item Music properties -These are used internally, and most users will not see or use them. - -They use Scheme-style naming, i.e. lowercase words separated with -dashes: @code{pitch}, @code{tremolo-type}. - -@item Translation properties -These influence the translation process, and most users will encounter them -regularly. For example, beaming behavior is tuned with -@code{autoBeamSettings}. - -These use mixed-caps naming: @code{autoBeamSettings}, -@code{ignoreMelismata}. They are assigned as follows: -@example - \set ignoreMelismata = ... -@end example - -@item Layout properties -These are internally used in the formatting process. Consequently, to -tune formatting details, it is necessary to adjust these -properties. For example, some objects may be moved around vertically -by setting their @code{padding} property. - -These properties use Scheme-style naming: @code{c0-position}, -@code{break-align-symbol}. They most often assigned as follows: - -@example - \override Score.RehearsalMark #'break-align-symbol = ... -@end example - -@noindent -Here, @code{RehearsalMark} is the type of the layout object. - -@end table - -This chapter discusses details of the three concepts in more detail, -and explains how they are glued together in LilyPond with the embedded -Scheme interpreter. - -@menu -* Interpretation context:: -* Scheme integration:: -* Music storage format:: -* Lexical details:: -* Output details:: -@end menu - - -@node Interpretation context -@section Interpretation context - -@menu -* Creating contexts:: -* Default contexts:: -* Context properties:: -* Context evaluation:: -* Defining contexts:: -* Changing contexts locally:: -* Engravers and performers:: -* Defining new contexts:: -@end menu - - -Interpretation contexts are objects that only exist during program -run. During the interpretation phase (when @code{interpreting music} -is printed on the standard output), the music expression in a -@code{\score} block is interpreted in time order, the same order in -which we hear and play the music. During this phase, the interpretation -context holds the state for the current point within the music, for -example: -@itemize @bullet -@item What notes are playing at this point? - -@item What symbols will be printed at this point? - -@item What is the current key signature, time signature, point within -the measure, etc.? -@end itemize - -Contexts are grouped hierarchically: A @internalsref{Voice} context is -contained in a @internalsref{Staff} context (because a staff can contain -multiple voices at any point), a @internalsref{Staff} context is contained in -@internalsref{Score}, @internalsref{StaffGroup}, or -@internalsref{ChoirStaff} context. - -Contexts associated with sheet music output are called @emph{notation -contexts}, those for sound output are called @emph{performance -contexts}. The default definitions of the standard notation and -performance contexts can be found in @file{ly/engraver-init.ly} and -@file{ly/performer-init.ly}, respectively. - - -@node Creating contexts -@subsection Creating contexts -@cindex @code{\context} -@cindex context selection - -Contexts for a music expression can be selected manually, using one of -the following music expressions: - -@example -\new @var{contexttype} @var{musicexpr} -\context @var{contexttype} [= @var{contextname}] @var{musicexpr} -@end example - -@noindent -This means that @var{musicexpr} should be interpreted within a context -of type @var{contexttype} (with name @var{contextname} if specified). -If no such context exists, it will be created: - -@lilypond[verbatim,raggedright] -\score { - \notes \relative c'' { - c4 <> f - } -} -@end lilypond - -@noindent -In this example, the @code{c} and @code{d} are printed on the default -staff. For the @code{e}, a context @code{Staff} called @code{another} -is specified; since that does not exist, a new context is created. -Within @code{another}, a (default) Voice context is created for the -@code{e4}. A context is ended when when all music referring it has -finished, so after the third quarter, @code{another} is removed. - -The @code{\new} construction creates a context with a -generated, unique @var{contextname}. An expression with -@code{\new} always leads to a new context. This is convenient -for creating multiple staffs, multiple lyric lines, etc. - -When using automatic staff changes, automatic phrasing, etc., the -context names have special meanings, so @code{\new} cannot be -used. - - -@node Default contexts -@subsection Default contexts - -Every top level music is interpreted by the @code{Score} context; in -other words, you may think of @code{\score} working like - -@example -\score @{ - \context Score @var{music} -@} -@end example - -Music expressions inherit their context from the enclosing music -expression. Hence, it is not necessary to explicitly specify -@code{\context} for most expressions. In -the following example, only the sequential expression has an explicit -context. The notes contained therein inherit the @code{goUp} context -from the enclosing music expression. - -@lilypond[verbatim,raggedright] - \notes \context Voice = goUp { c'4 d' e' } -@end lilypond - - -Second, contexts are created automatically to be able to interpret the -music expressions. Consider the following example: - -@lilypond[verbatim,raggedright] - \score { \notes { c'4-( d' e'-) } } -@end lilypond - -@noindent -The sequential music is interpreted by the Score context initially, -but when a note is encountered, contexts are setup to accept that -note. In this case, a @code{Voice}, and @code{Staff} -context are created. The rest of the sequential music is also -interpreted with the same @code{Voice}, and -@code{Staff} context, putting the notes on the same staff, in the same -voice. - -@node Context properties -@subsection Context properties - -Contexts have properties. These properties are set from the @file{.ly} -file using the following expression: -@cindex context properties -@cindex properties, context - -@example -\set @var{contextname}.@var{propname} = @var{value} -@end example - -@noindent -Sets the @var{propname} property of the context @var{contextname} to -the specified Scheme expression @var{value}. Both @var{propname} and -@var{contextname} are strings, which can often be written unquoted. - -@cindex inheriting -Properties that are set in one context are inherited by all of the -contained contexts. This means that a property valid for the -@internalsref{Voice} context can be set in the @internalsref{Score} context -(for example) and thus take effect in all @internalsref{Voice} contexts. - -Properties can be unset using the following statement. -@example -\unset @var{contextname}.@var{propname} -@end example - -@cindex properties, unsetting -@cindex @code{\unset} - -@noindent -This removes the definition of @var{propname} in @var{contextname}. If -@var{propname} was not defined in @var{contextname} (but was inherited -from a higher context), then this has no effect. - -If @var{contextname} is left out, then it defaults to the current -``bottom'' context: this is a context like @internalsref{Voice} that -cannot contain any other contexts. - - - -@node Context evaluation -@subsection Context evaluation - -Contexts can be modified during interpretation with Scheme code. The -syntax for this is -@example - \applycontext @var{function} -@end example - -@var{function} should be a Scheme function taking a single argument, -being the context to apply it to. The following code will print the -current bar number on the standard output during the compile: - -@example - \applycontext - #(lambda (x) - (format #t "\nWe were called in barnumber ~a.\n" - (ly:context-property x 'currentBarNumber))) -@end example - - - -@node Defining contexts -@subsection Defining contexts - -@cindex context definition -@cindex translator definition - -The most common way to create a new context definition is by extending -an existing one. An existing context from the paper block is copied -by referencing a context identifier: - -@example -\paper @{ - \translator @{ - @var{context-identifier} - @} -@} -@end example - -@noindent -Every predefined context has a standard identifier. For example, the -@code{Staff} context can be referred to as @code{\StaffContext}. - -The context can then be modified by setting or changing properties, -e.g. -@example -\translator @{ - \StaffContext - Stem \set #'thickness = #2.0 - defaultBarType = #"||" -@} -@end example -These assignments happen before interpretation starts, so a property -command will override any predefined settings. - -@cindex engraver - -@refbugs - -It is not possible to collect multiple property assignments in a -variable, and apply to one @code{\translator} definition by -referencing that variable. - -@node Changing contexts locally -@subsection Changing contexts locally - - -Extending an existing context can also be done locally. A piece of -music can be interpreted in a changed context by using the following syntax - -@example - \with @{ - @var{context modifications} - @} -@end example - -These statements comes between @code{\new} or @code{\context} and the -music to be interpreted. The @var{context modifications} property -settings and @code{\remove}, @code{\consists} and @code{\consistsend} -commands. The syntax is similar to the @code{\translator} block. - -The following example shows how a staff is created with bigger spaces, -and without a @code{Clef_engraver}. - -@lilypond[relative=1,fragment,verbatim] -<< - \new Staff { c4 es4 g2 } - \new Staff \with { - \override StaffSymbol #'staff-space = #(magstep 1.5) - fontSize = #1.5 - \remove "Clef_engraver" - } { - c4 es4 g2 - } >> -@end lilypond - -@refbugs - -The command @code{\with} has no effect on contexts that already -exist. - - -@node Engravers and performers -@subsection Engravers and performers - - -Each context is composed of a number of building blocks, or plug-ins -called engravers. An engraver is a specialized C++ class that is -compiled into the executable. Typically, an engraver is responsible -for one function: the @code{Slur_engraver} creates only @code{Slur} -objects, and the @code{Skip_event_swallow_translator} only swallows -(silently gobbles) @code{SkipEvent}s. - - - -@cindex engraver -@cindex plug-in - -An existing context definition can be changed by adding or removing an -engraver. The syntax for these operations is -@example -\consists @var{engravername} -\remove @var{engravername} -@end example - -@cindex @code{\consists} -@cindex @code{\remove} - -@noindent -Here @var{engravername} is a string, the name of an engraver in the -system. In the following example, the @code{Clef_engraver} is removed -from the Staff context. The result is a staff without a clef, where -the middle C is at its default position, the center line: - -@lilypond[verbatim,raggedright] -\score { - \notes { - c'4 f'4 - } - \paper { - \translator { - \StaffContext - \remove Clef_engraver - } - } -} -@end lilypond - -A list of all engravers is in the internal documentation, -see @internalsref{Engravers}. - -@node Defining new contexts -@subsection Defining new contexts - - -It is also possible to define new contexts from scratch. To do this, -you must define give the new context a name. In the following -example, a very simple Staff context is created: one that will put -note heads on a staff symbol. - -@example -\translator @{ - \type "Engraver_group_engraver" - \name "SimpleStaff" - \alias "Staff" - \consists "Staff_symbol_engraver" - \consists "Note_head_engraver" - \consistsend "Axis_group_engraver" -@} -@end example - -@noindent -The argument of @code{\type} is the name for a special engraver that -handles cooperation between simple engravers such as -@code{Note_head_engraver} and @code{Staff_symbol_engraver}. This -should always be @code{Engraver_group_engraver} (unless you are -defining a Score context from scratch, in which case -@code{Score_engraver} must be used). - -The complete list of context modifiers is the following: -@itemize @bullet -@item @code{\alias} @var{alternate-name}: -This specifies a different name. In the above example, -@code{\set Staff.X = Y} will also work on @code{SimpleStaff}s. - -@item @code{\consistsend} @var{engravername}: -Analogous to @code{\consists}, but makes sure that -@var{engravername} is always added to the end of the list of -engravers. - -Engravers that group context objects into axis groups or alignments -need to be at the end of the list. @code{\consistsend} insures that -engravers stay at the end even if a user adds or removes engravers. - -@item @code{\accepts} @var{contextname}: -This context can contains @var{contextname} contexts. The first -@code{\accepts} is created as a default context when events (e.g. notes -or rests) are encountered. - -@item @code{\denies}: -The opposite of @code{\accepts}. - -@item @code{\name} @var{contextname}: -This sets the type name of the context, e.g. @code{Staff}, -@code{Voice}. If the name is not specified, the translator will not -do anything. -@end itemize - - -@node Scheme integration -@section Scheme integration - -@cindex Scheme -@cindex GUILE -@cindex Scheme, in-line code -@cindex accessing Scheme -@cindex evaluating Scheme -@cindex LISP - -LilyPond internally uses GUILE, a Scheme-interpreter, to represent -data throughout the whole program, and glue together different program -modules. For advanced usage, it is sometimes necessary to access and -program the Scheme interpreter. - -Scheme is a full-blown programming language, from the LISP -family. and a full discussion is outside the scope of this document. -Interested readers are referred to the website -@uref{http://www.schemers.org/} for more information on Scheme. - -The GUILE library for extension is documented at -@uref{http://www.gnu.org/software/guile}. -@ifinfo -When it is installed, the following link should take you to its manual -@ref{(guile.info)guile} -@end ifinfo - -@menu -* Inline Scheme:: -* Input variables and Scheme:: -* Assignments:: -@end menu - -@node Inline Scheme -@subsection Inline Scheme - -Scheme expressions can be entered in the input file by entering a -hash-sign (@code{#}). The expression following the hash-sign is -evaluated as Scheme. For example, the boolean value @var{true} is -@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t}, -and can be used in property assignments: -@example - \set Staff.autoBeaming = ##f -@end example - - -@node Input variables and Scheme -@subsection Input variables and Scheme - - -The input format supports the notion of variable: in the following -example, a music expression is assigned to a variable with the name -@code{traLaLa}. -@example - traLaLa = \notes @{ c'4 d'4 @} -@end example - -@noindent - -There is also a form of scoping: in the following example, the -@code{\paper} block also contains a @code{traLaLa} variable, which is -independent of the outer @code{\traLaLa}. -@example - traLaLa = \notes @{ c'4 d'4 @} - \paper @{ traLaLa = 1.0 @} -@end example -@c -In effect, each input file is a scope, and all @code{\header}, -@code{\midi} and @code{\paper} blocks are scopes nested inside that -toplevel scope. - -Both variables and scoping are implemented in the GUILE module system. -An anonymous Scheme module is attached to each scope. An assignment of -the form -@example - traLaLa = \notes @{ c'4 d'4 @} -@end example - -@noindent -is internally converted to a Scheme definition -@example - (define traLaLa @var{Scheme value of ``@code{\notes ... }''}) -@end example - -This means that input variables and Scheme variables may be freely -mixed. In the following example, a music fragment is stored in the -variable @code{traLaLa}, and duplicated using Scheme. The result is -imported in a @code{\score} by means of a second variable -@code{twice}: -@example - traLaLa = \notes @{ c'4 d'4 @} - - #(define newLa (map ly:music-deep-copy - (list traLaLa traLaLa))) - #(define twice - (make-sequential-music newLa)) - - \score @{ \twice @} -@end example - -In the above example, music expressions can be `exported' from the -input to the Scheme interpreter. The opposite is also possible. By -wrapping a Scheme value in the function @code{ly:export}, a Scheme -value is interpreted as if it were entered in LilyPond syntax: instead -of defining @code{\twice}, the example above could also have been -written as -@example - @dots{} - \score @{ #(ly:export (make-sequential-music newLa)) @} -@end example - - - - - -@node Assignments -@subsection Assignments -@cindex Assignments - -Variables allow objects to be assigned to names during the parse -stage. To assign a variable, use -@example -@var{name}@code{=}@var{value} -@end example -To refer to a variable, precede its name with a backslash: -`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of -the input-types listed above. Variable assignments can appear at top -level in the LilyPond file, but also in @code{\paper} blocks. - -A variable can be created with any string for its name, but for -accessing it in the LilyPond syntax, its name must consist of -alphabetic characters only, and may not be a keyword of the syntax. -There are no restrictions for naming and accessing variables in the -Scheme interpreter, - -The right hand side of a variable assignment is parsed completely -before the assignment is done, so variables may be redefined in terms -of its old value, e.g. -@c -@example -foo = \foo * 2.0 -@end example - -When a variable is referenced in LilyPond syntax, the information it -points to is copied. For this reason, a variable reference must -always be the first item in a block. - -@example -\paper @{ - foo = 1.0 - \paperIdent % wrong and invalid -@} -@end example - -@example -\paper @{ - \paperIdent % correct - foo = 1.0 -@} -@end example - - - -@node Music storage format -@section Music storage format - -Music in LilyPond is entered as music expressions. This section -discusses different types of music expressions, and explains how -information is stored internally. This internal storage is accessible -through the Scheme interpreter, so music expressions may be -manipulated using Scheme functions. - -@menu -* Music expressions:: -* Internal music representation:: -* Manipulating music expressions:: -@end menu - -@node Music expressions -@subsection Music expressions -@cindex music expressions - -Notes, rests, lyric syllables are music expressions. Small music -expressions may be combined to form larger ones, for example, by -enclosing a list of expressions in @code{\sequential @{ @}} or @code{<< ->>}. In the following example, a compound expression is formed out of -the quarter note @code{c} and a quarter note @code{d}: - -@example -\sequential @{ c4 d4 @} -@end example - -@cindex Sequential music -@cindex @code{\sequential} -@cindex sequential music -@cindex @code{<<} -@cindex @code{>>} -@cindex Simultaneous music -@cindex @code{\simultaneous} - -The two basic compound music expressions are simultaneous and -sequential music: - -@example -\sequential @code{@{} @var{musicexprlist} @code{@}} -\simultaneous @code{@{} @var{musicexprlist} @code{@}} -@end example - -For both, there is a shorthand: - -@example -@code{@{} @var{musicexprlist} @code{@}} -@end example - -@noindent -for sequential and - -@example -@code{<<} @var{musicexprlist} @code{>>} -@end example - -@noindent -for simultaneous music. -In principle, the way in which you nest sequential and simultaneous to -produce music is not relevant. In the following example, three chords -are expressed in two different ways: - -@lilypond[fragment,verbatim,center] -\notes \context Voice { - <> <> <> - << { a b c' } { c' d' e' } >> -} -@end lilypond -However, using @code{<<} and @code{>>} for entering chords leads to -various peculiarities. For this reason, a special syntax -for chords was introduced in version 1.7: @code{< >}. - - - - - -Other compound music expressions include: -@example -\repeat @var{expr} -\transpose @var{from} @var{to} @var{expr} -\apply @var{func} @var{expr} -\context @var{type} = @var{id} @var{expr} -\times @var{fraction} @var{expr} -@end example - -@node Internal music representation -@subsection Internal music representation - - - - - - -When a music expression is parsed, it is converted into a set of -Scheme music objects. The defining property of a music object is that -it takes up time. Time is a rational number that measures the length -of a piece of music, in whole notes. - -A music object has three kinds of types: -@itemize @bullet -@item - music name: Each music expression has a name, for example, a note -leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to -a @internalsref{SimultaneousMusic}. A list of all expressions -available is in the internals manual, under @internalsref{Music -expressions}. - -@item - `type' or interface: Each music name has several `types' or interface, - for example, a note is an @code{event}, but it is also a @code{note-event}, - a @code{rhythmic-event} and a @code{melodic-event}. - - All classes of music are listed in the internals manual, under - @internalsref{Music classes}. -@item -C++ object: Each music object is represented by a C++ object. For technical -reasons, different music objects may be represented by different C++ -object types. For example, a note is @code{Event} object, while -@code{\grace} creates a @code{Grace_music} object. - -We expect that distinctions between different C++ types will disappear -in the future. -@end itemize - -The actual information of a music expression is stored in properties. -For example, a @internalsref{NoteEvent} has @code{pitch} and -@code{duration} properties that store the pitch and duration of that -note. A list of all properties available is in the internals manual, -under @internalsref{Music properties}. - -A compound music expression is a music object that contains other -music objects in its properties. A list of objects can be stored in -the @code{elements} property of a music object, or a single `child' -music object in the @code{element} object. For example, -@internalsref{SequentialMusic} has its children in @code{elements}, -and @internalsref{GraceMusic} has its single argument in -@code{element}. The body of a repeat is in @code{element} property of -@internalsref{RepeatedMusic}, and the alternatives in @code{elements}. - -@node Manipulating music expressions -@subsection Manipulating music expressions - -Music objects and their properties can be accessed and manipulated -directly, through the @code{\apply} mechanism. -The syntax for @code{\apply} is -@example -\apply #@var{func} @var{music} -@end example - -@noindent -This means that the scheme function @var{func} is called with -@var{music} as its argument. The return value of @var{func} is the -result of the entire expression. @var{func} may read and write music -properties using the functions @code{ly:music-property} and -@code{ly:music-set-property!}. - -An example is a function that reverses the order of elements in -its argument: -@lilypond[verbatim,raggedright] - #(define (rev-music-1 m) - (ly:music-set-property! m 'elements (reverse - (ly:music-property m 'elements))) - m) - \score { \notes \apply #rev-music-1 { c4 d4 } } -@end lilypond - -The use of such a function is very limited. The effect of this -function is void when applied to an argument which is does not have -multiple children. The following function application has no effect: - -@example - \apply #rev-music-1 \grace @{ c4 d4 @} -@end example - -@noindent -In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no -@code{elements}, only a single @code{element}. Every generally -applicable function for @code{\apply} must -- like music expressions -themselves -- be recursive. - -The following example is such a recursive function: It first extracts -the @code{elements} of an expression, reverses them and puts them -back. Then it recurses, both on @code{elements} and @code{element} -children. -@example -#(define (reverse-music music) - (let* ((elements (ly:music-property music 'elements)) - (child (ly:music-property music 'element)) - (reversed (reverse elements))) - - ; set children - (ly:music-set-property! music 'elements reversed) - - ; recurse - (if (ly:music? child) (reverse-music child)) - (map reverse-music reversed) - - music)) -@end example - -A slightly more elaborate example is in -@inputfileref{input/test,reverse-music.ly}. - -Some of the input syntax is also implemented as recursive music -functions. For example, the syntax for polyphony -@example - <> -@end example - -@noindent -is actually implemented as a recursive function that replaces the -above by the internal equivalent of -@example - << \context Voice = "1" @{ \voiceOne a @} - \context Voice = "2" @{ \voiceTwo b @} >> -@end example - -Other applications of @code{\apply} are writing out repeats -automatically (@inputfileref{input/test,unfold-all-repeats.ly}), -saving keystrokes (@inputfileref{input/test,music-box.ly}) and -exporting -LilyPond input to other formats (@inputfileref{input/test,to-xml.ly}) - -@seealso - -@file{scm/music-functions.scm}, @file{scm/music-types.scm}, -@inputfileref{input/test,add-staccato.ly}, -@inputfileref{input/test,unfold-all-repeats.ly}, and -@inputfileref{input/test,music-box.ly}. - -@node Lexical details -@section Lexical details - - -@cindex string -@cindex concatenate - -By enclosing text in quotes (@code{"}), strings are formed. To -include a @code{"} character in a string write @code{\"}. Various -other backslash sequences have special interpretations as in the C -language. A string that does not contain spaces or special characters -can be written without the quotes. The exact form of such unquoted -strings depends on the input mode; there are different rules for -lyrics, notes and markups. Strings can be concatenated with the -@code{+} operator. - - -@node Output details -@section Output details - -The default output format is La@TeX{}, which should be run -through La@TeX{}. Using the option @option{-f} -(or @option{--format}) other output formats can be selected also, but -currently none of them work reliably. - -At the beginning of the output file, various global parameters are -defined. Then the file @file{lilyponddefs.tex} is loaded to define -the macros used in the code which follows. @file{lilyponddefs.tex} -includes various other files, partially depending on the global -parameters. - -Now the music is output system by system (a `system' consists of all -staves belonging together). From @TeX{}'s point of view, a system is an -@code{\hbox} which contains a lowered @code{\vbox} so that it is centered -vertically on the baseline of the text. Between systems, -@code{\interscoreline} is inserted vertically to have stretchable space. -The horizontal dimension of the @code{\hbox} is given by the -@code{linewidth} parameter from LilyPond's @code{\paper} block. - -After the last system LilyPond emits a stronger variant of -@code{\interscoreline} only if the macro -@code{\lilypondpaperlastpagefill} is not defined (flushing the systems -to the top of the page). You can avoid that by setting the variable -@code{lastpagefill} in LilyPond's @code{\paper} block. - -It is possible to fine-tune the vertical offset further by defining the -macro @code{\lilypondscoreshift}: - -@example -\def\lilypondscoreshift@{0.25\baselineskip@} -@end example - -@noindent -where @code{\baselineskip} is the distance from one text line to the next. - -Here an example how to embed a small LilyPond file @code{foo.ly} into -running La@TeX{} text without using the @code{lilypond-book} script -(@pxref{lilypond-book manual}): - -@example -\documentclass@{article@} - -\def\lilypondpaperlastpagefill@{@} -\lineskip 5pt -\def\lilypondscoreshift@{0.25\baselineskip@} - -\begin@{document@} -This is running text which includes an example music file -\input@{foo.tex@} -right here. -\end@{document@} -@end example - -The file @file{foo.tex} has been simply produced with - -@example - lilypond-bin foo.ly -@end example - -The call to @code{\lineskip} assures that there is enough vertical space -between the LilyPond box and the surrounding text lines. - -@c EOF diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely index 63d11155e3..ccf6611e67 100644 --- a/Documentation/user/introduction.itely +++ b/Documentation/user/introduction.itely @@ -644,10 +644,9 @@ The @ifhtml The @end ifhtml -@emph{@ref{Technical manual}} +@emph{@ref{Changing defaults}} @c -discusses the general design of the program, and how to extend its -functionality. +Explains how to fine tune layout. @item @ifhtml The chapter diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi index 0e0b88ba94..1b3b612bc6 100644 --- a/Documentation/user/invoking.itexi +++ b/Documentation/user/invoking.itexi @@ -410,6 +410,7 @@ be skipped. Something is definitely wrong, and LilyPond cannot continue. This happens rarely. The most usual cause is misinstalled fonts. +@cindex trace, Scheme @cindex call trace @cindex Scheme error @item Scheme error diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely index 8a187a9b08..7c6ecbe512 100644 --- a/Documentation/user/lilypond.tely +++ b/Documentation/user/lilypond.tely @@ -149,13 +149,14 @@ this and other documentation. * Tutorial:: A tutorial introduction. * Notation manual:: All notation supported, and how to produce it. -* Using LilyPond:: How it all works. -* Technical manual:: How it all works. +* Changing defaults:: Tuning output * Invoking LilyPond:: Operation. * Converting from other formats:: Converting to lilypond source format. * lilypond-book manual:: Integrating text and music with lilypond-book. * Unified index:: -* Reference manual details:: +* Notation manual details:: +* Literature list:: +* Interfaces for programmers:: * Cheat sheet:: * GNU Free Documentation License:: FDL. @end menu @@ -168,9 +169,8 @@ this and other documentation. @include preface.itely @include introduction.itely @include tutorial.itely -@include refman.itely -@include running.itely -@include internals.itely +@include notation.itely +@include changing-defaults.itely @include invoking.itexi @include lilypond-book.itely @include converters.itely @@ -182,8 +182,14 @@ this and other documentation. @printindex cp -@include appendices.itely +@include notation-appendices.itely + +@include literature.itely + +@include programming-interface.itely + @include cheatsheet.itely + @include fdl.itexi @bye diff --git a/Documentation/user/literature.itely b/Documentation/user/literature.itely index 9c9e938c7e..76eca96d05 100644 --- a/Documentation/user/literature.itely +++ b/Documentation/user/literature.itely @@ -1,5 +1,5 @@ @node Literature list -@section Literature list +@appendix Literature list If you need to know more about music notation, here are some interesting titles to read. The source archive includes a more diff --git a/Documentation/user/music-glossary.tely b/Documentation/user/music-glossary.tely index c52bf5b2e5..369a2b7b06 100644 --- a/Documentation/user/music-glossary.tely +++ b/Documentation/user/music-glossary.tely @@ -944,7 +944,7 @@ also the contrapunctal technique used in the @emph{fugue} which, since the music of the baroque era, has been one of the most popular polyphonic composition methods. -@lilypond[staffsize=11,noquote] +@lilypond[staffsize=11] \override Score.TimeSignature #'style =\turnOff \notes\context PianoStaff << \context Staff = SA \relative c' { diff --git a/Documentation/user/appendices.itely b/Documentation/user/notation-appendices.itely similarity index 83% rename from Documentation/user/appendices.itely rename to Documentation/user/notation-appendices.itely index a70d26fb45..a52168b642 100644 --- a/Documentation/user/appendices.itely +++ b/Documentation/user/notation-appendices.itely @@ -1,25 +1,23 @@ -@node Reference manual details -@appendix Reference manual details +@node Notation manual details +@appendix Notation manual details @menu -* Chord name chart:: -* MIDI instruments:: -* The Feta font:: -* Scheme functions:: -* Layout property overview:: -* Context property overview:: -* Literature list:: +* Chord name chart:: +* MIDI instruments:: +* The Feta font:: +* All context properties:: +* Layout properties:: @end menu @node Chord name chart -@section Chord name chart +@appendixsec Chord name chart @lilypondfile{chord-names-jazz.ly} @node MIDI instruments -@section MIDI instruments +@appendixsec MIDI instruments @example "acoustic grand" "contrabass" "lead 7 (fifths)" @@ -40,7 +38,7 @@ "dulcimer" "tuba" "fx 6 (goblins)" "drawbar organ" "muted trumpet" "fx 7 (echoes)" "percussive organ" "french horn" "fx 8 (sci-fi)" -"rock organ" "brass section" "sitar" +"rock organ" "brass appendixsection" "sitar" "church organ" "synthbrass 1" "banjo" "reed organ" "synthbrass 2" "shamisen" "accordion" "soprano sax" "koto" @@ -68,10 +66,11 @@ @end example @node The Feta font -@section The Feta font +@appendixsec The Feta font + The following symbols are available in the Feta font and may be -accessed directly using text markup such as -@code{g^\markup @{ \musicglyph #"scripts-segno" @}}, see @ref{Text markup}. +accessed directly using text markup such as @code{g^\markup @{ +\musicglyph #"scripts-segno" @}}, see @ref{Text markup}. @lilypondfile[noindent]{feta16list.ly} @@ -80,10 +79,15 @@ accessed directly using text markup such as @lilypondfile[noindent]{parmesan16list.ly} -@include scheme-functions.tely + +@node All context properties +@appendixsec All context properties @include context-properties.tely + +@node Layout properties +@appendixsec Layout properties + @include layout-properties.tely -@include literature.itely diff --git a/Documentation/user/refman.itely b/Documentation/user/notation.itely similarity index 98% rename from Documentation/user/refman.itely rename to Documentation/user/notation.itely index 10a03b6afa..670e3047e3 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/notation.itely @@ -4,9 +4,6 @@ @c A menu is needed before every deeper *section nesting of @node's; run @c M-x texinfo-all-menus-update @c to automatically fill in these menus before saving changes -@c -@c FIXME: singular vs. plural: Beams/Beam - @node Notation manual @chapter Notation manual @@ -33,6 +30,7 @@ somewhat familiar with using LilyPond. * Ancient notation:: * Contemporary notation:: * Special notation:: +* Sound:: @end menu @c FIXME: Note entry vs Music entry at top level menu is confusing. @@ -1504,7 +1502,7 @@ In the example below, the autobeamer makes eight beams and sixteenth end at 3 eights; the third beam can only be corrected by specifying manual beaming. -@lilypond[raggedright,fragment,relative,noverbatim] +@lilypond[raggedright,fragment,relative] #(override-auto-beam-setting '(end * * * *) 3 8) % rather show case where it goes wrong %\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4 @@ -4654,7 +4652,7 @@ added clarinet voice. Quotations take into account the transposition both source and target instruments, if they are specified using the @code{\transposition} command. -@lilypond[verbatim fragment] +@lilypond[verbatim,fragment] \addquote clarinet \notes\relative c' { \transposition bes f4 fis g gis @@ -4682,10 +4680,6 @@ Examples: @inputfileref{input/regression,quote.ly} Internals: @internalsref{QuoteMusic}. - - - - @node Ancient notation @section Ancient notation @@ -7375,6 +7369,7 @@ entering the chant, as the following short excerpt demonstrates: } @end lilypond + @node Contemporary notation @section Contemporary notation @@ -7570,3 +7565,84 @@ If you view the result with Xdvi, then staff lines may show through the letters. Printing the PostScript file obtained does produce the correct result. + +@node Sound +@section Sound +@cindex Sound + +Entered music can also be converted to MIDI output. The performance +is good enough for proof-hearing the music for errors. + +Ties, dynamics and tempo changes are interpreted. Dynamic marks, +crescendi and decrescendi translate into MIDI volume levels. Dynamic +marks translate to a fixed fraction of the available MIDI volume +range, crescendi and decrescendi make the volume vary linearly between +their two extremities. The fractions can be adjusted by +@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context. +For each type of MIDI instrument, a volume range can be defined. This +gives a basic equalizer control, which can enhance the quality of +the MIDI output remarkably. The equalizer can be controlled by +setting @code{instrumentEqualizer}. + +@refbugs + +Many musically interesting effects, such as swing, articulation, +slurring, etc., are not translated to MIDI. + +The MIDI output allocates a channel for each Staff, and one for global +settings. Hence, the MIDI file should not have more than 15 staves +(or 14 if you do not use drums). + + +@menu +* MIDI block:: +* MIDI instrument names:: +@end menu + + +@node MIDI block +@subsection MIDI block +@cindex MIDI block + + +The MIDI block is analogous to the paper block, but it is somewhat +simpler. The @code{\midi} block can contain: +@cindex MIDI block + +@itemize @bullet + @item a @code{\tempo} definition, and + @item context definitions. +@end itemize + +Assignments in the @code{\midi} block are not allowed. + +A number followed by a period is interpreted as a real number, so +for setting the tempo for dotted notes, an extra space should be +inserted, for example: + +@example + \midi @{ \tempo 4 . = 120 @} +@end example + + +@cindex context definition + +Context definitions follow precisely the same syntax as within the +\paper block. Translation modules for sound are called performers. +The contexts for MIDI output are defined in @file{ly/performer-init.ly}. + + +@node MIDI instrument names +@subsection MIDI instrument names + +@cindex instrument names +@cindex @code{Staff.midiInstrument} + +The MIDI instrument name is set by the @code{Staff.midiInstrument} +property. The instrument name should be chosen from the list in +@ref{MIDI instruments}. + +@refbugs + +If the selected string does not exactly match, then the default is +used, which is the Grand Piano. diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely new file mode 100644 index 0000000000..ff923a66c6 --- /dev/null +++ b/Documentation/user/programming-interface.itely @@ -0,0 +1,510 @@ +@node Interfaces for programmers +@appendix Interfaces for programmers + + + +@menu +* Programmer interfaces for input :: +* Markup programmer interface:: +* Contexts for programmers:: +@end menu + +@node Programmer interfaces for input +@appendixsec Programmer interfaces for input + +@menu +* Input variables and Scheme:: +* Internal music representation:: +* Manipulating music expressions:: +@end menu + +@node Input variables and Scheme +@appendixsubsec Input variables and Scheme + + +The input format supports the notion of variable: in the following +example, a music expression is assigned to a variable with the name +@code{traLaLa}. +@example + traLaLa = \notes @{ c'4 d'4 @} +@end example + +@noindent + +There is also a form of scoping: in the following example, the +@code{\paper} block also contains a @code{traLaLa} variable, which is +independent of the outer @code{\traLaLa}. +@example + traLaLa = \notes @{ c'4 d'4 @} + \paper @{ traLaLa = 1.0 @} +@end example +@c +In effect, each input file is a scope, and all @code{\header}, +@code{\midi} and @code{\paper} blocks are scopes nested inside that +toplevel scope. + +Both variables and scoping are implemented in the GUILE module system. +An anonymous Scheme module is attached to each scope. An assignment of +the form +@example + traLaLa = \notes @{ c'4 d'4 @} +@end example + +@noindent +is internally converted to a Scheme definition +@example + (define traLaLa @var{Scheme value of ``@code{\notes ... }''}) +@end example + +This means that input variables and Scheme variables may be freely +mixed. In the following example, a music fragment is stored in the +variable @code{traLaLa}, and duplicated using Scheme. The result is +imported in a @code{\score} by means of a second variable +@code{twice}: +@example + traLaLa = \notes @{ c'4 d'4 @} + + #(define newLa (map ly:music-deep-copy + (list traLaLa traLaLa))) + #(define twice + (make-sequential-music newLa)) + + \score @{ \twice @} +@end example + +In the above example, music expressions can be `exported' from the +input to the Scheme interpreter. The opposite is also possible. By +wrapping a Scheme value in the function @code{ly:export}, a Scheme +value is interpreted as if it were entered in LilyPond syntax: instead +of defining @code{\twice}, the example above could also have been +written as +@example + @dots{} + \score @{ #(ly:export (make-sequential-music newLa)) @} +@end example + + +@node Internal music representation +@appendixsubsec Internal music representation + +When a music expression is parsed, it is converted into a set of +Scheme music objects. The defining property of a music object is that +it takes up time. Time is a rational number that measures the length +of a piece of music, in whole notes. + +A music object has three kinds of types: +@itemize @bullet +@item + music name: Each music expression has a name, for example, a note +leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to +a @internalsref{SimultaneousMusic}. A list of all expressions +available is in the internals manual, under @internalsref{Music +expressions}. + +@item + `type' or interface: Each music name has several `types' or interface, + for example, a note is an @code{event}, but it is also a @code{note-event}, + a @code{rhythmic-event} and a @code{melodic-event}. + + All classes of music are listed in the internals manual, under + @internalsref{Music classes}. +@item +C++ object: Each music object is represented by a C++ object. For technical +reasons, different music objects may be represented by different C++ +object types. For example, a note is @code{Event} object, while +@code{\grace} creates a @code{Grace_music} object. + +We expect that distinctions between different C++ types will disappear +in the future. +@end itemize + +The actual information of a music expression is stored in properties. +For example, a @internalsref{NoteEvent} has @code{pitch} and +@code{duration} properties that store the pitch and duration of that +note. A list of all properties available is in the internals manual, +under @internalsref{Music properties}. + +A compound music expression is a music object that contains other +music objects in its properties. A list of objects can be stored in +the @code{elements} property of a music object, or a single `child' +music object in the @code{element} object. For example, +@internalsref{SequentialMusic} has its children in @code{elements}, +and @internalsref{GraceMusic} has its single argument in +@code{element}. The body of a repeat is in @code{element} property of +@internalsref{RepeatedMusic}, and the alternatives in @code{elements}. + +@node Manipulating music expressions +@appendixsubsec Manipulating music expressions + +Music objects and their properties can be accessed and manipulated +directly, through the @code{\apply} mechanism. +The syntax for @code{\apply} is +@example +\apply #@var{func} @var{music} +@end example + +@noindent +This means that the scheme function @var{func} is called with +@var{music} as its argument. The return value of @var{func} is the +result of the entire expression. @var{func} may read and write music +properties using the functions @code{ly:music-property} and +@code{ly:music-set-property!}. + +An example is a function that reverses the order of elements in +its argument: +@lilypond[verbatim,raggedright] + #(define (rev-music-1 m) + (ly:music-set-property! m 'elements (reverse + (ly:music-property m 'elements))) + m) + \score { \notes \apply #rev-music-1 { c4 d4 } } +@end lilypond + +The use of such a function is very limited. The effect of this +function is void when applied to an argument which is does not have +multiple children. The following function application has no effect: + +@example + \apply #rev-music-1 \grace @{ c4 d4 @} +@end example + +@noindent +In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no +@code{elements}, only a single @code{element}. Every generally +applicable function for @code{\apply} must -- like music expressions +themselves -- be recursive. + +The following example is such a recursive function: It first extracts +the @code{elements} of an expression, reverses them and puts them +back. Then it recurses, both on @code{elements} and @code{element} +children. +@example +#(define (reverse-music music) + (let* ((elements (ly:music-property music 'elements)) + (child (ly:music-property music 'element)) + (reversed (reverse elements))) + + ; set children + (ly:music-set-property! music 'elements reversed) + + ; recurse + (if (ly:music? child) (reverse-music child)) + (map reverse-music reversed) + + music)) +@end example + +A slightly more elaborate example is in +@inputfileref{input/test,reverse-music.ly}. + +Some of the input syntax is also implemented as recursive music +functions. For example, the syntax for polyphony +@example + <> +@end example + +@noindent +is actually implemented as a recursive function that replaces the +above by the internal equivalent of +@example + << \context Voice = "1" @{ \voiceOne a @} + \context Voice = "2" @{ \voiceTwo b @} >> +@end example + +Other applications of @code{\apply} are writing out repeats +automatically (@inputfileref{input/test,unfold-all-repeats.ly}), +saving keystrokes (@inputfileref{input/test,music-box.ly}) and +exporting +LilyPond input to other formats (@inputfileref{input/test,to-xml.ly}) + +@seealso + +@file{scm/music-functions.scm}, @file{scm/music-types.scm}, +@inputfileref{input/test,add-staccato.ly}, +@inputfileref{input/test,unfold-all-repeats.ly}, and +@inputfileref{input/test,music-box.ly}. + + + +@node Markup programmer interface +@appendixsec Markup programmer interface + + +@menu +* Markup construction in scheme:: +* Markup command definition:: +@end menu + +@node Markup construction in scheme +@appendixsubsec Markup construction in scheme + +@cindex defining markup commands + +The @code{markup} macro builds markup expressions in Scheme while +providing a LilyPond-like syntax. For example, +@example +(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world") + #:bigger #:line ("foo" "bar" "baz"))) +@end example + +@noindent +is equivalent to: +@example +\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @} + \bigger @{ foo bar baz @} > +@end example + +@noindent +This example exposes the main translation rules between regular +LilyPond markup syntax and scheme markup syntax, which are summed up +is this table: +@multitable @columnfractions .5 .5 +@item @b{LilyPond} @tab @b{Scheme} +@item @code{\command} @tab @code{#:command} +@item @code{\variable} @tab @code{variable} +@item @code{@{ ... @}} @tab @code{#:line ( ... )} +@item @code{\center-align < ... >} @tab @code{#:center ( ... )} +@item @code{string} @tab @code{"string"} +@item @code{#scheme-arg} @tab @code{scheme-arg} +@end multitable + +Besides, the whole scheme language is accessible inside the +@code{markup} macro: thus, one may use function calls inside +@code{markup} in order to manipulate character strings for +instance. This proves useful when defining new markup commands (see +@ref{Markup command definition}). + +@refbugs + +One can not feed the @code{#:line} (resp @code{#:center}, +@code{#:column}) command with a variable or the result of a function +call. Eg: +@lisp +(markup #:line (fun-that-returns-markups)) +@end lisp +is illegal. One should use the @code{make-line-markup} (resp +@code{make-center-markup}, @code{make-column-markup}) function +instead: +@lisp +(markup (make-line-markup (fun-that-returns-markups))) +@end lisp + +@node Markup command definition +@appendixsubsec Markup command definition + +New markup commands can be defined thanks to the @code{def-markup-command} scheme macro. +@lisp +(def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...) + (@var{arg1-type?} @var{arg2-type?} ...) + ..command body..) + + @var{argi}: i@var{th} command argument + @var{argi-type?}: a type predicate for the i@var{th} argument + @var{paper}: the `paper' definition + @var{props}: a list of alists, containing all active properties. +@end lisp + +As a simple example, we show how to add a @code{\smallcaps} command, +which selects @TeX{}'s small caps font. Normally, we could select the +small caps font as follows: + +@verbatim + \markup { \override #'(font-shape . caps) Text-in-caps } +@end verbatim + +This selects the caps font by setting the @code{font-shape} property to +@code{#'caps} for interpreting @code{Text-in-caps}. + +To make the above available as @code{\smallcaps} command, we have to +define a function using @code{def-markup-command}. The command should +take a single argument, of markup type. Therefore, the start of the +definition should read +@example + (def-markup-command (smallcaps paper props argument) (markup?) +@end example + +@noindent + +What follows is the content of the command: we should interpret +the @code{argument} as a markup, i.e. + +@example + (interpret-markup paper @dots{} argument) +@end example + +@noindent +This interpretation should add @code{'(font-shape . caps)} to the active +properties, so we substitute the the following for the @dots{} in the +above example: + +@example + (cons (list '(font-shape . caps) ) props) +@end example + +@noindent +The variable @code{props} is a list of alists, and we prepend to it by +consing a list with the extra setting. + +However, suppose that we are using a font that does not have a +small-caps variant. In that case, we have to fake the small caps font, +by setting a string in upcase, with the first letter a little larger: + +@example +#(def-markup-command (smallcaps paper props str) (string?) + "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" + (interpret-markup paper props + (make-line-markup + (map (lambda (s) + (if (= (string-length s) 0) + s + (markup #:large (string-upcase (substring s 0 1)) + #:translate (cons -0.6 0) + #:tiny (string-upcase (substring s 1))))) + (string-split str #\Space))))) +@end example + +The @code{smallcaps} command first splits its string argument into +tokens separated by spaces (@code{(string-split str #\Space)}); for +each token, a markup is built with the first letter made large and +upcased (@code{#:large (string-upcase (substring s 0 1))}), and a +second markup built with the following letters made tiny and upcased +(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond +introduces a space between markups on a line, the second markup is +translated to the left (@code{#:translate (cons -0.6 0) ...}). Then, +the markups built for each token are put in a line +(@code{(make-line-markup ...)}). Finally, the resulting markup is +passed to the @code{interpret-markup} function, with the @code{paper} +and @code{props} arguments. + +Finally, suppose that we are typesetting a recitative in an opera, and +we would like to define a command that will show character names in a +custom manner. Names should be printed with small caps and translated a +bit to the left and top. We will define a @code{\character} command +that takes into account the needed translation, and uses the newly +defined @code{\smallcaps} command: + +@verbatim +#(def-markup-command (character paper props name) (string?) + "Print the character name in small caps, translated to the left and + top. Syntax: \\character #\"name\"" + (interpret-markup paper props + (markup "" #:translate (cons -4 2) #:smallcaps name))) +@end verbatim + +There is one complication that needs explanation: texts above and below +the staff are moved vertically to be at a certain distance (the +@code{padding} property) from the staff and the notes. To make sure +that this mechanism does not annihilate the vertical effect of our +@code{#:translate}, we add an empty string (@code{""}) before the +translated text. Now the @code{""} will be put above the notes, and the +@code{name} is moved in relation to that empty string. The net effect is +that the text is moved to the upper left. + +The final result is as follows: +@verbatim +\score { + \notes { \fatText + c''^\markup \character #"Cleopatra" + e'^\markup \character #"Giulio Cesare" + } +} +@end verbatim + +@lilypond[raggedright] +#(def-markup-command (smallcaps paper props str) (string?) + "Print the string argument in small caps. Syntax: \\smallcaps #\"string\"" + (interpret-markup paper props + (make-line-markup + (map (lambda (s) + (if (= (string-length s) 0) + s + (markup #:large (string-upcase (substring s 0 1)) + #:translate (cons -0.6 0) + #:tiny (string-upcase (substring s 1))))) + (string-split str #\Space))))) + +#(def-markup-command (character paper props name) (string?) + "Print the character name in small caps, translated to the left and + top. Syntax: \\character #\"name\"" + (interpret-markup paper props + (markup "" #:translate (cons -4 0) #:smallcaps name))) + +\score { + \notes { \fatText + c''^\markup \character #"Cleopatra" + e'^\markup \character #"Giulio Cesare" + } +} +@end lilypond + + + +@node Contexts for programmers +@appendixsec Contexts for programmers + + +@menu +* Context evaluation:: +* Applyoutput:: +@end menu + +@node Context evaluation +@appendixsubsec Context evaluation + +Contexts can be modified during interpretation with Scheme code. The +syntax for this is +@example + \applycontext @var{function} +@end example + +@var{function} should be a Scheme function taking a single argument, +being the context to apply it to. The following code will print the +current bar number on the standard output during the compile: + +@example + \applycontext + #(lambda (x) + (format #t "\nWe were called in barnumber ~a.\n" + (ly:context-property x 'currentBarNumber))) +@end example + + + +@node Applyoutput +@appendixsubsec Applyoutput + +The most versatile way of tuning an object is @code{\applyoutput}. Its +syntax is +@example +\applyoutput @var{proc} +@end example + +@noindent +where @var{proc} is a Scheme function, taking three arguments. + +When interpreted, the function @var{proc} is called for every layout +object found in the context, with the following arguments: +@itemize @bullet +@item the layout object itself, +@item the context where the layout object was created, and +@item the context where @code{\applyoutput} is processed. +@end itemize + + +In addition, the cause of the layout object, i.e. the music +expression or object that was responsible for creating it, is in the +object property @code{cause}. For example, for a note head, this is a +@internalsref{NoteHead} event, and for a @internalsref{Stem} object, +this is a @internalsref{NoteHead} object. + +Here is a simple example of @code{\applyoutput}; it blanks note-heads on the +center-line: +@example +(define (blanker grob grob-origin context) + (if (and (memq (ly:grob-property grob 'interfaces) + note-head-interface) + (eq? (ly:grob-property grob 'staff-position) 0)) + + (ly:grob-set-property! grob 'transparent #t))) +@end example + diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 4a03f90ef9..0f47b487d0 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -808,8 +808,8 @@ braces at the end of an expression. For example, @end example -For more information on context see the Technical manual description -in @ref{Interpretation context}. +For more information on context see the description in +@ref{Interpretation context}. diff --git a/make/lilypond.redhat.spec.in b/make/lilypond.redhat.spec.in index 39e9e88827..503b362073 100644 --- a/make/lilypond.redhat.spec.in +++ b/make/lilypond.redhat.spec.in @@ -107,7 +107,7 @@ fi /sbin/install-info --delete %{_infodir}/music-glossary.info.gz %{_infodir}/dir %endif -# chkfontpath --remove=%{_datadir}/share/lilypond/@TOPLEVEL_VERSION@/fonts/type1/ +# chkfontpath --remove=%{_datadir}/share/lilypond/@TOPLEVEL_VERSION@/fonts/type1n/ %postun @@ -144,7 +144,7 @@ scrollkeeper-update %doc NEWS.txt %if %{info} -%{_infodir}/* +%{_infodir}/lilypond/ %endif %{_mandir}/man1/abc2ly.1.gz diff --git a/scm/define-markup-commands.scm b/scm/define-markup-commands.scm index d4b0a3f7f3..3b1e6d1183 100644 --- a/scm/define-markup-commands.scm +++ b/scm/define-markup-commands.scm @@ -263,7 +263,7 @@ letter 'A'." This raises @var{arg}, by the distance @var{amount}. A negative @var{amount} indicates lowering: @c -@lilypond[verbatim,fragment,relative=1,quote] +@lilypond[verbatim,fragment,relative=1] c1^\\markup { C \\small \\raise #1.0 \\bold { \"9/7+\" }} @end lilypond The argument to @code{\\raise} is the vertical displacement amount, diff --git a/scm/documentation-generate.scm b/scm/documentation-generate.scm index 6062aae507..8c47ee1021 100644 --- a/scm/documentation-generate.scm +++ b/scm/documentation-generate.scm @@ -28,55 +28,24 @@ )) (map ly:load load-files) - -;;(define no-copies #t) ; from 490 to 410K, but doesn't look nice yet -;; -;; Also, copies of interfaces use up lots more space, but that's -;; functional because the default property values of the interfaces -;; are described... -(define no-copies #f) - - - - - - - - - - - - ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(dump-node (all-scheme-functions-doc) - (open-output-file "scheme-functions.tely") - 2) +(display + (slot-ref (all-scheme-functions-doc) 'text) + (open-output-file "scheme-functions.tely")) (display (markup-doc-string) + (open-output-file "markup-commands.tely")) - (open-output-file "markup-commands.tely") - ) -(dump-node - (make - #:name "Layout property overview" - #:desc "All user serviceable layout properties" - #:text (backend-properties-doc-string all-user-grob-properties)) - - (open-output-file "layout-properties.tely") - 2) - -(dump-node - (make - #:name "Context property overview" - #:desc "All user serviceable context properties" - #:text (translation-properties-doc-string all-user-translation-properties)) - - (open-output-file "context-properties.tely") - 2) +(display + (backend-properties-doc-string all-user-grob-properties) + (open-output-file "layout-properties.tely") ) +(display + (translation-properties-doc-string all-user-translation-properties) + (open-output-file "context-properties.tely") ) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; diff --git a/scm/new-markup.scm b/scm/new-markup.scm index a4174f94e0..b3f3d6d046 100644 --- a/scm/new-markup.scm +++ b/scm/new-markup.scm @@ -214,6 +214,43 @@ eg (make-COMMAND-markup arg1 arg2 ...), and the rest expression." (values (cons 'list (compile-all-markup-args (car expr))) (cdr expr))) (else (values (car expr) (cdr expr))))) +;;;;;;;;;;;;;;; +;;; Debugging utilities: print markup expressions in a friendly fashion + +(use-modules (ice-9 format)) +(define (markup->string markup-expr) + "Return a string describing, in LilyPond syntax, the given markup expression." + (define (proc->command proc) + (let ((cmd-markup (symbol->string (procedure-name proc)))) + (substring cmd-markup 0 (- (string-length cmd-markup) + (string-length "-markup"))))) + (define (arg->string arg) + (cond ((and (pair? arg) (pair? (car arg))) ;; markup list + (format #f "~{ ~a~}" (map markup->string arg))) + ((pair? arg) ;; markup + (markup->string arg)) + ((string? arg) ;; scheme string argument + (format #f "#\"~a\"" arg)) + (else ;; other scheme arg + (format #f "#~a" arg)))) + (let ((cmd (car markup-expr)) + (args (cdr markup-expr))) + (cond ((eqv? cmd simple-markup) ;; a simple string + (format #f "\"~a\"" (car args))) + ((eqv? cmd line-markup) ;; { ... } + (format #f "{~a}" (arg->string (car args)))) + ((eqv? cmd center-align-markup) ;; \center < ... > + (format #f "\\center-align <~a>" (arg->string (car args)))) + ((eqv? cmd column-markup) ;; \column < ... > + (format #f "\\column <~a>" (arg->string (car args)))) + (else ;; \command ... + (format #f "\\~a~{ ~a~} " (proc->command cmd) (map arg->string args)))))) + +(define-public (display-markup markup-expr) + "Print a LilyPond-syntax equivalent for the given markup expression." + (display "\\markup ") + (display (markup->string markup-expr))) + ;;;;;;;;;;;;;;; ;;; Utilities for storing and accessing markup commands signature ;;; and keyword. -- 2.39.5