1glilypond(1)                General Commands Manual               glilypond(1)
2
3
4

NAME

6       glilypond — integrate lilypond parts into groff
7

SYNOPSIS

9       glilypond [ options] [-] [--] [ filespec ....]
10

DESCRIPTION

12       glilypond transforms sheet music written in the lilypond language into
13       the groff(7) language using the .PSPIC request, such that groff(1) can
14       transform it into a format that can be displayed directly.
15
16       Files in groff language and standard input can be provided as argu‐
17       ments.
18

OPTION OVERVIEW

20   Breaking Options
21       -?|-h|--help|--usage
22              Print help or usage information, then leave the program.
23
24       --version
25              Print version information.
26
27       -l|--license
28              Print license information.
29
30   Options for building EPS Files
31       [--ly2eps]
32              Here the lilypond program creates eps files directly.  This is
33              the default.
34
35       [--pdf2eps]
36              The program glilypond generates a pdf file using lilypond.  Then
37              the eps file is generated by pdf2ps and ps2epsR.
38
39   Directories and Files
40       -e|--eps_dir directory_name
41              Normally all EPS files are sent to the temporary directory.
42              With this option, you can generate your own directory, in which
43              all useful EPS files are send.  So at last, the temporary direc‐
44              tory can be removed.
45
46       -p|--prefix begin_of_name
47              Normally all temporary files get names that start with the
48              ly....  prefix.  With this option, you can freely change this
49              prefix.
50
51       -k|--keep_all
52              Normally all temporary files without the eps files are deleted.
53              With this option, all generated files either by the lilypond
54              program or other format transposers are kept.
55
56       -t|--temp_dir dir
57              With this option, you call a directory that is the base for the
58              temporary directory.  This directory name is used as is without
59              any extensions.  If this directory does not exist it is be cre‐
60              ated.  The temporary directory is created by Perl's security op‐
61              erations directly under this directory.  In this temporary di‐
62              rectory, the temporary files are stored.
63
64   Output
65       -o|--output file_name
66              Normally all groff output of this program is sent to STDOUTR.
67              With this option, that can be changed, such that the output is
68              stored into a file named in the option argument file_name.
69
70       -v|-V|--verbose
71              A lot more of information is sent to STDERR.
72
73   Short Option Collections
74       The argument handling of options
75
76       Short options are arguments that start with a single dash -.  Such an
77       argument can consist of arbitrary many options without option argument,
78       composed as a collection of option characters following the single
79       dash.
80
81       Such a collection can be terminated by an option character that expects
82       an option argument.  If this option character is not the last character
83       of the argument, the following final part of the argument is the option
84       argument.  If it is the last character of the argument, the next argu‐
85       ment is taken as the option argument.
86
87       This is the standard for POSIX and GNU option management.
88
89       For example,
90
91       -kVe some_dir
92              is a collection of the short options -k and -V without option
93              argument, followed by the short option -e with option argument
94              that is the following part of the argument some_dir.  So this
95              argument could also be written as several arguments -k -V -e
96              some_dir.
97
98   Handling of Long Options
99       Arguments that start with a double dash -- are so-called long options R
100       .  Each double dash argument can only have a single long option.
101
102       Long options have or have not an option argument.  An option argument
103       can be the next argument or can be appended with an equal sign = to the
104       same argument as the long option.
105
106       --help is a long option without an option argument.
107
108       --eps_dir some_dir
109       --eps_dir=some_dir
110              is the long option --eps_dir with the option argument some_dir.
111
112       Moreover the program allows abbreviations of long options, as much as
113       possible.
114
115       The long option --keep_all can be abbreviated from --keep_al up to --k
116       because the program does not have another long option whose name starts
117       with the character k.
118
119       On the other hand, the option --version cannot be abbreviated further
120       than --vers because there is also the long option --verbose that can be
121       abbreviated up to --verb.
122
123       An option argument can also be appended to an abbreviation.  So is
124       --e=some_dir the same as --eps_dir some_dir.
125
126       Moreover the program allows an arbitrary usage of upper and lower case
127       in the option name.  This is Perl style.
128
129       For example, the long option --keep_all can as well be written as
130       --Keep_All or even as an abbreviation like --KeE.
131

FILESPEC ARGUMENTS

133       An argument that is not an option or an option argument is called a
134       filespec argument.
135
136       Without any filespec argument, standard input is read.
137
138       Each filespec argument must either be the name of a readable file or a
139       dash - for standard input.  Each input must be written in the roff or
140       groff language and can include lilypond parts.
141
142       Normally arguments starting with a dash - are interpreted as an option.
143       But if you use an argument that consists only of a doubled dash -- R ,
144       all following arguments are taken as filespec argument, even if such an
145       argument starts with a dash.  This is handled according to the GNU
146       standard.
147

THE LILYPOND PARTS IN ROFF INPUT

149   Integrated Lilypond Codes
150       A lilypond part within a structure written in the groff language is the
151       whole part between the marks
152              .lilypond start
153       and
154              .lilypond end
155
156       A groff input can have several of these lilypond parts.
157
158       When processing such a lilypond part between .lilypond start and .lily‐
159       pond end we say that the glilypond program is in lilypond mode.
160
161       These lilypond parts are sent into temporary lilypond files with the
162       file name extension .ly.  These files are transformed later on into EPS
163       files.
164
165   Inclusion of ly-Files
166       An additional command line for file inclusion of lilypond files is
167       given by
168       .lilypond include file_name
169       in groff input.  For each such include command, one file of lilypond
170       code can be included into the groff code.  Arbitrarily many of these
171       commands can be included in the groff input.
172
173       These include commands can only be used outside the lilypond parts.
174       Within the lilypond mode, this inclusion is not possible.  So .lilypond
175       include may not be used in lilypond mode, i.e. between .lilypond start
176       and .lilypond end.  These included ly-files are also transformed into
177       EPS files.
178

GENERATED FILES

180       By the transformation process of lilypond parts into EPS files, there
181       are many files generated.  By default, these files are regarded as tem‐
182       porary files and as such stored in a temporary directory.
183
184       This process can be changed by command line options.
185
186   Command Line Options for Directories
187       The temporary directory for this program is either created automati‐
188       cally or can be named by the option -t|--temp_dir dir.
189
190       Moreover, the EPS files that are later on referred by .PSPIC command in
191       the final groff output can be stored in a different directory that can
192       be set by the command line option -e|--eps_dir directory_name.  With
193       this option, the temporary directory can be removed completely at the
194       end of the program.
195
196       The beginning of the names of the temporary files can be set by the
197       command line option [-p |] begin_of_name.
198
199       All of the temporary files except the EPS files are deleted finally.
200       This can be changed by setting the command line option [-k |] With
201       this, all temporary files and directories are kept, not deleted.
202
203       These EPS files are stored in a temporary or EPS directory.  But they
204       cannot be deleted by the transformation process because they are needed
205       for the display which can take a long time.
206

TRANSFORMATION PROCESSES FOR GENERATING EPS FILES

208   Mode ly2eps
209       This mode is the default.  It can also be chosen by the option
210       --ly2eps.
211
212       In this mode, the .ly files are transformed by the lilypond program
213       into many files of different formats, including eps files, using
214              $ lilypond --ps -dbackend=eps -dgs-load-fonts --output=file-name
215       for each .ly file.  The output file-name must be provided without an
216       extension, its directory is temporary.
217
218       There are many EPS files created.  One having the complete transformed
219       ly file, named file-name.eps.
220
221       Moreover there are EPS files for each page, named file-name-digit.eps.
222
223       The last step to be done is replacing all lilypond parts by the collec‐
224       tion of the corresponding EPS page files.  This is done by groff com‐
225       mands
226       .PSPIC file-name-digit.eps
227
228   Mode pdf2eps
229       This mode can be chosen by the option --pdf2eps.
230
231       In this mode, the .ly files are transformed by the lilypond(1) program
232       into pdf files, using
233              lilypond --pdf --output=file-name
234       for each .ly file.  The file-name must be provided without the exten‐
235       sion .pdf.  By this process, a file file-name.pdf is generated.
236
237       The next step is to transform these PDF files into a PS file.  This is
238       done by the pdf2ps(1) program using
239              $  pdf2ps file-name .pdf file-name .ps
240       The next step creates an EPS file from the PS file.  This is done by
241       the ps2eps(1) program using
242              $ ps2eps file-name.ps
243
244       By that, a file file-name.eps is created for each lilypond part in the
245       groff file or standard input.
246
247       The last step to be done is replacing all lilypond parts by the groff
248       command
249              .PSPIC file-name.eps
250

THE GENERATED NEW ROFF STRUCTURE

252       The new groff(7) structure generated by glilypond is either
253
254       1)     sent to standard output and can there be saved into a file or
255              piped into groff(1) or groffer(1) or
256
257       2)     stored into a file by given the option -o  | --output file_name
258

SEE ALSO

260       groff(1)
261              the usage of the groff program and pointers to the documentation
262              and availability of the groff system.  The main source of infor‐
263              mation for the groff system is the groff info(1) file.
264
265       groff(7)
266              documents the groff language.
267
268       groff_tmac(5)
269              contains documentation of the .PSPIC request.
270
271       lilypond(1)
272              The documentation of the lilypond program.  The main source of
273              information for the lilypond language is the lilypond info(1)
274              file.
275
276       pdf2ps(1)
277              transform a PDF file into a Postscript format.
278
279       ps2eps(1)
280              transform a PS file into an EPS format.
281

COPYING

283       Copyright © 2013-2014 Free Software Foundation, Inc.
284
285       This file is part of glilypond, which is part of GNU groff, a free
286       software project.
287
288       You can redistribute it and/or modify it under the terms of the GNU
289       General Public License version 2 (GPL2) as published by the Free Soft‐
290       ware Foundation.
291
292       The license text is available in the internet at ⟨http://www.gnu.org/
293       licenses/gpl-2.0.html⟩.
294

AUTHORS

296       This document was written by Bernd Warken
297       ⟨groff-bernd.warken-72@web.de⟩.
298
299
300
301Groff Version 1.22.3            4 November 2014                   glilypond(1)
Impressum