From 232de3305dd5262822fd1e081ddd52581319f4ce Mon Sep 17 00:00:00 2001 From: Trevor Daniels Date: Sun, 25 Nov 2012 11:56:36 +0000 Subject: [PATCH] Doc: new syntax for \tweak, \override (2936) Also remove text saying spaces are required around the . in Lyric overrides --- Documentation/learning/tweaks.itely | 82 +++++++------------ .../notation/changing-defaults.itely | 61 +++++++------- Documentation/notation/input.itely | 12 +-- Documentation/notation/spacing.itely | 26 +++--- Documentation/notation/vocal.itely | 19 ----- 5 files changed, 78 insertions(+), 122 deletions(-) diff --git a/Documentation/learning/tweaks.itely b/Documentation/learning/tweaks.itely index 6cc699a898..1382f60393 100644 --- a/Documentation/learning/tweaks.itely +++ b/Documentation/learning/tweaks.itely @@ -197,8 +197,7 @@ how this is done. The general syntax of this command is: @example -\override @var{Context}.@var{LayoutObject} #'@var{layout-property} = -#@var{value} +\override @var{Context}.@var{LayoutObject}.@var{layout-property} = #@var{value} @end example @noindent @@ -206,25 +205,31 @@ This will set the property with the name @var{layout-property} of the layout object with the name @var{LayoutObject}, which is a member of the @var{Context} context, to the value @var{value}. -The @var{Context} can be omitted (and usually is) when the +The @var{Context} may be omitted (and usually is) when the required context is unambiguously implied and is one of lowest level contexts, i.e., @code{Voice}, @code{ChordNames} or @code{Lyrics}, and we shall omit it in many of the following examples. We shall see later when it must be specified. Later sections deal comprehensively with properties and their -values, see @ref{Types of properties}. But in this section we shall +values, see @ref{Types of properties}. But in this section we shall use just a few simple properties and values which are easily understood in order to illustrate the format and use of these commands. -For now, don't worry about the @code{#'}, which must precede the -layout property, and the@tie{}@code{#}, which must precede the value. -These must always be present in exactly this form. This is the -most common command used in tweaking, and most of the rest of -this chapter will be directed to presenting examples of how it is -used. Here is a simple example to change the color of the -note head: +LilyPond's primary expressions are musical items like notes, +durations, and markups. More basic expressions like numbers, +strings, and lists are processed in @q{Scheme mode}, which is +invoked by prefixing the value with @samp{#}. Although the +values may sometimes have a valid representation in LilyPond's +musical mode, this manual will always use @samp{#} for their +entry for the sake of consistency. For more information about +Scheme mode, see @rextend{LilyPond Scheme syntax}. + +@code{\override} is the most common command used in tweaking, and +most of the rest of this chapter will be directed to presenting +examples of how it is used. Here is a simple example to change the +color of the note head: @cindex color property, example @cindex NoteHead, example of overriding @@ -252,7 +257,7 @@ value; note, not its previous value if several @code{\override} commands have been issued. @example -\revert @var{Context}.@var{LayoutObject} #'@var{layout-property} +\revert @var{Context}.@var{LayoutObject}.@var{layout-property} @end example Again, just like @var{Context} in the @code{\override} command, @@ -371,7 +376,7 @@ also that an equals sign should not be present. So the simple form of the @code{\tweak} command is @example -\tweak #'@var{layout-property} #@var{value} +\tweak @var{layout-property} #@var{value} @end example A @code{\tweak} command can also be used to modify just one in @@ -404,12 +409,13 @@ the original event: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] <\tweak Accidental.color #red cis4 \tweak Accidental.color #green es - g> + g> @end lilypond This long form of the @code{\tweak} command can be described as + @example -\tweak @var{layout-object} #'@var{layout-property} @var{value} +\tweak @var{layout-object}.@var{layout-property} @var{value} @end example @cindex tuplets, nested @@ -455,8 +461,6 @@ appearance may be modified in the usual way with @cindex transparent property, example @cindex TupletNumber, example of overriding -@c NOTE Tuplet brackets collide if notes are high on staff -@c See issue 509 @lilypond[quote,ragged-right,verbatim,fragment,relative=1] \times 2/3 { c8[ c c] } \once \override TupletNumber.text = #tuplet-number::calc-fraction-text @@ -599,8 +603,7 @@ at first, so we can be sure the command is working. We get: \override Slur.thickness = #5.0 @end example -Don't forget the @code{#'} preceding the -property name and a@tie{}@code{#} preceding the new value! +Don't forget the@tie{}@code{#} preceding the new value! The final question is, @q{Where should this command be placed?} While you are unsure and learning, the best @@ -831,17 +834,12 @@ to change the lyrics to italics. The object is @code{LyricText}, the property is @code{font-shape} and the value is @code{italic}. As before, we'll omit the context. -As an aside, although it is an important one, note that because the -values of @code{font-shape} are symbols they must be introduced with a -single apostrophe, @code{'}. That is why apostrophes are needed -before @code{thickness} in the earlier example and @code{font-shape}. -These are both symbols too. Symbols are then read internally by -LilyPond. Some of them are the names of properties, like -@code{thickness} or @code{font-shape}, others are used as values that -can be given to properties, like @code{italic}. Note the distinction -from arbitrary text strings, which would appear as @code{"a text -string"}; for more details about symbols and strings, see -@rextend{Scheme tutorial}. +As an aside, although it is an important one, note that some +properties take values that are symbols, like @code{italic}, and +must be preceded by an apostrophe, @code{'}. Symbols are then +read internally by LilyPond. Note the distinction from arbitrary +text strings, which would appear as @code{"a text string"}; for +more details about symbols and strings, see @rextend{Scheme tutorial}. So we see that the @code{\override} command needed to print the lyrics in italics is: @@ -878,33 +876,9 @@ like so: @noindent and the lyrics are all printed in italics. -@subheading Specifying the context in lyric mode - -@cindex context, specifying in lyric mode -@cindex lyric mode, specifying context - -In the case of lyrics, if you try specifying the context in the -format given earlier the command will fail. A syllable -entered in lyricmode is terminated by either a space, -a newline or a digit. All other characters are included -as part of the syllable. For this reason a space or newline -must appear before the terminating @code{@}} to prevent it being -included as part of the final syllable. Similarly, -spaces must be inserted before and after the -period or dot, @q{.}, separating the context name from the -object name, as otherwise the two names are run together and -the interpreter cannot recognize them. So the command should be: - -@example -\override Lyrics.LyricText.font-shape = #'italic -@end example - @warning{In lyrics always leave whitespace between the final syllable and the terminating brace.} -@warning{In overrides in lyrics always place spaces around -the dot between the context name and the object name.} - @seealso Extending: @rextend{Scheme tutorial}. diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index 79467fbbc0..6eeb94eef9 100644 --- a/Documentation/notation/changing-defaults.itely +++ b/Documentation/notation/changing-defaults.itely @@ -1909,29 +1909,12 @@ association list. See @file{scm/define-grobs.scm} to see the settings for each grob description. Grob descriptions are modified with @code{\override}. -@code{\override} is actually a shorthand; +The syntax for the @code{\override} command is @example -\override @var{context}.@var{GrobName} #'@var{property} = #@var{value} +\override [@var{context}.]@var{GrobName}.@var{property} = #@var{value} @end example -@noindent -is more or less equivalent to - -@c leave this long line -gp -@example -\set @var{context}.@var{GrobName} = - #(cons (cons '@var{property} @var{value}) - ) -@end example - -The value of @code{context}.@code{GrobName} (the alist) is used to initialize -the properties of individual grobs. Grobs have -properties, named in Scheme style, with -@code{dashed-words}. The values of grob properties change -during the formatting process: formatting basically amounts -to computing properties using callback functions. - For example, we can increase the thickness of a note stem by overriding the @code{thickness} property of the @code{Stem} object: @@ -1959,11 +1942,33 @@ context is used: } @end lilypond +Some tweakable options are called @q{subproperties} and reside inside +properties. To tweak those, use commands in the form + +@example +\override Stem.details.beamed-lengths = #'(4 4 3) +@end example + +or to modify the ends of spanners, use a form like these + +@example +\override TextSpanner.bound-details.left.text = #"left text" +\override TextSpanner.bound-details.right.text = #"right text" +@end example + @funindex \revert @cindex reverting overrides @cindex overrides, reverting -The effects of @code{\override} can be undone by @code{\revert}: +The effects of @code{\override} can be undone by @code{\revert}. + +The syntax for the @code{\revert} command is + +@example +\revert [@var{context}.]@var{GrobName}.@var{property} +@end example + +For example, @lilypond[quote,verbatim,relative=2] c4 @@ -2031,13 +2036,6 @@ To construct this tweak we must determine these bits of information: @item a sensible value: here @code{3.0}. @end itemize -Some tweakable options are called @q{subproperties} and reside inside -properties. To tweak those, use commands in the form - -@example -\override Stem.details.beamed-lengths = #'(4 4 3) -@end example - @cindex internal documentation @cindex finding graphical objects @cindex graphical object descriptions @@ -2074,7 +2072,7 @@ accomplished with the @code{\tweak} command, which has the following syntax: @example -\tweak @var{layout-object} #'@var{grob-property} @var{value} +\tweak [@var{layout-object}.]@var{grob-property} @var{value} @end example Specifying @var{layout-object} is optional. @@ -2101,7 +2099,7 @@ For example: -But the main use of the @code{\tweak} command is to modify just +The main use of the @code{\tweak} command is to modify just one of a number of notation elements which start at the same musical moment, like the notes of a chord, or tuplet brackets which start at the same time. @@ -2196,8 +2194,9 @@ beams or accidentals, since these are generated later by @code{NoteHead} layout objects rather than by music elements in the input stream. -Such indirectly created layout objects can be tweaked using the explicit -form of the @code{\tweak} command: +Such indirectly created layout objects can be tweaked using the form +of the @code{\tweak} command in which the grob name is specified +explicitly: @lilypond[relative=2,verbatim,quote] \tweak Stem.color #red diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely index 9de53e0190..74766a52f6 100644 --- a/Documentation/notation/input.itely +++ b/Documentation/notation/input.itely @@ -493,17 +493,19 @@ However, whitespace should always be used in the following circumstances to avoid errors: @itemize + @item Around every opening and closing curly bracket. + @item After every command or variable, i.e. every item that begins with a @code{\} sign. + @item After every item that is to be interpreted as a Scheme expression, i.e. every item that begins with a @code{#}@tie{}sign. + @item To separate all elements of a Scheme expression. -@item In @code{lyricmode} to separate all the terms in both -@code{\override} and @code{\set} commands. In particular, spaces -must be used around the dot and the equals sign in commands like -@code{\override Score.LyricText.font-size = #5} and before and -after the entire command. + +@item In @code{lyricmode} before and after @code{\set} and +@code{\override} commands. @end itemize diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely index a318ed4cee..8352e5a8be 100644 --- a/Documentation/notation/spacing.itely +++ b/Documentation/notation/spacing.itely @@ -1169,7 +1169,7 @@ layoutVariable = \layout @{ @end example it will hold the current @code{\layout} configuration with the -@code{NoteHead #'font-size} override added, but this combination +@code{NoteHead.font-size} override added, but this combination is @emph{not} saved as the new current configuration. Be aware that the @q{current configuration} is read when the variable is defined and not when it is used, so the content of the variable @@ -1201,11 +1201,11 @@ use of @code{\layoutVariable} the final @code{\layout} block would consist of: @example - TextScript #'padding = #1 - TextScript #'color = #magenta - Glissando #'thickness = #1.5 - NoteHead #' font-size = #4 - NoteHead #' color = #red + TextScript.padding = #1 + TextScript.color = #magenta + Glissando.thickness = #1.5 + NoteHead.font-size = #4 + NoteHead.color = #red @end example plus the @code{indent} and the @code{StaffGrouper} overrides. @@ -1215,8 +1215,8 @@ But if the variable had already been defined before the first only @example - NoteHead #' font-size= #4 % (written in the variable definition) - NoteHead #' color = #red % (added after the use of the variable) + NoteHead.font-size = #4 % (written in the variable definition) + NoteHead.color = #red % (added after the use of the variable) @end example If carefully planned, @code{\layout} variables can be a valuable tool @@ -2415,12 +2415,12 @@ explained above is as a collection of settings that control the amount of vertical padding between staves and systems. It is possible to approach vertical spacing in a different way -using @code{NonMusicalPaperColumn #'line-break-system-details}. +using @code{NonMusicalPaperColumn.line-break-system-details}. While the flexible vertical spacing mechanisms specify vertical -padding, @code{NonMusicalPaperColumn #'line-break-system-details} +padding, @code{NonMusicalPaperColumn.line-break-system-details} can specify exact vertical positions on the page. -@code{NonMusicalPaperColumn #'line-break-system-details} accepts +@code{NonMusicalPaperColumn.line-break-system-details} accepts an associative list of three different settings: @itemize @@ -2613,7 +2613,7 @@ do not count as a staff. of the distance between adjacent staff lines. Positive values move staves and lyrics up, negative values move staves and lyrics down. -@item Because the @code{NonMusicalPaperColumn #'line-break-system-details} +@item Because the @code{NonMusicalPaperColumn.line-break-system-details} settings given here allow the positioning of staves and systems anywhere on the page, it is possible to violate paper or margin boundaries or even to print staves or systems on top of one another. Reasonable values @@ -2914,7 +2914,7 @@ than @code{1 16}. By default, spacing in tuplets depends on various non-duration factors (such as accidentals, clef changes, etc). To disregard such symbols and force uniform equal-duration spacing, use -@code{Score.SpacingSpanner #'uniform-stretching}. This +@code{Score.SpacingSpanner.uniform-stretching}. This property can only be changed at the beginning of a score, @lilypond[quote,ragged-right,verbatim] diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely index 219cfb6fd4..c0b74d2ba9 100644 --- a/Documentation/notation/vocal.itely +++ b/Documentation/notation/vocal.itely @@ -149,25 +149,6 @@ compile. Instead, braces should always be surrounded with white space: \lyricmode @{ lah lah lah @} @end example -@cindex overrides in lyric mode -@funindex \override in \lyricmode - -Similarly, in lyric mode, a period will be included in the -alphabetic sequence that it follows. As a consequence, spaces -must be inserted around the period in @code{\override} commands. -Do @emph{not} write - -@example -\override Score.LyricText.font-shape = #'italic -@end example - -@noindent -but instead use - -@example -\override Score.LyricText.font-shape = #'italic -@end example - Punctuation, lyrics with accented characters, characters from non-English languages, or special characters (such as the heart symbol or slanted quotes), may simply be inserted directly -- 2.39.2