2.5.1 Markup construction in Scheme (Extending LilyPond)

#### 2.5.1 Markup construction in Scheme

Markup expressions are internally represented in Scheme using the `markup` macro:

    (markup expr)

To see a markup expression in its Scheme form, use the `\displayScheme` command:

    \displayScheme
    \markup {
      \column {
        \line { \bold \italic "hello" \raise #0.4 "world" }
        \larger \line { foo bar baz }
      }
    }

Compiling the code above will send the following to the display console:

    (markup
      #:line
      (#:column
       (#:line
        (#:bold (#:italic "hello") #:raise 0.4 "world")
        #:larger
        (#:line ("foo" "bar" "baz")))))

To prevent the markup from printing on the page, use ‘`\void \displayScheme markup`’. Also, as with the `\displayMusic` command, the output of `\displayScheme` can be saved to an external file. See Displaying music expressions.

This example demonstrates the main translation rules between regular LilyPond markup syntax and Scheme markup syntax. Using `#{ … #}` for entering in LilyPond syntax will often be most convenient, but we explain how to use the `markup` macro to get a Scheme-only solution.

> LilyPond | Scheme
> `\markup markup1` | `(markup markup1)`
> `\markup { markup1 markup2 … }` | `(markup markup1 markup2 …)`
> `\markup-command` | `#:markup-command`
> `\variable` | `variable`
> `\center-column { … }` | `#:center-column (…)`
> `string` | `"string"`
> `#scheme-arg` | `scheme-arg`

The whole Scheme language is accessible inside the `markup` macro. For example, You may use function calls inside `markup` in order to manipulate character strings. This is useful when defining new markup commands (see New markup command definition).

#### Known issues and warnings

The markup-list argument of commands such as `#:line`, `#:center-column`, and `#:column` cannot be a variable or the result of a function call.

    (markup #:line (function-that-returns-markups))

is invalid. One should use the `make-line-markup`, `make-center-column-markup`, or `make-column-markup` functions instead,

    (markup (make-line-markup (function-that-returns-markups)))

#### 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