@c -*-texinfo-*-
@c Note:
@c
@c A menu is needed before every deeper *section nesting of @nodes
@c Run M-x texinfo-all-menus-update
@c to automagically fill in these menus
@c before saving changes

@ignore

TODO
  * cue notes
  * different staff sizes
  * font selection

  * move some stuff to refman
  * merge some stuff with refman entries
  
  * add @ref{}s to lilypond-internals:
     @rgrob{Name} to grob
     @reng{Name} to engraver

  there's a very simple, very general noXXX mechanism; try

noop	\property Staff.VoltaBrace = #'()
yes: \property Staff.VoltaBracket = #'((meta .  ((interfaces . ()))))


  visibility?
  brew_molecule?
@end ignore


@node Tricks
@chapter Tricks

@menu
* Manual beam settings::        Manual beam settings
* Engraver hacking::            Engraver hacking
* Part combiner::               Part combiner
* Markup text::                 Markup text
* Apply hacking::               Apply hacking
* Embedded TeX::                Embedded TeX
* Embedded PostScript::         Embedded PostScript
@end menu


@node Manual beam settings
@section Manual beam settings
@cindex beams
@cindex beam settings
@cindex manual beams


@c auto knees


@cindex @code{no-stem-extend}

Conventionally, stems and beams extend to the middle staff line.  This
extension can be controlled through @code{Voice.Stem}'s grob-property
@code{no-stem-extend}:

@quotation
@lilypond[fragment,relative,verbatim]
  \grace a'8 a4
  \property Voice.Stem \set #'no-stem-extend = ##t
  \grace g8 g4 [g8 g]
@end lilypond
@end quotation

The beam symbol can be tweaked through @code{Voice.Beam}'s
grob-properties @code{height} and @code{staff-position},
in staff-spaces.

Set @code{height} to zero, to get horizontal beams:

@quotation
@lilypond[fragment,relative,verbatim]
  \property Voice.Beam \set #'direction = #1
  \property Voice.Beam \set #'height = #0
  [a''8 e' d c]
@end lilypond
@end quotation

Here's how you'd specify a weird looking beam that instead of being
horizontal, falls two staff spaces:

@quotation
@lilypond[fragment,relative,verbatim]
  \property Voice.Beam \set #'staff-position = #2
  \property Voice.Beam \set #'height = #-2
  [c'8 c] 
@end lilypond
@end quotation
@cindex @code{default-neutral-direction}

The direction of a perfectly centred beams can be
controlled through @code{Voice.Beam}'s grob-property
@code{default-neutral-direction}

@quotation
@lilypond[fragment,relative,verbatim]
  [b''8 b]
  \property Voice.Beam \set #'default-neutral-direction = #-1
  [b b]
@end lilypond
@end quotation

There are several ways to calculate the direction of a beam.
@table @code
@item majority
number count of up or down notes
@item mean
mean center distance of all notes
@item median
mean centre distance weighted per note
@end table

You can spot the differences of these settings from these simple
examples:

@quotation
@lilypond[fragment,relative,verbatim]
  [d''8 a]
  \property Voice.Beam \set #'dir-function = #beam-dir-mean
  [d a] 
  \property Voice.Beam \set #'dir-function = #beam-dir-median
  [d a]
@end lilypond
@end quotation

@quotation    
@lilypond[fragment,relative,verbatim]
  \time 3/8;
  [d''8 a a]
  \property Voice.Beam \set #'dir-function = #beam-dir-mean
  [d a a] 
  \property Voice.Beam \set #'dir-function = #beam-dir-median
  [d a a] 
@end lilypond
@end quotation

These beam direction functions are defined in @file{scm/beam.scm}.  If
your favourite algorithm isn't one of these, you can hook up your own.



@node Engraver hacking
@section Engraver hacking

No time signature, no barlines... 
@lilypond[verbatim]
\score {
  \notes \relative c'' {
    a b c d
    d c b a
  }
  \paper {
    linewidth = -1.;
    \translator {
      \StaffContext
      whichBar = #""
      \remove "Time_signature_engraver";
    }
  }
}
@end lilypond

No staff, no clef, squash pitches
@lilypond[verbatim]
\score {
  \notes { c4 c4 c8 c8 }
  \paper {
    linewidth = -1.;
    \translator {
      \StaffContext
      \remove Staff_symbol_engraver;
      \consists Pitch_squash_engraver;
      \remove Clef_engraver;
    }
  }
}
@end lilypond


@node Part combiner
@section Part combiner

@lilypond[verbatim]
\score{
  \context Staff = flauti <
    \time 4/4;
    \context Voice=one \partcombine Voice
    \context Thread=one \notes\relative c'' {
      c4 d e f | b,4 d c d | r2 e4 f | c4 d e f |
      c4 r e f | c4 r e f | c4 r a r | a a r a |
      a2 \property Voice.soloADue = ##f a |
    }
    \context Thread=two \notes\relative c'' {
      g4 b d f | r2 c4 d | a c c d | a4. b8 c4 d
      c r e r | r2 s2 | a,4 r a r | a r r a |
      a2 \property Voice.soloADue = ##f a |
    }
  >
  \paper{
    linewidth = 80 * \staffspace;
    \translator{
      \ThreadContext
      \consists Rest_engraver;
    }
    \translator{
      \VoiceContext
      \remove Rest_engraver;
    }
  }
}
@end lilypond




@node Markup text
@section Markup text


@ignore


#(define text-flat '((font-relative-size . -2 ) (music "accidentals--1")))

  \property VoiceCombineStaff.instrument = #`((kern . 0.5) (lines
    "2 Clarinetti" (rows "     (B" ,text-flat ")")))

    % Ugh, markup burps
    \property StaffCombineStaff.instrument = #'((kern . 0.5)
    (lines "Violoncello" (rows "     e") (rows "Contrabasso")))


@end ignore



Metrome hack...

[todo: hack this into C++, use \tempo]

@lilypond[verbatim]
#(define note '(rows (music "noteheads-2" ((kern . -0.1) "flags-stem"))))
#(define eight-note `(rows ,note ((kern . -0.1) (music ((raise . 3.5) "flags-u3")))))
#(define dotted-eight-note `(rows ,eight-note (music "dots-dot")))

\score {
  \notes\relative c'' {
    a1^#`((rows (font-relative-size . -1)) ,dotted-eight-note " = 64")
  }
  \paper {
    linewidth = -1.;
    \translator{
      \ScoreContext
      TextScript \override #'font-shape = #'upright
    }
  }
}
@end lilypond


@c  equalizer


@node Apply hacking
@section Apply hacking

[Add Parenthesed note head example?]

[Add Smart transpose example?]


@lilypond[verbatim]
music = \notes { c'4 d'4( e'4 f'4 }

#(define (reverse-music music)
  (let* ((elements (ly-get-mus-property music 'elements))
         (reversed (reverse elements))
         (span-dir (ly-get-mus-property music 'span-direction)))
    
    (ly-set-mus-property music 'elements reversed)
    
    (if (dir? span-dir)
        (ly-set-mus-property music 'span-direction (- span-dir)))
    
    (map reverse-music reversed)
    
    music))

\score {
  \context Voice {
    \music
    \apply #reverse-music \music
  }
  \paper { linewidth = -1.; }
}
@end lilypond

@node Embedded TeX
@section Embedded TeX
@lilypond[fragment,relative,verbatim]
  a''^"3 $\\times$ \\`a deux"
@end lilypond

@node Embedded PostScript
@section Embedded PostScript

Arbitrary lines and curves not supported...

[TODO:] Make a direct postscript command?

@lilypond[verbatim]
\score {
  \notes \relative c'' {
    a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}"
    -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}"
    b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}"
    s2
    a'1
  }
  \paper { linewidth = 70 * \staffspace; }
}
@end lilypond