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.

If you find any inaccuracies in this document, 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
    • 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 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