X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fprogramming-interface.itely;h=e62d864f82c201585fc77db5e300728559f65c2f;hb=c2389d605aaaf3b3e8c416428d4b4088e4b049ca;hp=c54e1bb0fa57d6e7b27e5a6cd89a7da4f116f8e8;hpb=fcfc36d5bef8efa35d3004c706816ce70ece9196;p=lilypond.git

diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely
index c54e1bb0fa..e62d864f82 100644
--- a/Documentation/user/programming-interface.itely
+++ b/Documentation/user/programming-interface.itely
@@ -1,4 +1,4 @@
-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
 @node Interfaces for programmers
 @chapter Interfaces for programmers
 
@@ -18,6 +18,7 @@
 * Internal music representation::  
 * Extending music syntax::      
 * Manipulating music expressions::  
+* Displaying music expressions::  
 * Using LilyPond syntax inside Scheme::  
 @end menu
 
@@ -25,7 +26,7 @@
 @subsection Input variables and Scheme
 
 
-The input format supports the notion of variable: in the following
+The input format supports the notion of variables: in the following
 example, a music expression is assigned to a variable with the name
 @code{traLaLa}.
 @example
@@ -43,7 +44,7 @@ traLaLa = @{ c'4 d'4 @}
 @end example
 @c
 In effect, each input file is a scope, and all @code{\header},
-@code{\midi} and @code{\layout} blocks are scopes nested inside that
+@code{\midi}, and @code{\layout} blocks are scopes nested inside that
 toplevel scope.
 
 Both variables and scoping are implemented in the GUILE module system.
@@ -62,7 +63,7 @@ is internally converted to a Scheme definition
 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
+imported in a @code{\score} block by means of a second variable
 @code{twice}:
 @example
 traLaLa = @{ c'4 d'4 @}
@@ -83,7 +84,7 @@ of defining @code{\twice}, the example above could also have been
 written as
 @example
 @dots{}
-@{ #(ly:export (make-sequential-music newLa)) @}
+@{ #(ly:export (make-sequential-music (list newLa))) @}
 @end example
 
 @refbugs
@@ -111,7 +112,7 @@ available is in the internals manual, under
 @item
 `type' or interface: Each music name has several `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}.
+@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}.
@@ -148,9 +149,11 @@ property of @internalsref{RepeatedMusic}, and the alternatives in
 @node Extending music syntax
 @subsection Extending music syntax
 
-The syntax of composite music expressions, like
-@code{\repeat}, @code{\transpose} and @code{\context}
-follows the general form of
+@c TODO: rewrite example.
+@c The use of FUNC as example  argument is rather confusing.
+
+The syntax of composite music expressions, like @code{\repeat},
+@code{\transpose}, and @code{\context} follows the general form of
 
 @example
 \@code{keyword} @var{non-music-arguments} @var{music-arguments}
@@ -158,11 +161,11 @@ follows the general form of
 
 Such syntax can also be defined as user code.  To do this, it is
 necessary to create a @emph{music function}.  This is a specially marked
-Scheme function.  For example, the music function @code{\applymusic} applies
+Scheme function.  For example, the music function @code{\applyMusic} applies
 a user-defined function to a music expression.  Its syntax is
 
 @example
-\applymusic #@var{func} @var{music}
+\applyMusic #@var{func} @var{music}
 @end example
 
 A music function is created with @code{ly:make-music-function},
@@ -171,8 +174,8 @@ A music function is created with @code{ly:make-music-function},
 (ly:make-music-function
 @end example
 
-@code{\applymusic} takes a Scheme function and a Music expression as
-argument.  This is encoded in its first argument,
+@code{\applyMusic} takes a Scheme function and a Music expression as
+arguments.  This is encoded in its parameter list,
 
 @example
 (list procedure? ly:music?)
@@ -181,8 +184,7 @@ argument.  This is encoded in its first argument,
 The function itself takes another argument, an Input location
 object.  That object is used to provide error messages with file names
 and line numbers.  The definition is the second argument of
-@code{ly:make-music-function}.  The body is function simply calls the
-function
+@code{ly:make-music-function}.  The body simply calls the function
 
 @example
 (lambda (where func music)
@@ -190,12 +192,12 @@ function
 @end example
 
 The above Scheme code only defines the functionality.  The tag
-@code{\applymusic} is selected by defining
+@code{\applyMusic} is selected by defining
 
 @example
-applymusic = #(ly:make-music-function
+applyMusic = #(ly:make-music-function
                 (list procedure? ly:music?)
-                (lambda (location func music)
+                (lambda (parser location func music)
                   (func music)))
 @end example
 
@@ -204,12 +206,12 @@ A @code{def-music-function} macro is introduced on top of
 functions:
 
 @example
-applymusic = #(def-music-function (location func music)
+applyMusic = #(def-music-function (parser location func music)
                 (procedure? ly:music?)
                 (func music))
 @end example
 
-Examples of the use of @code{\applymusic} are in the next section.
+Examples of the use of @code{\applyMusic} are in the next section.
 
 @seealso
 @file{ly/@/music@/-functions@/-init@/.ly}.
@@ -218,10 +220,10 @@ Examples of the use of @code{\applymusic} are in the next section.
 @subsection Manipulating music expressions
 
 Music objects and their properties can be accessed and manipulated
-directly, through the @code{\applymusic} mechanism.
-The syntax for @code{\applymusic} is
+directly, through the @code{\applyMusic} mechanism.
+The syntax for @code{\applyMusic} is
 @example
-\applymusic #@var{func} @var{music}
+\applyMusic #@var{func} @var{music}
 @end example
 
 @noindent
@@ -239,21 +241,21 @@ its argument,
     (reverse (ly:music-property m 'elements)))
   m)
 
-\applymusic #rev-music-1 { c'4 d'4 } 
+\applyMusic #rev-music-1 { c'4 d'4 } 
 @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
+function is void when applied to an argument that does not have
 multiple children.  The following function application has no effect
 
 @example
-\applymusic #rev-music-1 \grace @{ c4 d4 @}
+\applyMusic #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{\applymusic} must---like music expressions
+applicable function for @code{\applyMusic} must -- like music expressions
 themselves -- be recursive.
 
 The following example is such a recursive function: It first extracts
@@ -293,32 +295,59 @@ above by the internal equivalent of
    \context Voice = "2" @{ \voiceTwo b @} >>
 @end example
 
-Other applications of @code{\applymusic} are writing out repeats
+Other applications of @code{\applyMusic} 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})
+@c no @inputfileref{} here 
+(eg. @file{input/@/no@/-notation/@/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 Displaying music expressions
+@subsection Displaying music expressions
 
 @cindex internal storage
 @cindex @code{\displayMusic}
+@cindex @code{\displayLilyMusic}
+
 When writing a music function, it is often instructive to inspect how
 a music expression is stored internally.  This can be done with the
 music function @code{\displayMusic}.
 
-@seealso
+@example
+@{
+  \displayMusic @{ c'4\f @}
+@}
+@end example
 
-@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}.
+Conversely, displaying a music expression in LilyPond notation can be
+done using the music function @code{\displayLilyMusic}. For instance:
 
+@example
+@{
+  \displayLilyMusic \transpose c a, @{ c e g a bes @}
+@}
+@end example
+
+will display:
+
+@example
+@{ a, cis e fis g @}
+@end example
 
 @node Using LilyPond syntax inside Scheme
 @subsection Using LilyPond syntax inside Scheme
 
 Creating music expressions in Scheme can be tedious, as they are
 heavily nested and the resulting Scheme code is large.  For some
-simple tasks, this can be avoided, using LilyPond usual syntax inside
+simple tasks, this can be avoided, using common LilyPond syntax inside
 Scheme, with the dedicated @code{#@{ ... #@}} syntax.
 
 The following two expressions give equivalent music expressions:
@@ -336,7 +365,7 @@ The content of @code{#@{ ... #@}} is enclosed in an implicit @code{@{
 
 Arbitrary Scheme forms, including variables, can be used in @code{#@{ ... #@}}
 expressions with the @code{$} character (@code{$$} can be used to
-produce a single $ character).  This makes the creation of simple
+produce a single @code{$} character).  This makes the creation of simple
 functions straightforward.  In the following example, a function
 setting the TextScript's padding is defined:
 
@@ -373,7 +402,7 @@ example:
 
 {
   c'^"1"
-  \applymusic #(with-padding 3) { c'^"2" c'^"3" }
+  \applyMusic #(with-padding 3) { c'^"2" c'^"3" }
   c'^"4"
 }
 @end lilypond
@@ -397,7 +426,7 @@ This function may also be defined as a music function:
 
 @lilypond[quote,verbatim,raggedright]
 withPadding =
-  #(def-music-function (location padding music) (number? ly:music?)
+  #(def-music-function (parser location padding music) (number? ly:music?)
     #{ \override TextScript #'padding = #$padding
        $music 
        \revert TextScript #'padding #})
@@ -413,10 +442,12 @@ withPadding =
 @node Markup programmer interface
 @section Markup programmer interface
 
-Markups implemented as special Scheme functions.  When applied with as
-arguments an output definition (@code{\layout} or @code{\paper}),
-and a list of properties and other arguments, produce a Stencil
-object.
+@c Please rewrite the second sentence; I don't understand its meaning. AS
+
+Markups are implemented as special Scheme functions.  When applied
+with as arguments an output definition (@code{\layout} or
+@code{\paper}), and a list of properties and other arguments, produce
+a Stencil object.
 
 @menu
 * Markup construction in Scheme::  
@@ -439,8 +470,8 @@ providing a LilyPond-like syntax.  For example,
 @noindent
 is equivalent to:
 @example
-\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
-                  \bigger @{ foo bar baz @} >
+\markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
+                  \bigger \line @{ foo bar baz @} @}
 @end example
 
 @noindent
@@ -451,10 +482,12 @@ is this table:
 @quotation
 @multitable @columnfractions .3 .3
 @item @b{LilyPond} @tab @b{Scheme}
+@item @code{\markup markup1 @}} @tab @code{(markup markup1)}
+@item @code{\markup @{ markup1 markup2 ... @}} @tab 
+        @code{(markup markup1 markup2 ... )}
 @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{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
 @item @code{string} @tab @code{"string"}
 @item @code{#scheme-arg} @tab @code{scheme-arg}
 @end multitable
@@ -477,8 +510,8 @@ call.  Example:
 @end lisp
 
 @noindent
-is invalid.  One should use the @code{make-line-markup} (resp
-@code{make-center-markup}, @code{make-column-markup}) function
+is invalid.  One should use the @code{make-line-markup} (resp.,
+@code{make-center-markup} or @code{make-column-markup}) function
 instead,
 @lisp
 (markup (make-line-markup (fun-that-returns-markups)))
@@ -498,15 +531,11 @@ In a markup like
 function.  The markup expression is stored as
 
 @example
-(list raise-markup 0.5 (list simple-markup 'latin1 "foo"))
+(list raise-markup 0.5 (list simple-markup "foo"))
 @end example
 
-@noindent
-In this case, @code{latin1} is the input encoding, which is set with
-the @code{\encoding} command.
-
 When the markup is converted to printable objects (Stencils), the
-raise markup is called as
+@code{raise-markup} function is called as
 
 @example
 (apply raise-markup
@@ -516,10 +545,10 @@ raise markup is called as
        @var{the "foo" markup})
 @end example
 
-The @code{raise-markup} first creates the stencil for the @code{foo}
-string, and then it raises that Stencil by 0.5 staff space.  This is a
-rather simple example; more complex examples are in the rest of this
-section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
+The @code{raise-markup} function first creates the stencil for the
+@code{foo} string, and then it raises that Stencil by 0.5 staff space.
+This is a rather simple example; more complex examples are in the rest
+of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
 
 @node Markup command definition
 @subsection Markup command definition
@@ -558,7 +587,7 @@ This selects the caps font by setting the @code{font-shape} property to
 
 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
+take a single argument, of type markup.  Therefore, the start of the
 definition should read
 @example
 (def-markup-command (smallcaps layout props argument) (markup?)
@@ -567,7 +596,7 @@ definition should read
 @noindent
 
 What follows is the content of the command: we should interpret
-the @code{argument} as a markup, i.e.
+the @code{argument} as a markup, i.e.,
 
 @example
 (interpret-markup layout @dots{} argument)
@@ -584,14 +613,14 @@ above example:
 
 @noindent
 The variable @code{props} is a list of alists, and we prepend to it by
-consing a list with the extra setting.
+cons'ing a list with the extra setting.
 
 
 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
+that takes into account the necessary translation, and uses the newly
 defined @code{\smallcaps} command:
 
 @example
@@ -599,15 +628,15 @@ defined @code{\smallcaps} command:
   "Print the character name in small caps, translated to the left and
   top.  Syntax: \\character #\"name\""
   (interpret-markup layout props 
-   (markup "" #:translate (cons -3 1) #:smallcaps name)))
+   (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
 @end example
 
 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{#:translate}, we add an empty string (@code{#:hspace 0}) before the
+translated text.  Now the @code{#:hspace 0} 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.
 
@@ -636,7 +665,7 @@ The final result is as follows:
   "Print the character name in small caps, translated to the left and
   top.  Syntax: \\character #\"name\""
   (interpret-markup layout props 
-   (markup "" #:translate (cons -3 1) #:smallcaps name)))
+   (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
 
 {
   c''^\markup \character #"Cleopatra" c'' c'' c''
@@ -645,8 +674,8 @@ The final result is as follows:
 @end lilypond
 
 We have used the @code{caps} font shape, but suppose that our 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
+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
@@ -691,12 +720,12 @@ to the @code{interpret-markup} function, with the @code{layout} and
 @subsection Context evaluation
 
 @cindex calling code during interpreting
-@cindex @code{\applycontext}
+@cindex @code{\applyContext}
 
 Contexts can be modified during interpretation with Scheme code.  The
 syntax for this is
 @example
-\applycontext @var{function}
+\applyContext @var{function}
 @end example
 
 @var{function} should be a Scheme function taking a single argument,
@@ -704,7 +733,7 @@ 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
+\applyContext
   #(lambda (x)
     (format #t "\nWe were called in barnumber ~a.\n"
      (ly:context-property x 'currentBarNumber)))
@@ -717,13 +746,13 @@ current bar number on the standard output during the compile:
 
 
 @cindex calling code on layout objects
-@cindex @code{\applyoutput}
+@cindex @code{\applyOutput}
 
 
-The most versatile way of tuning an object is @code{\applyoutput}.  Its
+The most versatile way of tuning an object is @code{\applyOutput}.  Its
 syntax is
 @example
-\applyoutput @var{proc}
+\applyOutput @var{proc}
 @end example
 
 @noindent
@@ -734,17 +763,17 @@ 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.
+@item the context where @code{\applyOutput} is processed.
 @end itemize
 
 
-In addition, the cause of the layout object, i.e.  the music
+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 function to use for @code{\applyoutput}; it blanks
+Here is a function to use for @code{\applyOutput}; it blanks
 note-heads on the center-line:
 
 @example