X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fprogramming-interface.itely;h=4b0c523a71ec723dc59ede0f9822ece3bc57fa5d;hb=c10e42d15b978acf35c75671b16c618215be8215;hp=8b40fe3140c0d97a7504e935813989395414da7f;hpb=cfb0511f85f9691bfeebecaaaf962f7e0feb3ce0;p=lilypond.git

diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely
index 8b40fe3140..4b0c523a71 100644
--- a/Documentation/user/programming-interface.itely
+++ b/Documentation/user/programming-interface.itely
@@ -1,10 +1,20 @@
 @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
+
+@c \version "2.11.51"
+
 @node Interfaces for programmers
 @chapter Interfaces for programmers
 
 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::             
@@ -12,7 +22,8 @@ not familiar with Scheme, you may wish to read our
 * Building complicated functions::  
 * Markup programmer interface::  
 * Contexts for programmers::    
-* Scheme procedures as properties::
+* Scheme procedures as properties::  
+* TODO moved into scheme::      
 @end menu
 
 
@@ -27,6 +38,8 @@ This section discusses how to create music functions within LilyPond.
 * Paired substitution functions::  
 * Mathematics in functions::    
 * Void functions::              
+* Functions without arguments::  
+* Overview of available music functions::  
 @end menu
 
 @node Overview of music functions
@@ -73,7 +86,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.
 
@@ -122,7 +135,7 @@ tempoMark = #(define-music-function (parser location padding marktext)
                                     (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 }
 #})
 
@@ -220,7 +233,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
@@ -237,6 +250,45 @@ noPointAndClick =
 @end example
 
 
+@node Functions without arguments
+@subsection Functions without arguments
+
+In most cases a function without arguments should be written
+with an variable,
+
+@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 @command{lilypond} with
+
+@example
+lilypond -d display-bar-numbers FILENAME.ly
+@end example
+
+
+@node Overview of available music functions
+@subsection Overview of available music functions
+
+@c fixme ; this should be move somewhere else?
+The following commands are music functions
+
+@include identifiers.tely
+
+
+
 @node Programmer interfaces
 @section Programmer interfaces
 
@@ -284,7 +336,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
@@ -292,23 +344,35 @@ 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} block by means of a second variable
 @code{twice}:
-@example
-traLaLa = @{ c'4 d'4 @}
+
+@lilypond[verbatim]
+traLaLa = { c'4 d'4 }
+
+%% dummy action to deal with parser lookahead
+#(display "this needs to be here, sorry!")
 
 #(define newLa (map ly:music-deep-copy
   (list traLaLa traLaLa)))
 #(define twice
   (make-sequential-music newLa))
 
-@{ \twice @}
-@end example
+{ \twice }
+@end lilypond
+
+Due to parser lookahead
 
-In the above example, music expressions can be `exported' from the
+In this example, the assignment happens after parser has verified that
+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 @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.  Instead
-of defining @code{\twice}, the example above could also have been
-written as
+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{}
 @{ #(ly:export (make-sequential-music (list newLa))) @}
@@ -316,7 +380,7 @@ 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)
@@ -328,9 +392,9 @@ define some Scheme code in a macro (to be called later), use
 @end example
 
 
-@refbugs
+@knownissues
 
-Mixing Scheme and LilyPond identifiers is not possible with the
+Mixing Scheme and LilyPond variables is not possible with the
 @code{--safe} option.
 
 
@@ -343,21 +407,21 @@ 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
-@internalsref{Music expressions}.
+leads to a @rinternals{NoteEvent}, and @code{\simultaneous} leads to
+a @rinternals{SimultaneousMusic}.  A list of all expressions
+available is in the Internals Reference manual, under
+@rinternals{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
-Program reference, under
-@internalsref{Music classes}.
+Internals Reference, under
+@rinternals{Music classes}.
 
 @item
 C++ object: Each music object is represented by an object of the C++
@@ -365,19 +429,19 @@ class @code{Music}.
 @end itemize
 
 The actual information of a music expression is stored in properties.
-For example, a @internalsref{NoteEvent} has @code{pitch} and
+For example, a @rinternals{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}.
+under @rinternals{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
+@rinternals{SequentialMusic} has its children in @code{elements},
+and @rinternals{GraceMusic} has its single argument in
 @code{element}.  The body of a repeat is stored in the @code{element}
-property of @internalsref{RepeatedMusic}, and the alternatives in
+property of @rinternals{RepeatedMusic}, and the alternatives in
 @code{elements}.
 
 
@@ -528,7 +592,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 @code{a} into @code{a( a)}.  We begin
 by examining the internal representation of the music
 we want to end up with.
 
@@ -567,7 +631,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,
@@ -593,7 +657,7 @@ have two notes to build the sequence), add @code{SlurEvents} to the
 @code{SequentialMusic} with the two @code{EventChords}.
 
 @example
-doubleSlur = #(def-music-function (parser location note) (ly:music?)
+doubleSlur = #(define-music-function (parser location note) (ly:music?)
          "Return: @{ note ( note ) @}.
          `note' is supposed to be an EventChord."
          (let ((note2 (ly:music-deep-copy note)))
@@ -705,12 +769,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
@@ -724,8 +788,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)
@@ -735,7 +799,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
@@ -744,12 +808,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.
 
@@ -786,6 +850,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
 
 
@@ -833,7 +898,7 @@ useful when defining new markup commands (see
 @ref{New markup command definition}).
 
 
-@refbugs
+@knownissues
 
 The markup-list argument of commands such as @code{#:line},
 @code{#:center}, and @code{#:column} cannot be a variable or
@@ -908,7 +973,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
@@ -1050,9 +1115,105 @@ 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{Text markup commands}, for details.
+
+@knownissues
+
+Currently, the available combinations of arguments (after the standard
+@var{layout} and @var{props} arguments) to a markup command defined with
+@code{define-markup-command} are limited as follows.
+
+@table @asis
+@item (no argument)
+@itemx @var{list}
+@itemx @var{markup}
+@itemx @var{markup markup}
+@itemx @var{scm}
+@itemx @var{scm markup}
+@itemx @var{scm scm}
+@itemx @var{scm scm markup}
+@itemx @var{scm markup markup}
+@itemx @var{scm scm scm}
+@end table
+
+@noindent
+In the above table, @var{scm} represents native Scheme data types like
+@q{number} or @q{string}.
+
+As an example, it is not possible to use a markup command @code{foo} with
+four arguments defined as
+
+@example
+#(define-markup-command (foo layout props
+                         num1    str1    num2    str2)
+                        (number? string? number? string?)
+  ...)
+@end example
+
+@noindent
+If you apply it as, say,
+
+@example
+\markup \foo #1 #"bar" #2 #"baz"
+@end example
+
+@cindex Scheme signature
+@cindex signature, Scheme
+@noindent
+@command{lilypond} complains that it cannot parse @code{foo} due to its
+unknown Scheme signature.
 
 
+@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 latter 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
+beginning 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
@@ -1107,7 +1268,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.
@@ -1117,8 +1278,8 @@ arguments:
 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.
+@rinternals{NoteHead} event, and for a @rinternals{Stem} object,
+this is a @rinternals{NoteHead} object.
 
 Here is a function to use for @code{\applyOutput}; it blanks
 note-heads on the center-line:
@@ -1152,8 +1313,26 @@ Properties can also be set to a Scheme procedure,
 c b a g b a g b
 @end lilypond
 
-Procedures may also be combined like that with
-"grob closure".  Here is a setting from
+@noindent
+In this case, the procedure is executed as soon as the value of the
+property is requested during the formatting process.
+
+Most of the typesetting engine is driven by such callbacks.
+Properties that typically use callbacks include  
+
+@table @code
+@item stencil
+  The printing routine, that constructs a drawing for the symbol
+@item X-offset
+  The routine that sets the horizontal position
+@item X-extent
+  The routine that computes the width of an object
+@end table
+
+The procedure always takes a single argument, being the grob.
+
+If routines with multiple arguments must be called, the current grob
+can be inserted with a grob closure.  Here is a setting from
 @code{AccidentalSuggestion},
 
 @example
@@ -1166,4 +1345,170 @@ Procedures may also be combined like that with
            (list ly:self-alignment-interface::x-aligned-on-self)))))
 @end example
 
+@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
+thing is enclosed in @code{ly:make-simple-closure}.
+
+In fact, using a single procedure as property value is equivalent to
+
+@example
+(ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
+@end example
+
+@noindent
+The inner @code{ly:make-simple-closure} supplies the grob as argument
+to @var{proc}, the outer ensures that result of the function is
+returned, rather than the @code{simple-closure} object.
+
+
+@node TODO moved into scheme
+@section TODO moved into scheme
+
+@menu
+* Using Scheme code instead of \tweak::  
+* Difficult tweaks::            
+@end menu
+
+@node Using Scheme code instead of \tweak
+@subsection Using Scheme code instead of @code{\tweak}
+
+The main disadvantage of @code{\tweak} is its syntactical
+inflexibility.  For example, the following produces a syntax error.
+
+@example
+F = \tweak #'font-size #-3 -\flageolet
+
+\relative c'' @{
+  c4^\F c4_\F
+@}
+@end example
+
+@noindent
+With other words, @code{\tweak} doesn't behave like an articulation
+regarding the syntax; in particular, it can't be attached with
+@code{^} and @code{_}.
+
+Using Scheme, this problem can be circumvented.  The route to the
+result is given in @ref{Adding articulation to notes (example)},
+especially how to use @code{\displayMusic} as a helping guide.
+
+@example
+F = #(let ((m (make-music 'ArticulationEvent
+                          'articulation-type "flageolet")))
+       (set! (ly:music-property m 'tweaks)
+             (acons 'font-size -3
+                    (ly:music-property m 'tweaks)))
+       m)
+ 
+\relative c'' @{
+  c4^\F c4_\F
+@}
+@end example
+
+@noindent
+Here, the @code{tweaks} properties of the flageolet object
+@code{m} (created with @code{make-music}) are extracted with
+@code{ly:music-property}, a new key-value pair to change the
+font size is prepended to the property list with the
+@code{acons} Scheme function, and the result is finally
+written back with @code{set!}.  The last element of the
+@code{let} block is the return value, @code{m} itself.
+
+
+
+@node Difficult tweaks
+@subsection Difficult tweaks
+
+There are a few classes of difficult adjustments.
+
+@itemize
+
+
+@item
+One type of difficult adjustment is the appearance of spanner objects,
+such as slur and tie.  Initially, only one of these objects is created,
+and they can be adjusted with the normal mechanism.  However, in some
+cases the spanners cross line breaks.  If this happens, these objects
+are cloned.  A separate object is created for every system that it is
+in.  These are clones of the original object and inherit all
+properties, including @code{\override}s.
+
+
+In other words, an @code{\override} always affects all pieces of a
+broken spanner.  To change only one part of a spanner at a line break,
+it is necessary to hook into the formatting process.  The
+@code{after-line-breaking} callback contains the Scheme procedure that
+is called after the line breaks have been determined, and layout
+objects have been split over different systems.
+
+In the following example, we define a procedure
+@code{my-callback}.  This procedure
+
+@itemize
+@item
+determines if we have been split across line breaks
+@item
+if yes, retrieves all the split objects
+@item
+checks if we are the last of the split objects
+@item
+if yes, it sets @code{extra-offset}.
+@end itemize
+
+This procedure is installed into @rinternals{Tie}, so the last part
+of the broken tie is translated up.
+
+@lilypond[quote,verbatim,ragged-right]
+#(define (my-callback grob)
+  (let* (
+         ; have we been split?
+         (orig (ly:grob-original grob))
+
+         ; if yes, get the split pieces (our siblings)
+         (siblings (if (ly:grob? orig)
+                     (ly:spanner-broken-into orig) '() )))
+
+   (if (and (>= (length siblings) 2)
+             (eq? (car (last-pair siblings)) grob))
+     (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
+
+\relative c'' {
+  \override Tie #'after-line-breaking =
+  #my-callback
+  c1 ~ \break c2 ~ c
+}
+@end lilypond
+
+@noindent
+When applying this trick, the new @code{after-line-breaking} callback
+should also call the old one @code{after-line-breaking}, if there is
+one.  For example, if using this with @code{Hairpin},
+@code{ly:hairpin::after-line-breaking} should also be called.
+
+
+@item Some objects cannot be changed with @code{\override} for
+technical reasons.  Examples of those are @code{NonMusicalPaperColumn}
+and @code{PaperColumn}.  They can be changed with the
+@code{\overrideProperty} function, which works similar to @code{\once
+\override}, but uses a different syntax.
+
+@example
+\overrideProperty
+#"Score.NonMusicalPaperColumn"  % Grob name
+#'line-break-system-details     % Property name
+#'((next-padding . 20))         % Value
+@end example
+
+Note, however, that @code{\override}, applied to
+@code{NoteMusicalPaperColumn} and @code{PaperColumn}, still works as
+expected within @code{\context} blocks.
+
+@end itemize
+
+
+
+