X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fprogramming-interface.itely;h=2783c79a6a1956b7f478b1d51cbc32f33bf80f07;hb=a51d465d74f8b918c2a92f7676d1154a7f7d622c;hp=e55d26471bb677b0bbf0ceadd2b2346ccea27240;hpb=0afe76f729e557b06c8bdacabd3eb3ba8b9247df;p=lilypond.git diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely index e55d26471b..2783c79a6a 100644 --- a/Documentation/user/programming-interface.itely +++ b/Documentation/user/programming-interface.itely @@ -12,7 +12,7 @@ Advanced tweaks may be performed by using Scheme. If you are not familiar with Scheme, you may wish to read our -@ref{Scheme tutorial}. +@rlearning{Scheme tutorial}. @menu * Music functions:: @@ -230,7 +230,7 @@ turning off Point and Click). To do this, we return a @code{void} music expression. That is why the form -that is returned is the @code{(make-music ...)}. With the +that is returned is the @code{(make-music ...)}. With the @code{'void} property set to @code{#t}, the parser is told to actually disregard this returned music expression. Thus the important part of the void music function is the @@ -251,7 +251,7 @@ noPointAndClick = @subsection Functions without arguments In most cases a function without arguments should be written -with an identifier, +with an variable, @example dolce = \markup@{ \italic \bold dolce @} @@ -359,7 +359,7 @@ traLaLa = { c'4 d'4 } Due to parser lookahead In this example, the assignment happens after parser has verified that -nothing interesting happens after @code{traLaLa = @{ ... @}}. Without +nothing interesting happens after @code{traLaLa = @{ ... @}}. Without the dummy statement in the above example, the @code{newLa} definition is executed before @code{traLaLa} is defined, leading to a syntax error. @@ -391,7 +391,7 @@ define some Scheme code in a macro (to be called later), use @refbugs -Mixing Scheme and LilyPond identifiers is not possible with the +Mixing Scheme and LilyPond variables is not possible with the @code{--safe} option. @@ -404,12 +404,12 @@ 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 +@itemize @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 Program reference manual, under +available is in the Internals Reference manual, under @internalsref{Music expressions}. @item @@ -417,7 +417,7 @@ available is in the Program reference manual, under 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 -Program reference, under +Internals Reference, under @internalsref{Music classes}. @item @@ -589,7 +589,7 @@ d' @subsection Doubling a note with slurs (example) Suppose we want to create a function which translates -input like @samp{a} into @samp{a( a)}. We begin +input like @code{a} into @code{a( a)}. We begin by examining the internal representation of the music we want to end up with. @@ -796,7 +796,7 @@ Here, what we want to set (the @q{place}) is the @q{elements} property of (the @code{'elements}, @code{'duration}, @code{'pitch}, etc, that we see in the @code{\displayMusic} output above). The new value is the former elements property, with an extra item: the -@code{MarcatoEvent} expression, which we copy from the +@code{ArticulationEvent} expression, which we copy from the @code{\displayMusic} output, @example @@ -810,7 +810,7 @@ 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. -Finally, once we have added the @code{MarcatoEvent} to its elements +Finally, once we have added the marcato articulation to its @code{elements} property, we can return @code{result-event-chord}, hence the last line of the function. @@ -847,6 +847,7 @@ Stencil object given a number of arguments. * Markup construction in Scheme:: * How markups work internally:: * New markup command definition:: +* New markup list command definition:: @end menu @@ -1114,6 +1115,56 @@ be used to set text in small caps. See @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 @@ -1168,7 +1219,7 @@ 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 @var{context}, with the following arguments: -@itemize @bullet +@itemize @item the layout object itself, @item the context where the layout object was created, and @item the context where @code{\applyOutput} is processed. @@ -1248,8 +1299,8 @@ can be inserted with a grob closure. Here is a setting from @noindent In this example, both @code{ly:self-alignment-interface::x-aligned-on-self} and @code{ly:self-alignment-interface::centered-on-x-parent} are called -with the grob as argument. The results are added with the @code{+} -function. To ensure that this addition is properly executed, the whole +with the grob as argument. The results are added with the @code{+} +function. To ensure that this addition is properly executed, the whole thing is enclosed in @code{ly:make-simple-closure}. In fact, using a single procedure as property value is equivalent to