X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fnotation-appendices.itely;h=6b58d17b656dd69d4785a64e42d452e0c8d725a4;hb=56c9f1f640a7946117d01f123464d1dafb3a29f1;hp=af9eeacc6f6e0b32fec0e92d744cba293dac8356;hpb=ee7ca91ef74b9d17aad3b6927c5dfb217e94cc5c;p=lilypond.git

diff --git a/Documentation/notation/notation-appendices.itely b/Documentation/notation/notation-appendices.itely
index af9eeacc6f..6b58d17b65 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,8 @@ and just before
 * Technical glossary::
 * All context properties::
 * Layout properties::
-* Identifiers::
+* Available music functions::
+* Predefined type predicates::
 * Scheme functions::
 @end menu
 
@@ -212,11 +214,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,15 +410,21 @@ 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
 
 The following is a list of names that can be used for the
-@code{midiInstrument} property.
+@code{midiInstrument} property.  The order of the instruments
+below, starting in the left-hand column moving down, corresponds
+to the General MIDI Standard's 128 Program Numbers.
 
 @example
 acoustic grand            contrabass           lead 7 (fifths)
@@ -573,8 +581,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
@@ -849,38 +860,124 @@ The following styles may be used for note heads.
 @node List of articulations
 @appendixsec List of articulations
 
+
 @cindex accent
-@cindex marcato
-@cindex staccatissimo
+@cindex accentus
+@cindex circulus
+@cindex coda
+@cindex downbow
+@cindex downmordent
+@cindex downprall
 @cindex espressivo
 @cindex fermata
-@cindex stopped
-@cindex staccato
-@cindex portato
-@cindex tenuto
-@cindex upbow
-@cindex downbow
-@cindex foot marks
-@cindex organ pedal marks
-@cindex turn
-@cindex open
-@cindex stopped
 @cindex flageolet
-@cindex reverseturn
-@cindex trill
-@cindex prall
+@cindex halfopen
+@cindex ictus
+@cindex lheel
+@cindex lineprall
+@cindex longfermata
+@cindex ltoe
+@cindex marcato
 @cindex mordent
-@cindex prallprall
+@cindex open
+@cindex portato
+@cindex prall
+@cindex pralldown
 @cindex prallmordent
-@cindex prall, up
-@cindex prall, down
-@cindex thumb marking
+@cindex prallprall
+@cindex prallup
+@cindex reverseturn
+@cindex rheel
+@cindex rtoe
 @cindex segno
-@cindex coda
+@cindex semicirculus
+@cindex shortfermata
+@cindex signumcongruentiae
+@cindex snappizzicato
+@cindex staccatissimo
+@cindex staccato
+@cindex stopped
+@cindex tenuto
+@cindex thumb
+@cindex trill
+@cindex turn
+@cindex upbow
+@cindex upmordent
+@cindex upprall
 @cindex varcoda
+@cindex verylongfermata
+
+The following scripts are available in the Feta font and may be
+attached to notes (eg. @samp{c\accent}).
+
+@c Articulations and ornamentations
+@c Fingering instructions (for "thumb")
+@c Common notation for unfretted strings
+@c   Bowing indications
+@c   Harmonics
+@c   Snap (Bartók) pizzicato
+@c Custom percussion staves (for "halfopen" -- not yet funindexed)
+@c References for wind instruments (for "open"/"stopped" -- not yet funindexed)
+
+
+@menu
+* Articulation scripts::
+* Ornament scripts::
+* Fermata scripts::
+* Instrument-specific scripts::
+* Repeat sign scripts::
+* Ancient scripts::
+@end menu
+
+
+@node Articulation scripts
+@unnumberedsubsec Articulation scripts
+
+@lilypond[quote]
+\include "script-chart.ly"
+\new RhythmicStaff { \scriptStaff #articulations }
+@end lilypond
+
+@node Ornament scripts
+@unnumberedsubsec Ornament scripts
+
+@lilypond[quote]
+\include "script-chart.ly"
+\new RhythmicStaff { \scriptStaff #ornaments }
+@end lilypond
+
+@node Fermata scripts
+@unnumberedsubsec Fermata scripts
+
+@lilypond[quote]
+\include "script-chart.ly"
+\new RhythmicStaff { \scriptStaff #fermatas }
+@end lilypond
+
+@node Instrument-specific scripts
+@unnumberedsubsec Instrument-specific scripts
+
+@lilypond[quote]
+\include "script-chart.ly"
+\new RhythmicStaff { \scriptStaff #instrument-specific }
+@end lilypond
+
+@node Repeat sign scripts
+@unnumberedsubsec Repeat sign scripts
 
+@lilypond[quote]
+\include "script-chart.ly"
+\new RhythmicStaff { \scriptStaff #repeats }
+@end lilypond
 
-@lilypondfile[quote,texidoc]{script-chart.ly}
+@node Ancient scripts
+@unnumberedsubsec Ancient scripts
+
+@lilypond[quote]
+\include "script-chart.ly"
+\include "gregorian.ly"
+\new VaticanaStaff { \scriptStaffAncient #ancient }
+@end lilypond
 
 
 @node Percussion notes
@@ -892,22 +989,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 +1039,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 +1077,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 +1094,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 +1268,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,12 +1338,18 @@ TODO
 @include layout-properties.tely
 
 
-@node Identifiers
-@appendixsec Identifiers
+@node Available music functions
+@appendixsec Available music functions
 
 @include identifiers.tely
 
 
+@node Predefined type predicates
+@appendixsec Predefined type predicates
+
+@include type-predicates.tely
+
+
 @node Scheme functions
 @appendixsec Scheme functions