glilypond(1)

📦
version 1.24.2 · 15 versions
, in alpine 3.24

🎀 glilypond — General Commands Manual 🎀

okay bestie, so this is the manual page for glilypond, and it lives in section 1 of the General Commands Manual. it's giving "niche but iconic" tbh. let's go 💅

✨ 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

like, that's the whole vibe check right there 🫶

✨ Description ✨

glilypond is a groff(7) preprocessor, and its whole personality is enabling you to embed LilyPond music scores inside groff documents 🎶✨

If no operands are given, or if file is -, then glilypond reads the standard input stream. and a double-dash argument (--) lowkey overrides everything: it causes all subsequent arguments to be interpreted as file operands, even if their names start with a dash. periodt.

💀 heads up bestie: glilypond requires the File::HomeDir Perl module, which you can get via CPAN.

✨ Usage ✨

so rn, glilypond works with the groff ps, dvi, html, and xhtml devices 🦋

the lbp and lj4 devices are untested 😭 and unfortunately the pdf device does not yet work. not me being sad about it but also it's just facts.

✨ Option overview ✨

  • -? | -h | --help | --usage — display usage information and exit. bye bestie 👋
  • --version — display version information and exit ✨
  • -l | --license — display copyright license information and exit 📜

🧚 Options for building EPS files

  • --ly2eps — tells lilypond(1) to create Encapsulated PostScript (EPS) files. this is the default 🔥
  • --pdf2eps — glilypond generates a PDF file using lilypond. then the EPS file is generated by pdf2ps and ps2eps. icons only.

📁 Directories and files

  • -e directory_name, --eps_dir directory_name — normally all EPS files get sent to the temporary directory. with this option you can generate your own directory where all the useful EPS files get sent, so at last the temporary directory can be removed 🎀
  • -p begin_of_name, --prefix begin_of_name — normally all temporary files get names that start with the ly... prefix. with this option you can freely change that prefix 💅
  • -k, --keep_all — normally all temporary files without the EPS files are deleted. with this option, all generated files — whether from the lilypond program or from other format transposers — are kept 🫶
  • -t dir, --temp_dir dir — with this option you name 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 created. the temporary directory itself is created by Perl's security operations directly under this directory, and the temporary files are stored in it 🦋

🖨️ Output

  • -o file_name, --output file_name — normally all groff output of this program is sent to STDOUT. with this option that changes, so the output gets stored into a file named by the option argument file_name 💖
  • -v | -V | --verbose — a lot more information is sent to STDERR 😭 (she's chatty)

✨ Short option collections ✨

the argument handling of options

short options are arguments that start with a single dash -. such an argument can consist of arbitrarily many options that take no 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 that 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, then the next argument is taken as the option argument ✨

this is the standard for POSIX and GNU option management, iykyk.

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

slay 🎉

✨ Handling of long options ✨

arguments that start with a double dash -- are so-called long options 💜 each double dash argument can only have a single long option. no sharing, one per customer.

long options have or have not an option argument. an option argument can be the next argument, or it 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 --e=some_dir is 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 😌 iconic.

✨ 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 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 to by the .PSPIC command in the final groff output can be stored in a different directory, which 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) 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) 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) 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, and its directory is temporary 🎀

there are many EPS files created. one has 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) structure generated by glilypond is either

  1. sent to standard output, and can there be saved into a file or piped into groff(1), or
  2. stored into a file by giving the option -o | --output file_name

both are valid, bestie, pick your fighter 💅

✨ Authors ✨

glilypond was written by Bernd Warken 👑 (we stan)

✨ See also ✨

  • groff(1) — describes the usage of the groff command and contains pointers to further documentation of the groff system 📚
  • groff_tmac(5) — describes the .PSPIC request 🎀
  • lilypond(1) — briefly describes the lilypond command and contains pointers to further documentation 🌸
  • pdf2ps(1) — transforms a PDF file into a PostScript format 🦋
  • ps2eps(1) — transforms a PS file into an EPS format ✨

so yeah, that's the whole page 🫶 and legally we gotta shout out the footer: this is groff 1.24.2, dated 2026-10-01, and it's the glilypond(1) page 💖 thanks for coming to my ted talk, mwah 💋

📦 where this page comes from