1.2.8 LilyPond’s box model (Extending LilyPond)

#### 1.2.8 LilyPond’s box model

The ‘classical’ box model for text (as used, for example, in TeX), comprises the three dimensions width, height, and depth: glyphs are positioned on a horizontal text base line; the height of a glyph is the vertical size above this line, the depth the size below this line, and the width holds the horizontal size of the glyph. LilyPond adds a fourth dimension, breapth,1 to extend the horizontal size by a part left of the glyph’s ‘reference point’, denoted with ‘(0, 0)’ in the image below. The main reason for this extension is that many glyphs like fermatas are symmetrical horizontally (and also symmetrically attached to a note head), and the best reference point for such glyphs is consequently the horizontal center. Other glyphs like the quarter-tone accidental shown on the left in the image also have considerable breapth.

As demonstrated by the custos glyph on the right side of the image, the box defined for a glyph often differs considerably of what gets actually printed: LilyPond positions the right side of the custos glyph box at the end of a staff, making the long extension line stick out to the right into the margin.

This box model is not only used for LilyPond’s musical glyphs but also for markup of any kind. Both the horizontal and vertical dimensions are specified as an extent; using Scheme notation, the left glyph in the image above has a horizontal extent of `#'(-9 . 26)` and a vertical extent of `#'(-10 . 29)`.

LilyPond also uses some extensions to the box model to cover special cases.

- If a box should not take part in LilyPond’s music spacing algorithm along a certain axis, set the extents of this axis to the otherwise nonsensical value `#'(+inf.0 . -inf.0)`, also available as the symbol `empty-interval`.
- In markup, spacing (which normally causes horizontal or vertical movement of the next object in the markup) is also set up as a box internally: the extent along the orthogonal axis is set to `empty-interval` as a marker, and a spacing value s is represented as the extent `#'(0 . s)`. Contrary to ‘normal’ boxes, spacing can be also negative: for example, the horizontal extent of the markup command `\hspace #-4` is `#'(0 . -4)`.

#### Footnotes

##### (1)

This artificial name was derived from the English word ‘breadth’, which means approximately the same as ‘width’.

#### Extending LilyPond v2.26.0 (stable-branch).

- 1 Scheme tutorial
  - 1.1 Introduction to Scheme
    - 1.1.1 Scheme sandbox
    - 1.1.2 Scheme variables
    - 1.1.3 Scheme simple data types
    - 1.1.4 Scheme compound data types
      - Pairs
      - Lists
      - Association lists (alists)
      - Hash tables
    - 1.1.5 Calculations in Scheme
    - 1.1.6 Scheme procedures
      - Defining procedures
      - Predicates
      - Return values
    - 1.1.7 Scheme conditionals
      - if
      - cond
  - 1.2 Scheme in LilyPond
    - 1.2.1 LilyPond Scheme syntax
    - 1.2.2 LilyPond variables
    - 1.2.3 Debugging Scheme code
    - 1.2.4 Input variables and Scheme
    - 1.2.5 Importing Scheme in LilyPond
    - 1.2.6 Object properties
    - 1.2.7 LilyPond compound variables
      - Offsets
      - Fractions
      - Extents
      - Property alists
      - Alist chains
    - 1.2.8 LilyPond’s box model
    - 1.2.9 Internal music representation
  - 1.3 Building complicated functions
    - 1.3.1 A first approach (example)
    - 1.3.2 Displaying music expressions
    - 1.3.3 Music properties
    - 1.3.4 Doubling a note with slurs (example)
    - 1.3.5 Adding articulation to notes (example)
- 2 Interfaces for programmers
  - 2.1 LilyPond code blocks
  - 2.2 Scheme functions
    - 2.2.1 Scheme function definitions
    - 2.2.2 Scheme function usage
    - 2.2.3 Void Scheme functions
  - 2.3 Music functions
    - 2.3.1 Music function definitions
    - 2.3.2 Music function usage
    - 2.3.3 Simple substitution functions
    - 2.3.4 Intermediate substitution functions
    - 2.3.5 Mathematics in functions
    - 2.3.6 Functions without arguments
    - 2.3.7 Void music functions
  - 2.4 Event functions
  - 2.5 Markup functions
    - 2.5.1 Markup construction in Scheme
    - 2.5.2 How markups work internally
    - 2.5.3 New markup command definition
      - Markup command definition syntax
      - On properties
      - A complete example
      - Adapting builtin commands
      - Converting markups to strings
    - 2.5.4 New markup list command definition
  - 2.6 Contexts for programmers
    - 2.6.1 Context evaluation
    - 2.6.2 Running a function on all layout objects
  - 2.7 Callback functions
  - 2.8 Unpure-pure containers
  - 2.9 Difficult tweaks
- 3 LilyPond Scheme interfaces
- Appendix A GNU Free Documentation License
- Appendix B Index