X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fprogramming-interface.itely;h=e26293b43feb9b7cc8e32f22b75fbe0c9be59b89;hb=555d8e498a31380d62be9f4853ab514b3786e986;hp=b64f0d87d126bf555d71b616d345a850739fba9c;hpb=16c174dd8fc82d6fdde10af1077cc3e0bfc08b22;p=lilypond.git diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely index b64f0d87d1..e26293b43f 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:: @@ -83,7 +83,7 @@ The @code{parser} and @code{location} argument are mandatory, 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. @@ -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 @} @@ -333,7 +333,7 @@ traLaLa = @{ c'4 d'4 @} @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 @@ -359,12 +359,12 @@ 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. -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. @@ -377,7 +377,7 @@ been written as 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) @@ -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,7 +404,7 @@ 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 @@ -413,7 +413,7 @@ available is in the Program reference manual, under @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 @@ -433,7 +433,7 @@ 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' +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 @@ -589,7 +589,7 @@ d' @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. @@ -628,7 +628,7 @@ 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, @@ -766,12 +766,12 @@ necessary, but just like clear variable names, it is good practice. (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 @@ -785,8 +785,8 @@ add the marcato to its elements list property. (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) @@ -796,7 +796,7 @@ Here, what we want to set (the "place") is the "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 @@ -805,12 +805,12 @@ former elements property, with an extra item: the (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. -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 @@ -969,7 +970,7 @@ The arguments are @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 @@ -1111,9 +1112,59 @@ to the @code{interpret-markup} function, with the @code{layout} and 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 @@ -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