X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fnotation-appendices.itely;h=30756c9d2fc00e682e4b0047b7e534fd04aae366;hb=2ccb49133730ac1e98c7068e884297f3246aaf3b;hp=af9eeacc6f6e0b32fec0e92d744cba293dac8356;hpb=794dcbdb52faf4292036cd1b0270a956cf4316a3;p=lilypond.git diff --git a/Documentation/notation/notation-appendices.itely b/Documentation/notation/notation-appendices.itely index af9eeacc6f..30756c9d2f 100644 --- a/Documentation/notation/notation-appendices.itely +++ b/Documentation/notation/notation-appendices.itely @@ -4,48 +4,36 @@ 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" +@c \version "2.15.17" @node Notation manual tables @appendix Notation manual tables -@c Please do not delete the following @ignore block. -@ignore -Note for editors and translators: In the following menu, two entries -are needed to link to a pair of automatically generated sections. -Please keep them and, if using emacs, do not run -texinfo-all-menus-update without manually restoring them back. These -menu entries are: - -* Text markup commands:: -* Text markup list commands:: - -and they should go just after -* Note head styles:: - -and just before -* List of articulations:: -@end ignore - @menu * Chord name chart:: * Common chord modifiers:: +* Predefined string tunings:: * Predefined fretboard diagrams:: +* Predefined paper sizes:: * MIDI instruments:: * List of colors:: * The Feta font:: * Note head styles:: * Text markup commands:: * Text markup list commands:: +* List of special characters:: * List of articulations:: * Percussion notes:: * Technical glossary:: * All context properties:: * Layout properties:: -* Identifiers:: +* Available music functions:: +* Context modification identifiers:: +* Predefined type predicates:: * Scheme functions:: @end menu @@ -54,7 +42,7 @@ and just before @node Chord name chart @appendixsec Chord name chart -The following charts shows two standard systems for printing chord +The following chart shows two standard systems for printing chord names, along with the pitches they represent. @lilypondfile{chord-names-jazz.ly} @@ -212,11 +200,11 @@ Minor-major seventh @tab Minor triad, major seventh @tab -@code{maj7.5-} +@code{m7+} @tab @lilypond[line-width=3\cm,noragged-right, notime] \chordmode { - c1:maj7.5- + c1:m7+ } @end lilypond @@ -402,21 +390,318 @@ Perfect fourth, perfect fifth } @end lilypond +@item +Power chord (two-voiced) +@tab +Perfect fifth +@tab +@code{1.5} +@tab +@lilypond[line-width=3\cm,noragged-right, notime] +\chordmode { + \powerChords + c1:1.5 +} +@end lilypond + +@item +Power chord (three-voiced) +@tab +Perfect fifth, octave +@tab +@code{1.5.8} +@tab +@lilypond[line-width=3\cm,noragged-right, notime] +\chordmode { + \powerChords + c1:1.5.8 +} +@end lilypond @end multitable +@node Predefined string tunings +@appendixsec Predefined string tunings + +The chart below shows the predefined string tunings. + +@lilypondfile{display-predefined-string-tunings.ly} + @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} + +The chart below shows the predefined fretboard diagrams for mandolin. + +@lilypondfile{display-predefined-mandolin-fretboards.ly} + + +@node Predefined paper sizes +@appendixsec Predefined paper sizes + +Paper sizes are defined in @file{scm/paper.scm} + +@noindent +@strong{The @qq{ISO 216} A Series} +@table @code +@item "a10" +(26 x 37 mm) +@item "a9" +(37 x 52 mm) +@item "a8" +(52 x 74 mm) +@item "a7" +(74 x 105 mm) +@item "a6" +(105 x 148 mm) +@item "a5" +(148 x 210 mm) +@item "a4" +(210 x 297 mm) +@item "a3" +(297 x 420 mm) +@item "a2" +(420 x 594 mm) +@item "a1" +(594 x 841 mm) +@item "a0" +(841 x 1189 mm) +@end table + +@noindent +@strong{The @qq{ISO 216} B Series} +@table @code +@item "b10" +(31 x 44 mm) +@item "b9" +(44 x 62 mm) +@item "b8" +(62 x 88 mm) +@item "b7" +(88 x 125 mm) +@item "b6" +(125 x 176 mm) +@item "b5" +(176 x 250 mm) +@item "b4" +(250 x 353 mm) +@item "b3" +(353 x 500 mm) +@item "b2" +(500 x 707 mm) +@item "b1" +(707 x 1000 mm) +@item "b0" +(1000 x 1414 mm) +@end table + +@noindent +@strong{Two extended sizes as defined in @qq{DIN 476}} +@table @code +@item "4a0" +(1682 x 2378 mm) +@item "2a0" +(1189 x 1682 mm) +@end table + +@noindent +@strong{@qq{ISO 269} standard C series} +@table @code +@item "c10" +(28 x 40 mm) +@item "c9" +(40 x 57 mm) +@item "c8" +(57 x 81 mm) +@item "c7" +(81 x 114 mm) +@item "c6" +(114 x 162 mm) +@item "c5" +(162 x 229 mm) +@item "c4" +(229 x 324 mm) +@item "c3" +(324 x 458 mm) +@item "c2" +(458 x 648 mm) +@item "c1" +(648 x 917 mm) +@item "c0" +(917 x 1297 mm) +@end table + +@noindent +@strong{North American paper sizes} +@table @code +@item "junior-legal" +(8.0 x 5.0 in) +@item "legal" +(8.5 x 14.0 in) +@item "ledger" +(17.0 x 11.0 in) +@item "letter" +(8.5 x 11.0 in) +@item "tabloid" +(11.0 x 17.0 in) +@item "11x17" +(11.0 x 17.0 in) +@item "17x11" +(17.0 x 11.0 in) +@end table + +@noindent +@strong{Government-letter by IEEE Printer Working Group, for children's +writing} +@table @code +@item "government-letter" +(8 x 10.5 in) +@item "government-legal" +(8.5 x 13.0 in) +@item "philippine-legal" +(8.5 x 13.0 in) +@end table + +@noindent +@strong{ANSI sizes} +@table @code +@item "ansi a" +(8.5 x 11.0 in) +@item "ansi b" +(17.0 x 11.0 in) +@item "ansi c" +(17.0 x 22.0 in) +@item "ansi d" +(22.0 x 34.0 in) +@item "ansi e" +(34.0 x 44.0 in) +@item "engineering f" +(28.0 x 40.0 in) +@end table + +@noindent +@strong{North American Architectural sizes} +@table @code +@item "arch a" +(9.0 x 12.0 in) +@item "arch b" +(12.0 x 18.0 in) +@item "arch c" +(18.0 x 24.0 in) +@item "arch d" +(24.0 x 36.0 in) +@item "arch e" +(36.0 x 48.0 in) +@item "arch e1" +(30.0 x 42.0 in) +@end table + +@noindent +@strong{Antique sizes still used in the United Kingdom} +@table @code +@item "statement" +(5.5 x 8.5 in) +@item "half letter" +(5.5 x 8.5 in) +@item "quarto" +(8.0 x 10.0 in) +@item "octavo" +(6.75 x 10.5 in) +@item "executive" +(7.25 x 10.5 in) +@item "monarch" +(7.25 x 10.5 in) +@item "foolscap" +(8.27 x 13.0 in) +@item "folio" +(8.27 x 13.0 in) +@item "super-b" +(13.0 x 19.0 in) +@item "post" +(15.5 x 19.5 in) +@item "crown" +(15.0 x 20.0 in) +@item "large post" +(16.5 x 21.0 in) +@item "demy" +(17.5 x 22.5 in) +@item "medium" +(18.0 x 23.0 in) +@item "broadsheet" +(18.0 x 24.0 in) +@item "royal" +(20.0 x 25.0 in) +@item "elephant" +(23.0 x 28.0 in) +@item "double demy" +(22.5 x 35.0 in) +@item "quad demy" +(35.0 x 45.0 in) +@item "atlas" +(26.0 x 34.0 in) +@item "imperial" +(22.0 x 30.0 in) +@item "antiquarian" +(31.0 x 53.0 in) +@end table + +@noindent +@strong{PA4 based sizes} +@table @code +@item "pa0" +(840 x 1120 mm) +@item "pa1" +(560 x 840 mm) +@item "pa2" +(420 x 560 mm) +@item "pa3" +(280 x 420 mm) +@item "pa4" +(210 x 280 mm) +@item "pa5" +(140 x 210 mm) +@item "pa6" +(105 x 140 mm) +@item "pa7" +(70 x 105 mm) +@item "pa8" +(52 x 70 mm) +@item "pa9" +(35 x 52 mm) +@item "pa10" +(26 x 35 mm) +@end table + +@noindent +@strong{Used in Southeast Asia and Australia} +@table @code +@item "f4" +(210 x 330 mm) +@end table + +@noindent +@strong{Used for very small @code{@@lilypond} examples in the +documentation based on a8 landscape.} +@table @code +@item "a8landscape" +(74 x 52 mm) +@end table + + @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 +858,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 @@ -594,6 +882,7 @@ accessed directly using text markup such as @code{g^\markup @{ * Bracket-tip glyphs:: * Pedal glyphs:: * Accordion glyphs:: +* Tie glyphs:: * Vaticana glyphs:: * Medicaea glyphs:: * Hufnagel glyphs:: @@ -601,6 +890,7 @@ accessed directly using text markup such as @code{g^\markup @{ * Neomensural glyphs:: * Petrucci glyphs:: * Solesmes glyphs:: +* Kievan Notation glyphs:: @end menu @@ -609,8 +899,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #clefs +\markuplist \override-lines #'(word-space . 4) + \doc-chars #clefs @end lilypond @@ -619,8 +909,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #timesig +\markuplist \override-lines #'(word-space . 4) + \doc-chars #timesig @end lilypond @@ -629,8 +919,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #numbers +\markuplist \override-lines #'(word-space . 4) + \doc-chars #numbers @end lilypond @@ -639,8 +929,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #accidentals +\markuplist \override-lines #'(word-space . 4) + \doc-chars #accidentals @end lilypond @@ -649,8 +939,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #default-noteheads +\markuplist \override-lines #'(word-space . 4) + \doc-chars #default-noteheads @end lilypond @@ -659,8 +949,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #special-noteheads +\markuplist \override-lines #'(word-space . 4) + \doc-chars #special-noteheads @end lilypond @@ -669,8 +959,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #shape-note-noteheads +\markuplist \override-lines #'(word-space . 4) + \doc-chars #shape-note-noteheads @end lilypond @@ -679,8 +969,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #rests +\markuplist \override-lines #'(word-space . 4) + \doc-chars #rests @end lilypond @@ -689,8 +979,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #flags +\markuplist \override-lines #'(word-space . 4) + \doc-chars #flags @end lilypond @@ -699,8 +989,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #dots +\markuplist \override-lines #'(word-space . 4) + \doc-chars #dots @end lilypond @@ -709,8 +999,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #dynamics +\markuplist \override-lines #'(word-space . 4) + \doc-chars #dynamics @end lilypond @@ -719,8 +1009,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #scripts +\markuplist \override-lines #'(word-space . 4) + \doc-chars #scripts @end lilypond @@ -729,8 +1019,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #arrowheads +\markuplist \override-lines #'(word-space . 4) + \doc-chars #arrowheads @end lilypond @@ -739,8 +1029,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #brackettips +\markuplist \override-lines #'(word-space . 4) + \doc-chars #brackettips @end lilypond @@ -749,8 +1039,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #pedal +\markuplist \override-lines #'(word-space . 4) + \doc-chars #pedal @end lilypond @@ -759,8 +1049,18 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #accordion +\markuplist \override-lines #'(word-space . 4) + \doc-chars #accordion +@end lilypond + + +@node Tie glyphs +@unnumberedsubsec Tie glyphs + +@lilypond[quote] +\include "font-table.ly" +\markuplist \override-lines #'(word-space . 4) + \doc-chars #ties @end lilypond @@ -769,8 +1069,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #vaticana +\markuplist \override-lines #'(word-space . 4) + \doc-chars #vaticana @end lilypond @@ -779,8 +1079,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #medicaea +\markuplist \override-lines #'(word-space . 4) + \doc-chars #medicaea @end lilypond @@ -789,8 +1089,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #hufnagel +\markuplist \override-lines #'(word-space . 4) + \doc-chars #hufnagel @end lilypond @@ -799,8 +1099,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #mensural +\markuplist \override-lines #'(word-space . 4) + \doc-chars #mensural @end lilypond @@ -809,8 +1109,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #neomensural +\markuplist \override-lines #'(word-space . 4) + \doc-chars #neomensural @end lilypond @@ -819,8 +1119,8 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #petrucci +\markuplist \override-lines #'(word-space . 4) + \doc-chars #petrucci @end lilypond @@ -829,10 +1129,18 @@ accessed directly using text markup such as @code{g^\markup @{ @lilypond[quote] \include "font-table.ly" -\markuplines \override-lines #'(word-space . 4) - \doc-chars #solesmes +\markuplist \override-lines #'(word-space . 4) + \doc-chars #solesmes @end lilypond +@node Kievan Notation glyphs +@unnumberedsubsec Kievan Notation glyphs + +@lilypond[quote] +\include "font-table.ly" +\markuplist \override-lines #'(word-space . 4) + \doc-chars #kievan +@end lilypond @node Note head styles @appendixsec Note head styles @@ -842,45 +1150,160 @@ The following styles may be used for note heads. @lilypondfile[noindent]{note-head-style.ly} + +@node Text markup commands +@appendixsec Text markup commands + @include markup-commands.tely + +@node Text markup list commands +@appendixsec Text markup list commands + +The following commands can all be used with @code{\markuplist}: + @include markup-list-commands.tely + +@node List of special characters +@appendixsec List of special characters + +The following special characters references can be used; +for more details, see @ref{ASCII aliases}. + +The HTML syntax is used and most of these references are the same as HTML. +The rest of them are inspired by @LaTeX{}. + +The characters are boxed so that you can see their size. +A small padding has been added between the character and the box +for more readability. + +@lilypond[quote] +\include "special-characters.ly" +@end lilypond + + @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) -@lilypondfile[quote,texidoc]{script-chart.ly} + +@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 + +@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 +1315,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 +1365,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 +1403,12 @@ 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{Special characters}. + + @node grob @unnumberedsubsec grob @@ -943,40 +1419,158 @@ 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. -When the value of such a variable is changed in a @code{.ly} file, +When the value of such a variable is changed in a @file{.ly} file, the change is global, and unless explicitly reverted, the new value will persist to the end of the file, affecting subsequent @code{\score} blocks as well as external files added with the @@ -1001,21 +1595,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,11 +1665,24 @@ TODO @include layout-properties.tely -@node Identifiers -@appendixsec Identifiers +@node Available music functions +@appendixsec Available music functions @include identifiers.tely +@node Context modification identifiers +@appendixsec Context modification identifiers + +The following commands are defined for use as context modifications +within a @code{\layout} or @code{\with} block. + +@include context-mod-identifiers.tely + +@node Predefined type predicates +@appendixsec Predefined type predicates + +@include type-predicates.tely + @node Scheme functions @appendixsec Scheme functions