what to do when lilypond fails? (by Ruben Philipp)

Although slippery-chicken's LilyPond-support is well-tested on various systems with different specifications, it might occur that the call to lp-display exits with an error, or files generated via write-lp-data-for-all cannot be properly parsed by lilypond, even with a working copy of LilyPond installed on your system and a properly configured slippery-chicken environment[^1].

In the most likely case, the syntax of the LilyPond data generated by slippery-chicken does not comply with the syntax supported by the LilyPond version on your machine. First of all, make sure that the LilyPond version on your system matches at least the version indicated in the :lp-version keyword-argument of write-lp-data-for-all.

Syntax changes in LilyPond are not unusual and rather considered as making

[...] input simpler to both read and write, [and] occasionally the changes are made to accommodate new features or enhancements to existing functions.[^2]

slippery-chicken's LilyPond output (as of December 2023) complies with LilyPond version 2.42.1. As argued above, it is very likely that the version installed on your machine implements a (slightly) different syntax, which can cause erroneous results or lead to grave errors when parsing a .ly file with lilypond.

Generally, if you run into any of such complications (as described above) with LilyPond generation, please launch a GitHub issue so that the problem can be resolved within slippery-chicken's code base.

Automatic conversion of LilyPond files

This is not an existential issue as LilyPond aims at backwards compatibility in their release policy, ensured via proper documentation of syntax changes and the implementation of a document conversion tool, convert-ly[^3].

convert-ly reads .ly-files and converts them from a specific version (either estimated via the \version command in the files, or explicitly using the --from= option) to comply with the syntax definitions of the LilyPond version running on your system. The LilyPond files parsed with this process should then be validly readable and interpretable with the lilypond command. The following example illustrates the process of automatically converting all .ly files contained in a certain directory and saving (this is what --edit demands) the updated files using the name of the original file. Copies of the original files will be created with a tilde ("~") added to the filename-suffix.

convert-ly --edit --from=2.20.0 /path/to/*.ly

Auto-conversion with lp-display

It should be clear that the method described above will work with code generated via write-lp-data-for-all, but leaves the question of how to immediately generate PDFs via lp-display unanswered as the latter function calls to the lilypond-command immediately after generating the score data. Thus, there is, per default, no syntax conversion/updating taking place. A quite simple solution to this issue, which does not involve tweaking the slippery-chicken source code itself, is based on creating a "user-defined" lp-command which runs convert-ly on all LilyPond files in the lp-output directory and only then runs lilypond on the main LilyPond file of the slippery-chicken piece.

The easiest implementation (on a UNIX system) appears to write a simple shell script which is then set to be the standard lilypond-command, e.g. via adding the following line to your .swank.lisp:

(set-sc-config 'lilypond-command
               "/path/to/lp-display-autoconvert.sh")

Make sure that the permissions for this file are set properly via (in the shell):

chmod 755 /path/to/lp-display-autoconvert.sh

The following shell script is an example implementation of the code contained in the file lp-display-autoconvert.sh:

#!/bin/zsh
################################################################################
### This script should be invoked by slippery-chicken lp-display
### as the lp-command. It automatically converts all .ly files in
### the directoroy of the lpfile (which is the main lilypond file of
### the sc piece) and runs the lpcommand thereafter.
### NB: This file must be executable (chmod 755)
###
### CREATED
### 2023-04-29
###
### $$ Last modified:  20:23:01 Sat Apr 29 2023 CEST
################################################################################

scarg="$1"
noext="$2"
lpfile="$3"
lpfiledir=$(dirname "${lpfile}")
lpcommand="/opt/homebrew/Cellar/lilypond/2.24.1/bin/lilypond"
convertcommand="/opt/homebrew/Cellar/lilypond/2.24.1/bin/convert-ly"

### run convert-ly on all lilypond files in the given directory
$convertcommand --edit --from=2.20.0 $lpfiledir/*.ly

### run lilypond
$lpcommand $scarg $noext $lpfile

################################################################################
### EOF lp-display-autoconvert.sh

Make sure to adjust the variables lpcommand and convertcommand to your system's configuration.

After evaluating the (set-sc-config 'lilypond-command ..., you should be able to use lp-display to generate your scores as PDF files.

Footnotes

[^1]: This is achieved by setting the lilypond-command according to your system's configuration, e.g. via (set-sc-config 'lilypond-command "/path/to/lilypond").

[^2]: LilyPond Documentation: Why does the syntax change

[^3] LilyPond Documentation: Updating files with convert-ly