Ubuntu Manpage: glilypond - 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)  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
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 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.