Extending LilyPond

This is a work-in-progress resource on extending LilyPond in Scheme.

Maybe something for the official documentation can come out of it eventually.

This document assumes prior knowledge of the Scheme language itself. A good, albeit to this day incomplete, introduction to Scheme in the context of LilyPond is found on Urs Liska’s website. For French-speaking readers, there is another one in French (by myself).

If you find any inaccuracies in this document or want to suggest an improvement, drop me an email.

License: Creative Commons CC0.

Contents:

• Introduction to extending
  • Inserting Scheme inside LilyPond
  • Exported functions and naming
  • The Scheme sandbox
  • Music function primer
  • Callback primer
  • Printing values
  • First steps with the internals
    • Smobs
    • Probs
  • Glossary of important object types
  • Overview of LilyPond’s inner workings and how you might hook in them
    • Parsing
    • Iterating
    • Pure positioning
    • Page breaking and line breaking
    • Unpure positioning
    • Writing output
• LilyPond and Scheme
  • Scopes
  • Hash vs. dollar
• Music objects
  • Defining music functions
    • Argument type checking
    • Optional arguments
    • Other function types
  • The \etc shortcut
  • Music expressions
  • Music properties
  • Constructing music from scratch
  • Music transformation tools
  • Copying music
  • Pitches
  • Durations and moments
• The translation process
  • Overview
  • Grob basics
  • Contexts
    • Context properties
    • The context hierarchy
    • Context IDs
    • Defining new context types
  • Useful translation hooks
    • Accessing a context
    • Tweaking grobs during translation
    • Overwriting grob properties set by engravers
  • Writing an engraver
    • Basics
    • The time step cycle
    • Processing stream events
    • Creating grobs
    • First engraver example
    • Acknowledging grobs
    • Second engraver example
    • End acknowledgers
    • Third engraver example
    • Grob parents and spanner bounds
      • Horizontal parents and bounds
      • Vertical parents
    • Fourth engraver example
    • Killing grobs
    • Fifth engraver example
• Backend programming
  • Grob interfaces
  • Properties and callbacks
    • Understanding callbacks
    • Important properties
    • The grob-transformer
    • Grob pointers
  • The causation chain
  • Grob suicide
  • Grob flavors and line breaks
    • Items and spanners
    • Paper columns
    • Spanner bounds
    • Broken grobs
  • Spacing topics
    • Directions and axes
    • Intervals
    • Coordinates, extents and reference points
    • Units
  • Drawing objects
    • Stencils
    • Markups
  • Dummy properties
  • Unpure-pure containers
    • The problem
    • Writing an unpure-pure container
    • The purity contract
    • TODOs
    • Further reading on purity
• Adding properties and types
  • New properties
  • New event class
  • New music type
  • New grob type