In this stage @code{Music_iterators} do a traversal of the @code{Music}
structure. The music events thus encountered are reported to
-@code{Translator}s, a set objects that collectively form interpretation
+@code{Translator}s, a set of objects that collectively form interpretation
contexts.
@item Breaking
Relations between all grobs are modified to reflect line breaks: When a
-spanner, eg. a slur, crosses a line-break, then the spanner is "broken
+spanner, e.g. a slur, crosses a line-break, then the spanner is "broken
into pieces", for every line that the spanner is in, a copy of the grob
is made. A substitution process redirects all grob-reference so that
-spanner grob will only reference other grobs in the same line.
+each spanner grob will only reference other grobs in the same line.
@item Outputting:
* Miscellaneous Scheme functions::
@end menu
+@ignore
+ Why not use Scheme syntax for the functions below, such as
+ (ly-input-location? obj) and (ly-get-mus-property m sym) ?
+
+ /MB
+@end ignore
+
@node Input location
-@section input location
+@section Input location
-The parser generates
+@c The parser generates
-Input location objects point to a lcoation in the input file. This
+Input location objects point to a location in the input file. This
location is used to generate error messages and to enable the point and
click output.
-@defun ly-input-location?
-Type predicate
+@defun ly-input-location? obj
+Type predicate, return true if @var{obj} is an input location.
@end defun
Moment is a rational number. Since GUILE doesn't support them natively,
so we created our own rational data type.
-@defun moment?
+@defun moment? obj
+Type predicate, return true if @var{obj} is a moment.
@end defun
@defun make-moment num den
@end defun
-@defun duration? d
-type predicate for Duration
+@defun duration? obj
+Type predicate, return true if @var{obj} is a duration.
@end defun
@node Pitch data type
@end defun
@defun music? obj
-A type predicate, return true if @var{obj} is a music object.
+Type predicate, return true if @var{obj} is a music object.
@end defun
@defun ly-music-name music
reports the events it finds to interpretation contexts. It is not yet
user-serviceable.
-@defun c++-function?
-type predicate for c++-function. Music_iterator are created from
-schemified C++ constructors. Such a constructor is a @code{c++-function}.
+@defun c++-function? obj
+Type predicate, return true if @var{obj} is a c++-function.
+Music_iterator are created from schemified C++ constructors. Such a
+constructor is a @code{c++-function}.
@end defun
@node Translator
In music notation, lots of symbols are related in some way. You can
think of music notation as a graph where nodes are formed by the
-symbols, and the arcs by their relations. A grob is node in that graph.
+symbols, and the arcs by their relations. A grob is a node in that graph.
The directed edges in the graph are formed by references to other grobs
(i.e. pointers).
-
This big graph of grobs specifies the notation problem. The solution of
this problem is a description of the printout in closed form, i.e. a
list of values. These values are Molecules. (see @ref{Molecules})
If you keep following offset reference points, you will always end up at
the root object. This root object is called @code{Line_of_score}, and it
-represents a system (ie. a line of music).
+represents a system (i.e. a line of music).
All grobs carry a set of grob-properties. In the Stem example above,
the property @code{direction} is set to value @code{1}. The function
A grob is often associated with a symbol, but some grobs do not print
any symbols. They take care of grouping objects. For example, there is a
separate grob that stacks staffs vertically. The @code{NoteCollision}
-also is an abstract grob: it only moves around chords, but doesn't print
+is also an abstract grob: it only moves around chords, but doesn't print
anything.
A complete list of grob types is found in the generated documentation.
-Offset callbacks can be stacked, ie.
+Offset callbacks can be stacked, i.e.
@example
\property .... \override #'Y-offset-callbacks = #(list
@subsection Setting grob properties
Grob properties are stored as GUILE association lists, with symbols as
-keys. In GUILE you can access these using functions described @ref{Grob
-Scheme functions}. From C++, grob properties can be accessed using
-these functions:
+keys. In GUILE you can access these using functions described in
+Section @ref{Grob Scheme functions}. From C++, grob properties can be
+accessed using these functions:
@example
SCM get_grob_property (SCM) const;
@end example
All lookup functions identify undefined properties with end-of-list
-(ie. @code{'()} in Scheme or @code{SCM_EOL} in C)
+(i.e. @code{'()} in Scheme or @code{SCM_EOL} in C)
Properties are stored in two ways:
@itemize @bullet
@item mutable properties.
-grob properties that change from object to object. The storage of
+Grob properties that change from object to object. The storage of
these are private to a grob. For example pointers to other grobs are
always stored in the mutable properties.
Grob properties that are shared across different grobs of the same
type. The storage is shared, and hence it is read-only. Typically, this
is used to store function callbacks, and default settings. They are
-initially read from from @file{scm/grob-description.scm}.
+initially read from @file{scm/grob-description.scm}.
@end itemize
You can change immutable grob properties with the \override syntax:
\property Voice.stem \revert #'direction
@end example
-If you use this a lot, this gets old quickly. So we also have a
-shorthand,
+There is also a shorthand,
@example
\property Context.GrobType \set #'prop = #VAL
@end example
In this case, in every grob that satisfies @var{pred}, the grob property
- @var{sym} is set to @var{val} is done. For example
+ @var{sym} is set to @var{val}. For example
@example
\outputproperty
@node Grob interfaces
@unnumberedsubsec Grob interfaces
-Grob properties form a namespace where you can set variables per
+Grob properties form a name space where you can set variables per
object. Each object however, may have multiple functions. For example,
consider a dynamic symbol, such @code{\ff} (fortissimo). It is printed
above or below the staff, it is a dynamic sign, and it is a kind of
@unnumberedsubsec Items and Spanners
Grobs can also be distinguished in their role in the horizontal spacing.
-A lot of grobs define constraints on the spacing by their sizes. For
+Many grobs define constraints on the spacing by their sizes. For
example, note heads, clefs, stems, and all other symbols with a fixed
shape. These grobs form a subtype called @code{Item}.
also the X-reference point of the spanner.
Some items need special treatment for line breaking. For example, a
-clef is normally only printed at the start of a line (ie. after a line
+clef is normally only printed at the start of a line (i.e. after a line
break). To model this, `breakable' items (clef, key signature, bar lines,
etc.) are copied twice. Then we have three versions of each breakable
item: one version if there is no line break, one version that is printed
can run with the @code{-f scm} option. The scheme expressions are then
dumped in the output file.
-All visible, i.e. non-transparant, grobs have a callback to create a
+All visible, i.e. non-transparent, grobs have a callback to create a
Molecule. The name of the property is @code{molecule-callback}, and its
value should be a Scheme function taking one argument (the grob) and
returning a Molecule. Most molecule callbacks are written in C++, but
them. This information is stored in font metric files. LilyPond can read
two types of font-metrics: @TeX{} Font Metric files (TFM files) and
Adobe Font Metric files (AFM files). LilyPond will always try to load
-AFM files first they files are more versatile.
+AFM files first since they are more versatile.
@defun ly-get-default-font gr
This returns the default font for grob @var{gr}.
@end defun
@defun dir?
-type predicate. A direction is a -1, 0 or 1.
+type predicate. A direction is a -1, 0 or 1, where -1 represents left or
+down and 1 represents right or up.
@end defun
@defun ly-number->string num
+@c -*-texinfo-*-
+
@node lilypond-book
@chapter lilypond-book
line width and font size definitions before @code{CONTENTS}, so the
music samples will match the layout of your document.
-Very often, if you mix music and text, the music is often only a few
+Very often, if you mix music and text, the music is only a few
notes or at most a few bars. This music should be as short as possible
and not stretched to be aligned to the right margin. lilypond-book does
this automatically if you don't use a @code{\score} block in
@end example
In the texinfo version, bitmaps of the music are also generated, so you
-can also make a HTML document with embedded music.
+can make a HTML document with embedded music.
@section TeXinfo reference
-Your markup the lilypond code like this:
+You specify the lilypond code like this:
@example
@@lilypond[options, go, here]
YOUR LILYPOND CODE
@end example
-@command{lilypond-book} knows the default margins, and a few papersizes.
-These commands should be in the beginning of the document:
+@command{lilypond-book} knows the default margins, and a few paper
+sizes. One of these commands should be in the beginning of the document:
@itemize @bullet
@item @code{@@afourpaper}
@item @code{@@afourlatex}
@section La@TeX{} reference
-Your markup the lilypond code like this:
+You specify the lilypond code like this:
@example
\begin[option, go, here]@{lilypond@}
YOUR LILYPOND CODE
\end@{lilypond@}
@end example
+@example
+\lilypondfile[options, go,here]@{@var{filename}@}
+@end example
or
-
@example
\lilypond@{ YOUR LILYPOND CODE @}
@end example
@table @code
@item eps
This will create the music as eps graphics and include it into the
-document with the @code{\includegraphics} command. It works in Latex
-only.
+document with the @code{\includegraphics} command. It works in
+La@TeX{} only.
This enables you to place music examples in the running text (and not in
a separate paragraph). To avoid that La@TeX{} places the music on a line
-of its one, there should be no empty lines between the normal text and
+of its own, there should be no empty lines between the normal text and
the lilypond environment. For inline music, you probably also need a
smaller music font size (eg. 11 pt or 13 pt)
The opposite of @code{singleline}: justify and break lines.
@item fragment
@item nofragment
- Override @command{lilypond-book} autodetection of what type of code is in the
+ Override @command{lilypond-book} auto detection of what type of code is in the
lilypond block, voice contents or complete code.
@item printfilename
Prints the file name before the music example. Useful in conjunction
When you run @command{lilypond-book} it will generate lots of small
files that Lilypond will process. So to avoid all the garbage in
your source directory, you should either change to a temporary
-directory, or use the @code{--outdir} commandline options:
+directory, or use the @code{--outdir} command line options:
@code{cd out && lilypond-book ../yourfile.tex}
TeXinfo input will be written to a file with extension @file{.texi}.
If you use @code{--outdir}, you should also @code{cd} to that directory
-before running LaTeX or makeinfo. This may seem a little kludgy, but
+before running LaTeX or makeinfo. This may seem a little kludgey, but
both Latex and makeinfo expect picture files (the music) to be in the
current working directory. Moreover, if you do this, LaTeX will not
clutter you normal working directory with output files.
@cindex lilypond-book and titling
@cindex \header in LaTeX documents
-If you want to combine music that has titling in @code{\header}
+If you want to add titling from the @code{\header} section of the
files, you should add the following to the top of your LaTeX
@example
\input titledefs.tex
@item @option{-f}, @option{--format=}
Specify the document type to process, @code{latex} or @code{texi}.
- @command{lilypond-book} usually figure out this automatically.
+ @command{lilypond-book} usually figure this out automatically.
@item --default-music-fontsize=@var{sz}pt
Set the fontsize to use for lilypond if no fontsize is given
as option.
@item --outname=@var{FILE}
The name of La@TeX{} file to output. If this option is not given,
- the output name derived from the input name.
+ the output name is derived from the input name.
@item --outdir=@var{DIR}
place generated files in @var{DIR}.
@item --version
The La@TeX{} \includeonly@{...@} command is ignored.
-The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
-But changing the linewidth in other ways will not give you a straight
+The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4,
+but changing the linewidth in other ways will not give you a straight
right margin.
-Ignores almost all La@TeX{} commands that changes margins and linewidths.
+Almost all La@TeX{} commands that change margins and line widths are ignored.
Since there is no finder's fee which doubles every year, there is no
need to wait for the prize money to grow. So send a bug report today if
projects / lilypond.git / commitdiff