Markup command documentation: categories and properties

[lilypond.git] / Documentation / user / editorial.itely

diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely
index 43d4b8ad3db0e5a779d141a690e42480d8c03a21..dda447e28eab2a85d3b050b07ba0429f0cd5377e 100644 (file)
--- a/Documentation/user/editorial.itely
+++ b/Documentation/user/editorial.itely
@@ -6,6 +6,8 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

+@c \version "2.11.38"
+

 @node Editorial annotations
 @section Editorial annotations
 
 @node Editorial annotations
 @section Editorial annotations
 


@@ -38,13 +40,15 @@ inside the staff.
 @node Selecting notation font size
 @unnumberedsubsubsec Selecting notation font size
 
 @node Selecting notation font size
 @unnumberedsubsubsec Selecting notation font size
 

-@cindex font size
-@cindex font size, selecting
-@cindex selecting font size
+@cindex font size (notation)
+@cindex selecting font size (notation)

 
 The font size of notation elements may be altered.  It does not
 change the size of variable symbols, such as beams or slurs.
 
 
 The font size of notation elements may be altered.  It does not
 change the size of variable symbols, such as beams or slurs.
 

+@warning{For font sizes of text, see
+@ref{Common markup commands}.}
+

 @lilypond[quote,fragment,relative=2,verbatim,ragged-right]
 \huge
 c4.-> d8---3
 @lilypond[quote,fragment,relative=2,verbatim,ragged-right]
 \huge
 c4.-> d8---3


@@ -56,18 +60,18 @@ c4.-> d8---3
 c4.-> d8---3
 \tiny
 c4.-> d8---3
 c4.-> d8---3
 \tiny
 c4.-> d8---3

-\normalsize
-c2
+\teeny
+c4.-> d8---3

 @end lilypond
 
 @end lilypond
 

-@cindex font size scaling
+@cindex font size (notation) scaling

 
 

-Internally, this sets the @code{fontSize} property.  This in turns
+Internally, this sets the @code{fontSize} property.  This in turn

 causes the @code{font-size} property to be set in all layout
 objects.  The value of @code{font-size} is a number indicating the
 size relative to the standard size for the current staff height.
 Each step up is an increase of approximately 12% of the font size.
 causes the @code{font-size} property to be set in all layout
 objects.  The value of @code{font-size} is a number indicating the
 size relative to the standard size for the current staff height.
 Each step up is an increase of approximately 12% of the font size.

-Six steps is exactly a factor two.  The Scheme function
+Six steps is exactly a factor of two.  The Scheme function

 @code{magstep} converts a @code{font-size} number to a scaling
 factor.  The @code{font-size} property can also be set directly,
 so that only certain layout objects are affected.
 @code{magstep} converts a @code{font-size} number to a scaling
 factor.  The @code{font-size} property can also be set directly,
 so that only certain layout objects are affected.


@@ -83,12 +87,12 @@ c4.-> d8---3
 c4.-> d8---3
 @end lilypond
 
 c4.-> d8---3
 @end lilypond
 

-@cindex standard font size
-@cindex font size, standard
+@cindex standard font size (notation)
+@cindex font size (notation), standard

 
 Font size changes are achieved by scaling the design size that is
 closest to the desired size.  The standard font size (for
 
 Font size changes are achieved by scaling the design size that is
 closest to the desired size.  The standard font size (for

-@code{font-size} equals 0), depends on the standard staff height.
+@code{font-size = #0}) depends on the standard staff height.

 For a 20pt staff, a 10pt font is selected.
 
 The @code{font-size} property can only be set on layout objects
 For a 20pt staff, a 10pt font is selected.
 
 The @code{font-size} property can only be set on layout objects


@@ -97,6 +101,8 @@ that use fonts.  These are the ones supporting the
 
 @predefined
 
 
 @predefined
 

+@funindex \teeny
+@code{\teeny},

 @funindex \tiny
 @code{\tiny},
 @funindex \small
 @funindex \tiny
 @code{\tiny},
 @funindex \small


@@ -114,6 +120,8 @@ Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference:

+@internalsref{fontSize},
+@internalsref{font-size},

 @internalsref{font-interface}.
 
 
 @internalsref{font-interface}.
 
 


@@ -138,8 +146,8 @@ c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
 
 @cindex thumb-script
 
 
 @cindex thumb-script
 

-You can use the thumb-script (e.g., in cello music)to indicate that a 
-note should be played with the thumb. 
+A thumb-script can be added (e.g., in cello music) to indicate
+that a note should be played with the thumb. 

 
 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 <a_\thumb a'-3>2 <b_\thumb b'-3>
 
 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 <a_\thumb a'-3>2 <b_\thumb b'-3>


@@ -152,7 +160,7 @@ Fingerings for chords can also be added to individual notes of the
 chord by adding them after the pitches.
 
 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 chord by adding them after the pitches.
 
 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]

-< c-1 e-2 g-3 b-5 >2 < d-1 f-2 a-3 c-5 >
+<c-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>

 @end lilypond
 
 Fingering instructions may be manually placed above or below the
 @end lilypond
 
 Fingering instructions may be manually placed above or below the


@@ -173,15 +181,19 @@ Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference:

+@internalsref{FingeringEvent},
+@internalsref{fingering-event},
+@internalsref{Fingering_engraver},
+@internalsref{New_fingering_engraver},

 @internalsref{Fingering}.
 
 
 @node Hidden notes
 @unnumberedsubsubsec Hidden notes
 
 @internalsref{Fingering}.
 
 
 @node Hidden notes
 @unnumberedsubsubsec Hidden notes
 

-@cindex Hidden notes
-@cindex Invisible notes
-@cindex Transparent notes
+@cindex hidden notes
+@cindex invisible notes
+@cindex transparent notes

 @funindex \hideNotes
 @funindex \unHideNotes
 
 @funindex \hideNotes
 @funindex \unHideNotes
 


@@ -200,8 +212,20 @@ b
 c
 @end lilypond
 
 c
 @end lilypond
 

+Notation objects which are attached to invisible notes are still
+visible.
+
+@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+c4( d)
+\hideNotes
+e4(\p f)--
+@end lilypond
+
+

 @predefined
 
 @predefined
 

+@funindex \hideNotes
+@funindex \unHideNotes

 @code{\hideNotes}, @code{\unHideNotes}
 
 @seealso
 @code{\hideNotes}, @code{\unHideNotes}
 
 @seealso


@@ -209,6 +233,10 @@ c
 Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 

+Internals Reference:
+@internalsref{Note_spacing_engraver},
+@internalsref{NoteSpacing}.
+

 
 @node Coloring objects
 @unnumberedsubsubsec Coloring objects
 
 @node Coloring objects
 @unnumberedsubsubsec Coloring objects


@@ -220,8 +248,8 @@ Snippets:
 @cindex coloring notes
 @cindex notes, colored
 
 @cindex coloring notes
 @cindex notes, colored
 

-Individual objects may be assigned colors.  You may use the color
-names listed in the @ref{List of colors}.
+Individual objects may be assigned colors.  Valid color names
+are listed in the @ref{List of colors}.

 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \override NoteHead #'color = #red
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \override NoteHead #'color = #red


@@ -262,7 +290,8 @@ gis a
 b2 cis
 @end lilypond
 
 b2 cis
 @end lilypond
 

-You can get exact RGB colors by specifying the rgb-color number.
+Exact RGB colors can be specified using the Scheme function
+@code{rgb-color}.

 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \override Staff.StaffSymbol #'color = #(x11-color 'SlateBlue2)


@@ -270,13 +299,10 @@ You can get exact RGB colors by specifying the rgb-color number.
   \with-color #(x11-color 'navy) "Clarinet"
 }
   
   \with-color #(x11-color 'navy) "Clarinet"
 }
   

-%black

 \override Stem #'color = #(rgb-color 0 0 0)
 gis8 a
 \override Stem #'color = #(rgb-color 0 0 0)
 gis8 a

-% white

 \override Stem #'color = #(rgb-color 1 1 1)
 gis8 a
 \override Stem #'color = #(rgb-color 1 1 1)
 gis8 a

-% dark blue

 \override Stem #'color = #(rgb-color 0 0 0.5) 
 gis4 a
 @end lilypond
 \override Stem #'color = #(rgb-color 0 0 0.5) 
 gis4 a
 @end lilypond


@@ -291,12 +317,13 @@ Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 
 @knownissues
 @lsrdir{Editorial,Editorial-annotations}.
 
 @knownissues

-An x11 color is not necessarily exactly the same shade as a
+An X11 color is not necessarily exactly the same shade as a

 similarly named normal color.  
 
 similarly named normal color.  
 

-Not all x11 colors are distinguishable in a web browser i.e. a web browser
-might not display a difference between 'LimeGreen and 'ForestGreen.  For 
-web use normal colors are recommended (i.e. #blue, #green, #red).
+Not all X11 colors are distinguishable in a web browser, i.e.,
+a web browser might not display a difference between @code{'LimeGreen}
+and @code{'ForestGreen}.  For web use normal colors are recommended
+(i.e., @code{#blue}, @code{#green}, @code{#red}).

 
 
 Notes in a chord cannot be colored with @code{\override}; use
 
 
 Notes in a chord cannot be colored with @code{\override}; use


@@ -312,18 +339,20 @@ Notes in a chord cannot be colored with @code{\override}; use
 @cindex parentheses
 
 Objects may be parenthesized by prefixing @code{\parenthesize} to
 @cindex parentheses
 
 Objects may be parenthesized by prefixing @code{\parenthesize} to

-the music event.  This only functions inside chords; to
-parenthesize a single note it must be enclosed with @code{<>} as
-if it is a chord.
+the music event.  When prefixed to a chord, it parenthesizes every
+note.  Individual notes inside a chord may also be parenthesized.

 
 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
 
 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]

-c2 < \parenthesize d>
+c2 \parenthesize d
+c2 \parenthesize <c e g>
+c2 <c \parenthesize e g>

 @end lilypond
 
 Non-note objects may be parenthesized as well.
 
 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]
 @end lilypond
 
 Non-note objects may be parenthesized as well.
 
 @lilypond[quote,relative=2,fragment,verbatim,ragged-right]

-< c d g >2-\parenthesize -. d
+c2-\parenthesize -. d
+c2 \parenthesize r

 @end lilypond
 
 @seealso
 @end lilypond
 
 @seealso


@@ -331,9 +360,16 @@ Non-note objects may be parenthesized as well.
 Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 

+Internals Reference:
+@internalsref{Parenthesis_engraver},
+@internalsref{ParenthesesItem},
+@internalsref{parentheses-interface}.
+

 @knownissues
 
 @knownissues
 

-Rests cannot be parenthesized.
+Parenthesizing a chord prints parentheses around each individual
+note, instead of a single large parenthesis around the entire
+chord.

 
 
 @node Stems
 
 
 @node Stems


@@ -372,6 +408,11 @@ Notation Reference:
 Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 

+Internals Reference:
+@internalsref{Stem_engraver},
+@internalsref{Stem},
+@internalsref{stem-interface}.
+

 
 @node Outside the staff
 @subsection Outside the staff
 
 @node Outside the staff
 @subsection Outside the staff


@@ -397,19 +438,42 @@ notation.
 {
   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
   a8 
 {
   \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
   a8 

-  \balloonGrobText #'Rest #' (-4 . -4) \markup { "I'm a rest" }
+  \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }

   r
   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2. 
 }
 @end lilypond
 
   r
   <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2. 
 }
 @end lilypond
 

+@cindex balloon
+@cindex notation, explaining
+

 There are two music functions, @code{balloonGrobText} and
 There are two music functions, @code{balloonGrobText} and

-@code{balloonText};  The former is used like @code{\once \override} to 
-attach text to any grob, and the latter is used like @code{ \tweak}, 
+@code{balloonText};  the former is used like @code{\once \override} to 
+attach text to any grob, and the latter is used like @code{\tweak}, 

 typically within chords, to attach text to an individual note.
 
 typically within chords, to attach text to an individual note.
 

-@cindex balloon
-@cindex notation, explaining
+Balloon text normally influences note spacing, but this can be
+altered:
+
+@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+\new Voice \with { \consists "Balloon_engraver" }
+{
+  \balloonLengthOff
+  \balloonGrobText #'Stem #'(3 . 4) \markup { "I'm a Stem" }
+  a8 
+  \balloonGrobText #'Rest #'(-4 . -4) \markup { "I'm a rest" }
+  r
+  \balloonLengthOn
+  <c, g'-\balloonText #'(-2 . -2) \markup { "I'm a note head" } c>2. 
+}
+@end lilypond
+
+
+@predefined
+
+@funindex balloonLengthOn
+@funindex balloonLengthOff
+@code{\balloonLengthOn}, @code{\balloonLengthOff}

 
 @seealso
 
 
 @seealso
 


@@ -417,7 +481,9 @@ Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference:

-@internalsref{text-balloon-interface}.
+@internalsref{Balloon_engraver},
+@internalsref{BalloonTextItem},
+@internalsref{balloon-interface}.

 
 
 @node Grid lines
 
 
 @node Grid lines


@@ -426,39 +492,40 @@ Internals Reference:
 Vertical lines can be drawn between staves synchronized with the
 notes.
 
 Vertical lines can be drawn between staves synchronized with the
 notes.
 

+The @code{Grid_point_engraver} must be used to create the end
+points of the lines, while the @code{Grid_line_span_engraver} must
+be used to actually draw the lines.  By default this centers grid
+lines horizontally below and to the left side of each note head.
+Grid lines extend from the middle lines of each staff.  The
+@code{gridInterval} must specify the duration between the grid
+lines.
+

 @lilypond[quote,verbatim,ragged-right]
 \layout {
   \context {
     \Staff
 @lilypond[quote,verbatim,ragged-right]
 \layout {
   \context {
     \Staff

-    % sets up grids

     \consists "Grid_point_engraver" 
     \consists "Grid_point_engraver" 

-    % this sets the grid interval to 1 quarternote (crotchet)

     gridInterval = #(ly:make-moment 1 4)
     gridInterval = #(ly:make-moment 1 4)

-      }
-}
-
-\new Score \with {
-  % by default this centers grid lines horizontally below and to the 
-  % left side of the notehead, the grid lines extend from 
-  % the middle lines of each staff
-  \consists "Grid_line_span_engraver"

   }
   }

+  \context {
+    \Score
+    \consists "Grid_line_span_engraver"
+  }
+}

 
 

-\new ChoirStaff <<
-  \new Staff {
-    \relative c'' {
+\score {
+  \new ChoirStaff <<
+    \new Staff \relative c'' {

       \stemUp
       c4. d8 e8 f g4
     }
       \stemUp
       c4. d8 e8 f g4
     }

-  }
-  \new Staff {
-    \clef bass
-    \relative c {
+    \new Staff \relative c {
+      \clef bass

       \stemDown
       \stemDown

-      c4  g'  f  e
+      c4 g' f e

     }
     }

-  }
->>
+  >>
+}

 @end lilypond
 
 @snippets
 @end lilypond
 
 @snippets


@@ -472,7 +539,13 @@ notes.
 Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 

-
+Internals Reference:
+@internalsref{Grid_line_span_engraver},
+@internalsref{Grid_point_engraver},
+@internalsref{GridLine},
+@internalsref{GridPoint},
+@internalsref{grid-line-interface},
+@internalsref{grid-point-interface}.

 
 
 @node Analysis brackets
 
 
 @node Analysis brackets


@@ -484,12 +557,13 @@ Snippets:
 @cindex note grouping bracket
 
 Brackets are used in musical analysis to indicate structure in musical
 @cindex note grouping bracket
 
 Brackets are used in musical analysis to indicate structure in musical

-pieces.  LilyPond supports a simple form of horizontal brackets.
+pieces.  Simple horizontal brackets are supported.

 
 @lilypond[quote,verbatim,ragged-right]
 \layout {
   \context {
 
 @lilypond[quote,verbatim,ragged-right]
 \layout {
   \context {

-    \Staff \consists "Horizontal_bracket_engraver"
+    \Voice
+    \consists "Horizontal_bracket_engraver"

   }
 }
 \relative c'' {
   }
 }
 \relative c'' {


@@ -503,7 +577,8 @@ Analysis brackets may be nested.
 @lilypond[quote,verbatim,ragged-right]
 \layout {
   \context {
 @lilypond[quote,verbatim,ragged-right]
 \layout {
   \context {

-    \Staff \consists "Horizontal_bracket_engraver"
+    \Voice
+    \consists "Horizontal_bracket_engraver"

   }
 }
 \relative c'' {
   }
 }
 \relative c'' {


@@ -520,7 +595,8 @@ Snippets:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference:
 @lsrdir{Editorial,Editorial-annotations}.
 
 Internals Reference:

-@internalsref{HorizontalBracket},

 @internalsref{Horizontal_bracket_engraver},
 @internalsref{Horizontal_bracket_engraver},

+@internalsref{HorizontalBracket},
+@internalsref{horizontal-bracket-interface},

 @internalsref{Staff}.
 
 @internalsref{Staff}.