* Technical glossary::
* All context properties::
* Layout properties::
-* Identifiers::
+* Available music functions::
* Scheme functions::
@end menu
@cindex Font, Feta
The following symbols are available in the Emmentaler font and may be
-accessed directly using text markup such as @code{g^\markup @{
-\musicglyph #"scripts.segno" @}}, see @ref{Formatting text}.
+accessed directly using text markup with the name of the glyph
+as shown in the tables below,
+such as @code{g^\markup @{\musicglyph #"scripts.segno" @}} or
+@code{\markup @{\musicglyph #"five"@}}. For more information,
+see @ref{Formatting text}.
@menu
@node Technical glossary
@appendixsec Technical glossary
-A glossary of the technical terms and concepts used internally.
+A glossary of the technical terms and concepts used internally in
+LilyPond. These terms may appear in the manuals, on mailing lists
+or in the source code.
@menu
+* alist::
* callback::
+* closure::
* glyph::
* grob::
+* immutable::
* interface::
* lexer::
+* mutable::
* output-def::
* parser::
* parser variable::
* prob::
-* simple-closure::
+* simple closure::
* smob::
* stencil::
@end menu
+@node alist
+@unnumberedsubsec alist
+
+@cindex alist
+@cindex association list
+
+An association list or @strong{alist} for short is a Scheme pair
+which associates a value with a key: @w{@code{(key . value)}}. For
+example, in @file{scm/lily.scm}, the alist
+@w{@qq{type-p-name-alist}} associates certain type predicates
+(e.g.@tie{}@code{ly:music?}) with names (e.g.@tie{}@qq{music}) so
+that type-check failures can be reported with a console message that
+includes the name of the expected type predicate.
+
@node callback
@unnumberedsubsec callback
user-level Scheme code to define how many low-level actions are
performed.
+
+@node closure
+@unnumberedsubsec closure
+
+@cindex closure
+@cindex simple closure
+
+In Scheme, a @strong{closure} is created when a function, usually
+a lambda expression, is passed as a variable. The closure contains
+the function's code plus references to the lexical bindings of the
+function's free variables (i.e. those variables used in the
+expression but defined outside it). When this function is applied
+to different arguments later, the free variable bindings that were
+captured in the closure are used to obtain the values of the free
+variables to be used in the calculation. One useful property of
+closures is the retention of internal variable values between
+invocations, so permitting state to be maintained.
+
+A @strong{simple closure} is a closure whose expression has no free
+variables and hence no free variable bindings.
+
+A simple closure is represented in LilyPond by a smob containing
+the expression and a method to apply the expression to a passed
+list of arguments.
+
+
@node glyph
@unnumberedsubsec glyph
LilyPond objects which represent items of notation in the printed
output such as note heads, stems, slurs, ties, fingering, clefs,
etc are called @q{Layout objects}, often known as @q{GRaphical
-OBjects}, or @strong{grobs} for short.
-
+OBjects}, or @strong{grobs} for short. They are represented by
+instances of the @code{Grob} class.
@seealso
Learning Manual:
@rlearning{Properties of layout objects}.
Internals Reference:
+@rinternals{grob-interface},
@rinternals{All layout objects}.
+@node immutable
+@unnumberedsubsec immutable
+
+@cindex immutable objects
+@cindex immutable properties
+@cindex shared properties
+
+An @strong{immutable} object is one whose state cannot be modified
+after creation, in contrast to a mutable object, which can be
+modified after creation.
+
+In LilyPond, immutable or shared properties define the default
+style and behavior of grobs. They are shared between many objects.
+In apparent contradiction to the name, they can be changed using
+@code{\override} and @code{\revert}.
+
+@seealso
+Notation Reference:
+@ref{mutable}.
+
@node interface
@unnumberedsubsec interface
grouped together in an object called a @code{grob-interface}, or
just @q{interface} for short.
-
@seealso
Learning Manual:
@rlearning{Objects and interfaces},
@unnumberedsubsec lexer
@cindex lexer
+@cindex Flex
A @strong{lexer} is a program which converts a sequence of
characters into a sequence of tokens, a process called lexical
-analysis. The LilyPond lexer converts an input @code{.ly} file
-into a tokenized file more suited to the next stage of processing,
-parsing, see @ref{parser}.
+analysis. The LilyPond lexer converts the stream obtained from an
+input @file{.ly} file into a tokenized stream more suited to the
+next stage of processing - parsing, for which see @ref{parser}.
+The LilyPond lexer is built with Flex from the lexer file
+@file{lily/lexer.ll} which contains the lexical rules. This file
+is part of the source code and is not included in the LilyPond
+binary installation.
+
+
+@node mutable
+@unnumberedsubsec mutable
+
+@cindex mutable objects
+@cindex mutable properties
+
+A @strong{mutable} object is one whose state can be modified after
+creation, in contrast to an immutable object, whose state is fixed
+at the time of creation.
+
+In LilyPond, mutable properties contain values that are specific to
+one grob. Typically, lists of other objects or results from
+computations are stored in mutable properties.
+
+@seealso
+Notation Reference:
+@ref{immutable}.
@node output-def
@unnumberedsubsec output-def
data structures associated with an output block. Instances are
created for midi, layout and paper blocks.
+
@node parser
@unnumberedsubsec parser
@cindex parser
+@cindex Bison
+@cindex grammar for LilyPond
+@cindex BNF
+
+A @strong{parser} analyzes the sequence of tokens produced by a
+lexer to determine its grammatical structure, grouping the tokens
+progressively into larger groupings according to the rules of the
+grammar. If the sequence of tokens is valid the end product is a
+tree of tokens whose root is the grammar's start symbol. If this
+cannot be achieved the file is invalid and an appropriate error
+message is produced. The syntactic groupings and the rules for
+constructing the groupings from their parts for the LilyPond syntax
+are defined in @file{lily/parser.yy} and shown in Backus Normal Form
+(BNF) in @ref{LilyPond grammar}. This file is used to build the
+parser during the program build by the parser generator, Bison. It
+is part of the source code and is not included in the LilyPond
+binary installation.
-A @strong{parser} analyzes the sequence of tokens produced by
-a lexer to determine its grammatical structure as defined by the
-rules governing the format of an input file.
@node parser variable
@unnumberedsubsec parser variable
+@cindex parser variable
+@cindex Scheme variable
+@cindex global variable
+@cindex afterGraceFraction
+@cindex musicQuotes
+@cindex mode
+@cindex output-count
+@cindex output-suffix
+@cindex parseStringResult
+@cindex partCombineListener
+@cindex pitchnames
+@cindex toplevel-bookparts
+@cindex toplevel-scores
+@cindex showLastLength
+@cindex showFirstLength
+
These are variables defined directly in Scheme. Their direct
use by users is strongly discouraged, because their scoping
semantics can be confusing.
@item showFirstLength
@end itemize
+
@node prob
@unnumberedsubsec prob
-TODO
-@node simple-closure
-@unnumberedsubsec simple-closure
-TODO
+@cindex prob
+@cindex property object
+
+PRoperty OBjects, or @strong{probs} for short, are instances of
+the @code{Prob} class, a simple base class for objects which have
+mutable and immutable property alists and the methods to manipulate
+them. The @code{Music} and @code{Stream_event} classes derive from
+@code{Prob}. Instances of the @code{Prob} class are also created
+to hold the formatted content of system grobs and titling blocks
+during page layout.
+
+
+@node simple closure
+@unnumberedsubsec simple closure
+
+See @ref{closure}.
+
@node smob
@unnumberedsubsec smob
-TODO
+
+@cindex smob
+@cindex Scheme object
+
+@strong{Smobs}, or ScheMe OBjects, are part of the mechanism used
+by Guile to export C and C++ objects to Scheme code. In LilyPond,
+smobs are created from C++ objects through macros. There are two
+types of smob objects: simple smobs, intended for simple immutable
+objects like numbers, and complex smobs, used for objects with
+identities. If you have access to the LilyPond sources, more
+information can be found in @file{lily/includes/smob.hh}.
@node stencil
@unnumberedsubsec stencil
-TODO
+
+@cindex stencil
+
+An instance of the @strong{stencil} class holds the information
+required to print a typographical object. It is a simple smob
+containing a confining box, which defines the vertical and
+horizontal extents of the object, and a Scheme expression which
+will print the object when evaluated. Stencils may be combined
+to form more complex stencils defined by a tree of Scheme
+expressions formed from the Scheme expressions of the component
+stencils.
+
+The @code{stencil} property, which connects a grob to its stencil,
+is defined in the @code{grob-interface} interface.
+
+@seealso
+Internals Reference:
+@rinternals{grob-interface}.
@node All context properties
@include layout-properties.tely
-@node Identifiers
-@appendixsec Identifiers
+@node Available music functions
+@appendixsec Available music functions
@include identifiers.tely
projects / lilypond.git / blobdiff