---
name: "glilypond"
section: "1"
platform: "linux"
package: "groff"
version: "1.24.2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/glilypond"
---

# glilypond(1)

embed LilyPond musical notation in groff documents

## Name

glilypond - embed LilyPond musical notation in *groff* documents

## Synopsis

**glilypond** \[**-k**\] \[{**--ly2eps**\|**--pdf2eps**}\] \[**-e** *directory*\] \[**-o** *output-file*\] \[**-p** *filename-prefix*\] \[**-t** *tdir*\] \[{**-v**\|**-V**}\] \[**--**\] \[*file* ...\]

**glilypond** \[{**--ly2eps**\|**--pdf2eps**}\] \[**--eps\_dir** *directory*\] \[**--keep\_all**\] \[**--output** *output-file*\] \[**--prefix** *filename-prefix*\] \[**--temp\_dir** *tdir*\] \[**--verbose**\] \[**--**\] \[*file* ...\]

**glilypond** **-?**

**glilypond** **-h**

**glilypond** **--help**

**glilypond** **--usage**

**glilypond** **-l**

**glilypond** **--license**

**glilypond** **--version**

## Description

*glilypond* is a [*groff*(7)](/groff/7.md) preprocessor that enables the embedding of LilyPond music scores in *groff* documents. If no operands are given, or if *file* is “**-**”, *glilypond* reads the standard input stream. A double-dash argument (“**--**”) causes all subsequent arguments to be interpreted as *file* operands, even if their names start with a dash.

*glilypond* requires the *File::HomeDir* Perl module, available via CPAN ⟨\\%https://\\:www\\:.cpan\\:.org/⟩.

## Usage

At present, *glilypond* works with the *groff* **ps**, **dvi**, **html**, and **xhtml** devices. The **lbp** and **lj4** devices are untested. Unfortunately, the **pdf** device does not yet work.

## Option overview

- **-?**\|**-h**\|**--help**\|**--usage**

  Display usage information and exit.

- **--version**

  Display version information and exit.

- **-l**\|**--license**

  Display copyright license information and exit.

### Options for building EPS files

- **--ly2eps**

  Direct [*lilypond*(1)](/lilypond/1.md) to create Encapsulated PostScript (EPS) files. This is the default.

- **--pdf2eps**

  The program *glilypond* generates a PDF file using *lilypond*. Then the EPS file is generated by *pdf2ps* and *ps2eps*.

### Directories and files

- **-e**\|**--eps\_dir** *directory\_name*

  Normally all *EPS* files are sent to the temporary directory. With this option, you can generate your own directory, in which all useful *EPS* files are send. So at last, the temporary directory can be removed.

- **-p**\|**--prefix** *begin\_of\_name*

  Normally all temporary files get names that start with the **ly***...* prefix. With this option, you can freely change this prefix.

- **-k**\|**--keep\_all**

  Normally all temporary files without the *eps* files are deleted. With this option, all generated files either by the *lilypond* program or other format transposers are kept.

- **-t**\|**--temp\_dir** *dir*

  With this option, you call a directory that is the base for the temporary directory. This directory name is used as is without any extensions. If this directory does not exist it is be created. The temporary directory is created by Perl's security operations directly under this directory. In this temporary directory, the temporary files are stored.

### Output

- **-o**\|**--output** *file\_name*

  Normally all *groff* output of this program is sent to **STDOUT**. With this option, that can be changed, such that the output is stored into a file named in the option argument *file\_name*.

- **-v**\|**-V**\|**--verbose**

  A lot more of information is sent to STDERR.

### Short option collections

The argument handling of options

*Short options* are arguments that start with a single dash **-**. Such an argument can consist of arbitrary many options without option argument, composed as a collection of option characters following the single dash.

Such a collection can be terminated by an option character that expects an option argument. If this option character is not the last character of the argument, the following final part of the argument is the option argument. If it is the last character of the argument, the next argument is taken as the option argument.

This is the standard for *POSIX* and *GNU* option management.

For example,

- **-kVe** *some\_dir*

  is a collection of the short options **-k** and **-V** without option argument, followed by the short option **-e** with option argument that is the following part of the argument *some\_dir*. So this argument could also be written as several arguments **-k -V -e** *some\_dir*.

### Handling of long options

Arguments that start with a double dash **--** are so-called *long options R .* Each double dash argument can only have a single long option.

*Long options* have or have not an option argument. An option argument can be the next argument or can be appended with an equal sign **=** to the same argument as the long option.

- **--help**

  is a long option without an option argument.

- **--eps\_dir** *some\_dir* **--eps\_dir=***some\_dir*

  is the long option **--eps\_dir** with the option argument *some\_dir*.

Moreover the program allows abbreviations of long options, as much as possible.

The *long option* **--keep\_all** can be abbreviated from **--keep\_al** up to **--k** because the program does not have another *long option* whose name starts with the character **k**.

On the other hand, the option **--version** cannot be abbreviated further than **--vers** because there is also the *long option* **--verbose** that can be abbreviated up to **--verb**.

An option argument can also be appended to an abbreviation. So is **--e=***some\_dir* the same as **--eps\_dir** *some\_dir*.

Moreover the program allows an arbitrary usage of upper and lower case in the option name. This is *Perl* style.

For example, the *long option* **--keep\_all** can as well be written as **--Keep\_All** or even as an abbreviation like **--KeE**.\

## LilyPond regions in *roff* input

### Integrated LilyPond code

A *lilypond* part within a structure written in the *groff* language is the whole part between the marks

```
.lilypond start
```

and

```
.lilypond end
```

A *groff* input can have several of these *lilypond* parts.

When processing such a *lilypond* part between **.lilypond start** and **.lilypond end** we say that the **glilypond** program is in *lilypond mode*.

These *lilypond* parts are sent into temporary *lilypond* files with the file name extension **.ly**. These files are transformed later on into *EPS* files.

### Inclusion of *.ly* files

An additional command line for file inclusion of *lilypond* files is given by

```
.lilypond include file_name
```

in *groff* input. For each such *include* command, one file of *lilypond* code can be included into the *groff* code. Arbitrarily many of these commands can be included in the *groff* input.

These include commands can only be used outside the *lilypond* parts. Within the *lilypond mode*, this inclusion is not possible. So **.lilypond include** may not be used in *lilypond mode*, i.e. between **.lilypond start** and **.lilypond end**. These included *ly*-files are also transformed into *EPS* files.

## Generated files

By the transformation process of *lilypond* parts into *EPS* files, there are many files generated. By default, these files are regarded as temporary files and as such stored in a temporary directory. This process can be changed by command-line options.

### Command-line options for directories

The temporary directory for this program is either created automatically or can be named by the option **-t**\|**--temp\_dir** *dir*.

Moreover, the *EPS* files that are later on referred by **.PSPIC** command in the final *groff* output can be stored in a different directory that can be set by the command-line option **-e**\|**--eps\_dir** *directory\_name*. With this option, the temporary directory can be removed completely at the end of the program.

The beginning of the names of the temporary files can be set by the command-line options **-p** or **--prefix**.

All of the temporary files except the *EPS* files are deleted finally. This can be changed by setting the command-line options **-k** or **--keep\_files**. With this, all temporary files and directories are kept, not deleted.

These *EPS* files are stored in a temporary or *EPS* directory. But they cannot be deleted by the transformation process because they are needed for the display which can take a long time.

## Transformation processes for generating EPS files

### Mode pdf2eps

In this mode, the current default, **.ly** files are transformed by the [*lilypond*(1)](/lilypond/1.md) program into *PDF* files, using

```
lilypond --pdf --output=file-name
```

for each **.ly** file. The *file-name* must be provided without the extension **.pdf**. By this process, a file *file-name***.pdf** is generated.

The next step is to transform these *PDF* files into a *PS* file. This is done by the [*pdf2ps*(1)](/pdf2ps/1.md) program using

```
$
pdf2ps
file-name.pdf
file-name.pds
```

The next step creates an *EPS* file from the *PS* file. This is done by the [*ps2eps*(1)](/ps2eps/1.md) program using

```
$ ps2eps file-name.ps
```

By that, a file *file-name***.eps** is created for each *lilypond* part in the *groff* file or standard input.

The last step to be done is replacing all *lilypond* parts by the *groff* command

```
.PSPIC file-name.eps
```

### Mode ly2eps

In earlier time, this mode was the default. But now it does not work any more, so accept the new default *pdf2eps*. For testing, this mode can also be chosen by the *glilypond* option **--ly2eps**.

In this mode, the **.ly** files are transformed by the *lilypond* program into many files of different formats, including *eps* files, using

```
$
lilypond --ps -dbackend=eps -dgs-load-fonts --output=
file-name
```

for each **.ly** file. The output *file-name* must be provided without an extension, its directory is temporary.

There are many *EPS* files created. One having the complete transformed **ly** file, named *file-name***.eps***.*

Moreover there are *EPS* files for each page, named *file-name***-***digit***.eps***.*

The last step to be done is replacing all *lilypond* parts by the collection of the corresponding *EPS* page files. This is done by *groff* commands

```
.PSPIC file-name-digit.eps
```

## Generated *groff* output

The new [*groff*(7)](/groff/7.md) structure generated by *glilypond* is either

- 1\)

  sent to standard output and can there be saved into a file or piped into [*groff*(1)](/groff/1.md) or

- 2\)

  stored into a file by given the option **-o  \|** --output *file\_name*

## Authors

*glilypond* was written by Bernd Warken ⟨groff\\-bernd\\:.warken\\-72@\\:web\\:.de⟩.

## See also

- [*groff*(1)](/groff/1.md)

  describes the usage of the *groff* command and contains pointers to further documentation of the *groff* system.

- [*groff\_tmac*(5)](/groff_tmac/5.md)

  describes the **.PSPIC** request.

- [*lilypond*(1)](/lilypond/1.md)

  briefly describes the *lilypond* command and contains pointers to further documentation.

- [*pdf2ps*(1)](/pdf2ps/1.md)

  transforms a *PDF* file into a *PostScript* format.

- [*ps2eps*(1)](/ps2eps/1.md)

  transforms a *PS* file into an *EPS* format.