From: Graham Percival Date: Thu, 11 May 2006 13:00:10 +0000 (+0000) Subject: Editing and merging info from emails from Nicolas. X-Git-Tag: release/2.9.5~33 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=c29a3c759df684a60c7d5d9cba31058db57eb756;p=lilypond.git Editing and merging info from emails from Nicolas. --- diff --git a/ChangeLog b/ChangeLog index 86d8171a57..2390b5e802 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2006-05-11 Graham Percival + + * Documentation/user/programming-interface.itely: first round of + editing and merging emails from Nicolas. + + * Documentation/user/scheme-tutorial: minor edit. + 2006-05-11 Han-Wen Nienhuys * python/musicxml.py (Xml_node.__init__): _attribute_dict stores diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely index 14aa7dffe9..d94146db00 100644 --- a/Documentation/user/programming-interface.itely +++ b/Documentation/user/programming-interface.itely @@ -2,16 +2,21 @@ @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}. @menu -* Programmer interfaces for input :: +* Programmer interfaces for input:: * Markup programmer interface:: * Contexts for programmers:: @end menu -@node Programmer interfaces for input -@section Programmer interfaces for input + +@node Programmer interfaces for input +@section Programmer interfaces for input + +This section discusses how to create functions within LilyPond. @menu * Input variables and Scheme:: @@ -112,32 +117,31 @@ Mixing Scheme and LilyPond identifiers is not possible with the When a music expression is parsed, it is converted into a set of Scheme music objects. The defining property of a music object is that it takes up time. Time is a rational number that measures the length -of a piece of music, in whole notes. +of a piece of music in whole notes. A music object has three kinds of types: @itemize @bullet @item -music name: Each music expression has a name, for example, a note +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 internals manual, under +available is in the Program reference manual, under @internalsref{Music expressions}. @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}. - -All classes of music are listed in the internals manual, under +@code{note-event}, a @code{rhythmic-event}, and a +@code{melodic-event}. All classes of music are listed in the +Profram reference, under @internalsref{Music classes}. @item C++ object: Each music object is represented by a C++ object. For technical reasons, different music objects may be represented by different C++ object types. For example, a note is @code{Event} -object, while @code{\grace} creates a @code{Grace_music} object. - -We expect that distinctions between different C++ types will disappear +object, while @code{\grace} creates a @code{Grace_music} object. We +expect that distinctions between different C++ types will disappear in the future. @end itemize @@ -173,7 +177,7 @@ The syntax of composite music expressions, like @code{\repeat}, \@code{keyword} @var{non-music-arguments} @var{music-arguments} @end example -Such syntax can also be defined as user code. To do this, it is +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 a user-defined function to a music expression. Its syntax is @@ -195,7 +199,7 @@ arguments. This is encoded in its parameter list, (list procedure? ly:music?) @end example -The function itself takes another argument, an Input location +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 simply calls the function @@ -230,12 +234,14 @@ Examples of the use of @code{\applyMusic} are in the next section. @seealso @file{ly/@/music@/-functions@/-init@/.ly}. + @node Manipulating music expressions @subsection Manipulating music expressions Music objects and their properties can be accessed and manipulated -directly, through the @code{\applyMusic} mechanism. +directly through the @code{\applyMusic} mechanism. The syntax for @code{\applyMusic} is + @example \applyMusic #@var{func} @var{music} @end example @@ -276,6 +282,7 @@ The following example is such a recursive function: It first extracts the @code{elements} of an expression, reverses them and puts them back. Then it recurses, both on @code{elements} and @code{element} children. + @example #(define (reverse-music music) (let* ((elements (ly:music-property music 'elements)) @@ -331,9 +338,9 @@ exporting LilyPond input to other formats @cindex @code{\displayMusic} @cindex @code{\displayLilyMusic} -When writing a music function, it is often instructive to inspect how +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}. +music function @code{\displayMusic} @example @{ @@ -341,8 +348,30 @@ music function @code{\displayMusic}. @} @end example -Conversely, displaying a music expression in LilyPond notation can be -done using the music function @code{\displayLilyMusic}. For instance: +@noindent +will display + +@example +(make-music + 'SequentialMusic + 'elements + (list (make-music + 'EventChord + 'elements + (list (make-music + 'NoteEvent + 'duration + (ly:make-duration 2 0 1 1) + 'pitch + (ly:make-pitch 0 0 0)) + (make-music + 'AbsoluteDynamicEvent + 'text + "f"))))) +@end example + +Displaying a music expression in LilyPond notation can be +done using the music function @code{\displayLilyMusic}. For example, @example @{ @@ -350,18 +379,19 @@ done using the music function @code{\displayLilyMusic}. For instance: @} @end example -will display: +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 common LilyPond syntax inside +simple tasks this can be avoided by using common LilyPond syntax inside Scheme, with the dedicated @code{#@{ ... #@}} syntax. The following two expressions give equivalent music expressions: @@ -452,6 +482,40 @@ withPadding = } @end lilypond +Music functions can involve Scheme programming, in +addition to simple substitution, + +@lilypond[quote,verbatim,ragged-right] +AltOn = #(define-music-function (parser location mag) (number?) + #{ \override Stem #'length = #$(* 7.0 mag) + \override NoteHead #'font-size = + #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #}) + +AltOff = { + \revert Stem #'length + \revert NoteHead #'font-size +} + +{ c'2 \AltOn #0.5 c'4 c' + \AltOn #1.5 c' c' \AltOff c'2 } +@end lilypond + +@noindent +This example may be rewritten + +@lilypond[quote,verbatim,ragged-right] +withAlt = #(define-music-function (parser location mag music) (number? ly:music?) + #{ \override Stem #'length = #$(* 7.0 mag) + \override NoteHead #'font-size = + #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) + $music + \revert Stem #'length + \revert NoteHead #'font-size #}) + +{ c'2 \withAlt #0.5 {c'4 c'} + \withAlt #1.5 {c' c'} c'2 } +@end lilypond + @node Markup programmer interface @section Markup programmer interface diff --git a/Documentation/user/scheme-tutorial.itely b/Documentation/user/scheme-tutorial.itely index 6d9d9c3cd4..4024a22ee6 100644 --- a/Documentation/user/scheme-tutorial.itely +++ b/Documentation/user/scheme-tutorial.itely @@ -14,8 +14,8 @@ LilyPond uses the Scheme programming language, both as part of the input syntax, and as internal mechanism to glue modules of the program together. This section is a very brief overview of entering data in -Scheme.@footnote{If you want to know more about Scheme, see -@uref{http://@/www@/.schemers@/.org}.} +Scheme. If you want to know more about Scheme, see +@uref{http://@/www@/.schemers@/.org}. The most basic thing of a language is data: numbers, character strings, lists, etc. Here is a list of data types that are relevant to