man > glilypond(1)

glilypond(1)                           General Commands Manual                          glilypond(1)

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) 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 inter‐
       preted as file operands, even if their names start with a dash.

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) to create Encapsulated PostScript (EPS) files.   This  is  the  de‐
              fault.

       --pdf2eps
              The  program glilypond generates a PDF file using lilypond.  Then the EPS file is gen‐
              erated 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  opera‐
              tions 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  argu‐
              ment 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  argu‐
       ment 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  gener‐
       ated.  By default, these files are regarded as temporary files and as such stored in a tempo‐
       rary 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  out‐
       put  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  com‐
       pletely 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 di‐
       rectories 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
       This mode is the actual default and can also be chosen by the option --pdf2eps.

       In this mode, the .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  dif‐
       ferent 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 correspond‐
       ing 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 given the option -o  | --output file_name

Authors
       glilypond was written by Bernd Warken.

See also
       groff(1)
              describes the usage of the groff command and contains pointers to  further  documenta‐
              tion 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.

groff 1.23.0                                31 March 2024                               glilypond(1)