X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fnotation-appendices.itely;h=87b51c81c2698efc77060236eefe40b4082c7a8a;hb=223ad8f5799657a5b628d862dd927f4197486b02;hp=af9eeacc6f6e0b32fec0e92d744cba293dac8356;hpb=fd7b0ae3e3cce6e083b344da6554f144d3130a6b;p=lilypond.git diff --git a/Documentation/notation/notation-appendices.itely b/Documentation/notation/notation-appendices.itely index af9eeacc6f..87b51c81c2 100644 --- a/Documentation/notation/notation-appendices.itely +++ b/Documentation/notation/notation-appendices.itely @@ -4,7 +4,8 @@ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH When revising a translation, copy the HEAD committish of the - version that you are working on. See TRANSLATION for details. + version that you are working on. For details, see the Contributors' + Guide, node Updating translation committishes.. @end ignore @c \version "2.12.0" @@ -45,7 +46,7 @@ and just before * Technical glossary:: * All context properties:: * Layout properties:: -* Identifiers:: +* Available music functions:: * Scheme functions:: @end menu @@ -212,11 +213,11 @@ Minor-major seventh @tab Minor triad, major seventh @tab -@code{maj7.5-} +@code{maj7.3-} @tab @lilypond[line-width=3\cm,noragged-right, notime] \chordmode { - c1:maj7.5- + c1:maj7.3- } @end lilypond @@ -408,10 +409,14 @@ Perfect fourth, perfect fifth @node Predefined fretboard diagrams @appendixsec Predefined fretboard diagrams -The chart below shows the predefined fretboard diagrams. +The chart below shows the predefined fretboard diagrams for guitar. @lilypondfile{display-predefined-fretboards.ly} +The chart below shows the predefined fretboard diagrams for ukulele. + +@lilypondfile{display-predefined-ukulele-fretboards.ly} + @node MIDI instruments @appendixsec MIDI instruments @@ -573,8 +578,11 @@ Where N is in the range 0-100. @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 @@ -864,6 +872,7 @@ The following styles may be used for note heads. @cindex organ pedal marks @cindex turn @cindex open +@cindex halfopen @cindex stopped @cindex flageolet @cindex reverseturn @@ -892,22 +901,43 @@ The following styles may be used for note heads. @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 @@ -921,6 +951,32 @@ layer. Callbacks are used extensively in LilyPond to permit 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 @@ -933,6 +989,13 @@ character, or a combination of two characters formating a ligature. A set of glyphs with a single style and shape comprise a font, and a set of fonts covering several styles and sizes comprise a typeface. + +@seealso +Notation Reference: +@ref{Fonts}, +@ref{Text encoding}. + + @node grob @unnumberedsubsec grob @@ -943,35 +1006,151 @@ a set of fonts covering several styles and sizes comprise a typeface. 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{Objects and interfaces}, +@rlearning{Naming conventions of objects and properties}, +@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 + +@cindex interface +@cindex grob-interface +@cindex graphical object interfaces + +Actions and properties which are common to a number of grobs are +grouped together in an object called a @code{grob-interface}, or +just @q{interface} for short. + +@seealso +Learning Manual: +@rlearning{Objects and interfaces}, +@rlearning{Naming conventions of objects and properties}, +@rlearning{Properties found in interfaces}. + +Notation Reference: +@ref{Layout interfaces}. + +Internals Reference: +@rinternals{Graphical Object Interfaces}. + @node lexer @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 -TODO + +@cindex output-def + +An instance of the @code{Output-def} class contains the methods and +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. @@ -1001,21 +1180,62 @@ LilyPond uses the following parser variables: @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 @@ -1030,8 +1250,8 @@ TODO @include layout-properties.tely -@node Identifiers -@appendixsec Identifiers +@node Available music functions +@appendixsec Available music functions @include identifiers.tely