@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
@node Interfaces for programmers
@chapter Interfaces for programmers
* Paired substitution functions::
* Mathematics in functions::
* Void functions::
+* Functions without arguments::
* Overview of available music functions::
@end menu
and are used in some advanced situations. The @code{parser}
argument is used to access to the value of another LilyPond
variable. The @code{location} argument
-is used to set the ``origin'' of the music expression that is built
+is used to set the @q{origin} of the music expression that is built
by the music function, so that in case of a syntax error LilyPond
can tell the user an appropriate place to look in the input file.
(number? string?)
#{
\once \override Score . RehearsalMark #'padding = $padding
- \once \override Score . RehearsalMark #'no-spacing-rods = ##t
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup { \bold $marktext }
#})
\noPointAndClick % disable point and click
@end example
+
+@node Functions without arguments
+@subsection Functions without arguments
+
+In most cases a function without arguments should be written
+with an identifier,
+
+@example
+dolce = \markup@{ \italic \bold dolce @}
+@end example
+
+However, in rare cases it may be useful to create a music function
+without arguments,
+
+@example
+displayBarNum =
+#(define-music-function (parser location) ()
+ (if (eq? #t (ly:get-option display-bar-numbers))
+ #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
+ #@{#@}))
+@end example
+
+To actually display bar numbers where this function is called,
+invoke lilypond with
+
+@example
+lilypond -d display-bar-numbers FILENAME.ly
+@end example
+
+
@node Overview of available music functions
@subsection Overview of available music functions
@noindent
is internally converted to a Scheme definition
@example
-(define traLaLa @var{Scheme value of ``@code{... }''})
+(define traLaLa @var{Scheme value of `@code{... }'})
@end example
This means that input variables and Scheme variables may be freely
is executed before @code{traLaLa} is defined, leading to a syntax
error.
-The above example shows how to `export' music expressions from the
+The above example shows how to @q{export} music expressions 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.
Scheme code is evaluated as soon as the parser encounters it. To
define some Scheme code in a macro (to be called later), use
-@ref{Void functions} or
+@ref{Void functions}, or
@example
#(define (nopc)
@internalsref{Music expressions}.
@item
-`type' or interface: Each music name has several `types' or
+@q{type} or interface: Each music name has several @q{types} or
interfaces, 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
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'
+the @code{elements} property of a music object, or a single @q{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
@subsection Doubling a note with slurs (example)
Suppose we want to create a function which translates
-input like ``@code{a}'' into ``@code{a( a)}''. We begin
+input like @samp{a} into @samp{a( a)}. We begin
by examining the internal representation of the music
we want to end up with.
@end example
The bad news is that the @code{SlurEvent} expressions
-must be added ``inside'' the note (or more precisely,
+must be added @q{inside} the note (or more precisely,
inside the @code{EventChord} expression).
Now we examine the input,
(let ((result-event-chord (ly:music-deep-copy event-chord)))
@end example
-`@code{let}' is used to declare local variables. Here we use one local
-variable, named `@code{result-event-chord}', to which we give the value
-@code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
+@code{let} is used to declare local variables. Here we use one local
+variable, named @code{result-event-chord}, to which we give the value
+@code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy} is
a function specific to LilyPond, like all functions prefixed by
-`@code{ly:}'. It is use to make a copy of a music
-expression. Here we copy `@code{event-chord} (the parameter of the
+@code{ly:}. It is use to make a copy of a music
+expression. Here we copy @code{event-chord} (the parameter of the
function). Recall that our purpose is to add a marcato to an
@code{EventChord} expression. It is better to not modify the
@code{EventChord} which was given as an argument, because it may be
(set! place new-value)
@end example
-Here, what we want to set (the "place") is the "elements" property of
-@code{result-event-chord} expression
+Here, what we want to set (the @q{place}) is the @q{elements} property of
+@code{result-event-chord} expression.
@example
(ly:music-property result-event-chord 'elements)
(ly:music-property result-event-chord 'elements))
@end example
-`@code{cons}' is used to add an element to a list without modifying the
+@code{cons} is used to add an element to a list without modifying the
original list. This is what we
want: the same list as before, plus the new @code{ArticulationEvent}
expression. The order inside the elements property is not important here.
* Markup construction in Scheme::
* How markups work internally::
* New markup command definition::
+* New markup list command definition::
@end menu
@item argi-type?
a type predicate for the i@var{th} argument
@item layout
-the `layout' definition
+the @q{layout} definition
@item props
a list of alists, containing all active properties.
@end table
Note: there is now an internal command @code{\smallCaps} which can
be used to set text in small caps. See
-@ref{Overview of text markup commands} for details.
+@ref{Overview of text markup commands}, for details.
+
+@node New markup list command definition
+@subsection New markup list command definition
+Markup list commands are defined with the
+@code{define-markup-list-command} Scheme macro, which is similar to the
+@code{define-markup-command} macro described in
+@ref{New markup command definition}, except that where the later returns
+a single stencil, the former returns a list stencils.
+In the following example, a @code{\paragraph} markup list command is
+defined, which returns a list of justified lines, the first one being
+indented. The indent width is taken from the @code{props} argument.
+@example
+#(define-markup-list-command (paragraph layout props args) (markup-list?)
+ (let ((indent (chain-assoc-get 'par-indent props 2)))
+ (interpret-markup-list layout props
+ (make-justified-lines-markup-list (cons (make-hspace-markup indent)
+ args)))))
+@end example
+
+Besides the usual @code{layout} and @code{props} arguments, the
+@code{paragraph} markup list command takes a markup list argument, named
+@code{args}. The predicate for markup lists is @code{markup-list?}.
+
+First, the function gets the indent width, a property here named
+@code{par-indent}, from the property list @code{props} If the property
+is not found, the default value is @code{2}. Then, a list of justified
+lines is made using the @code{make-justified-lines-markup-list}
+function, which is related to the @code{\justified-lines}
+built-in markup list command. An horizontal space is added at the
+begining using the @code{make-hspace-markup} function. Finally, the
+markup list is interpreted using the @code{interpret-markup-list}
+function.
+
+This new markup list command can be used as follows:
+@example
+\markuplines @{
+ \paragraph @{
+ The art of music typography is called \italic @{(plate) engraving.@}
+ The term derives from the traditional process of music printing.
+ Just a few decades ago, sheet music was made by cutting and stamping
+ the music into a zinc or pewter plate in mirror image.
+ @}
+ \override-lines #'(par-indent . 4) \paragraph @{
+ The plate would be inked, the depressions caused by the cutting
+ and stamping would hold ink. An image was formed by pressing paper
+ to the plate. The stamping and cutting was completely done by
+ hand.
+ @}
+@}
+@end example
@node Contexts for programmers
@section Contexts for programmers
projects / lilypond.git / blobdiff