@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
@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.
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 @}
written as
@example
@dots{}
-@{ #(ly:export (make-sequential-music newLa)) @}
+@{ #(ly:export (make-sequential-music (list newLa))) @}
@end example
@refbugs
@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}.
@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}
@end example
@code{\applymusic} takes a Scheme function and a Music expression as
-argument. This is encoded in its first argument,
+arguments. This is encoded in its parameter list,
@example
(list procedure? ly:music?)
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)
@example
applymusic = #(ly:make-music-function
(list procedure? ly:music?)
- (lambda (location func music)
+ (lambda (parser location func music)
(func music)))
@end example
functions:
@example
-applymusic = #(def-music-function (location func music)
+applymusic = #(def-music-function (parser location func music)
(procedure? ly:music?)
(func music))
@end example
@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
@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
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}).
@cindex internal storage
@cindex @code{\displayMusic}
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:
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:
@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 #})
@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::
@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)))
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
@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
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?)
@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)
@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
@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
@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,
projects / lilypond.git / blobdiff