glilypond(1) — Linux manual page

Name | Synopsis | Description | Usage | Option overview | LilyPond regions in roff input | Generated files | Transformation processes for generating EPS files | Generated groff output | Authors | See also | COLOPHON

glilypond(1)             General Commands Manual            glilypond(1)

Name         top

       glilypond - embed LilyPond musical notation in groff documents

Synopsis         top

       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         top

       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         top

       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         top

       -?|-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         top

   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         top

       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         top

   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         top

       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         top

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

See also         top

       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.

COLOPHON         top

       This page is part of the groff (GNU troff) project.  Information
       about the project can be found at 
       ⟨http://www.gnu.org/software/groff/⟩.  If you have a bug report
       for this manual page, see ⟨http://www.gnu.org/software/groff/⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2023-12-22.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2023-12-08.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

groff 1.23.0.453-330f9-dirty 1 November 2023                glilypond(1)