2.5.4 New markup list command definition (Extending LilyPond)

#### 2.5.4 New markup list command definition

Markup list commands are defined with the `define-markup-list-command` Scheme macro, which is similar to the `define-markup-command` macro described in New markup command definition, except that where the latter returns a single stencil, the former returns a list of stencils.

In a similar vein, `interpret-markup-list` is used instead of `interpret-markup` for converting a markup list into a list of stencils.

In the following example, a `\paragraph` markup list command is defined, which returns a list of justified lines, the first one being indented. The indent width is taken from the `props` argument.

    #(define-markup-list-command (paragraph layout props args) (markup-list?)
       #:properties ((par-indent 2))
       (interpret-markup-list layout props
         #{\markuplist \justified-lines { \hspace #par-indent #args } #}))

The version using just Scheme is more complex:

    #(define-markup-list-command (paragraph layout props args) (markup-list?)
       #:properties ((par-indent 2))
       (interpret-markup-list layout props
         (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
                                                 args))))

Besides the usual `layout` and `props` arguments, the `paragraph` markup list command takes a markup list argument, named `args`. The predicate for markup lists is `markup-list?`.

First, the function gets the indent width, a property here named `par-indent`, from the property list `props`. If the property is not found, the default value is `2`. Then, a list of justified lines is made using the built-in markup list command `\justified-lines`, which is related to the `make-justified-lines-markup-list` function. A horizontal space is added at the beginning using `\hspace` (or the `make-hspace-markup` function). Finally, the markup list is interpreted using the `interpret-markup-list` function.

This new markup list command can be used as follows:

    \markuplist {
      \paragraph {
        The art of music typography is called \italic {(plate) engraving.}
        The term derives from the traditional process of music printing.
        Just a few decades ago, sheet music was made by cutting and stamping
        the music into a zinc or pewter plate in mirror image.
      }
      \override-lines #'(par-indent . 4) \paragraph {
        The plate would be inked, the depressions caused by the cutting
        and stamping would hold ink.  An image was formed by pressing paper
        to the plate.  The stamping and cutting was completely done by
        hand.
      }
    }

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