# glilypond

## 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 interpreted 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 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) 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, 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) 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 ⟨groff-bernd.warken-72@web
           .de⟩.
    


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


* * *