1glilypond(1) General Commands Manual glilypond(1)
2
6 glilypond - embed LilyPond musical notation in groff documents
7
9 glilypond [-k] [{--ly2eps|--pdf2eps}] [-e directory] [-o output-file]
10 [-p filename-prefix] [-t tdir] [{-v|-V}] [--] [file ...]
11 glilypond [{--ly2eps|--pdf2eps}] [--eps_dir directory] [--keep_all]
12 [--output output-file] [--prefix filename-prefix] [--temp_dir
13 tdir] [--verbose] [--] [file ...]
14 glilypond -?
16 glilypond -h
17 glilypond --help
18 glilypond --usage
19 glilypond -l
21 glilypond --license
22 glilypond --version
24
26 glilypond is a groff(7) preprocessor that enables the embedding of
27 LilyPond music scores in groff documents. If no operands are given, or
28 if file is “-”, glilypond reads the standard input stream. A double-
29 dash argument (“--”) causes all subsequent arguments to be interpreted
30 as file operands, even if their names start with a dash.
31
33 At present, glilypond works with the groff ps, dvi, html, and xhtml de‐
34 vices. The lbp and lj4 devices are untested. Unfortunately, the pdf
35 device does not yet work.
36
38 -?|-h|--help|--usage
39 Display usage information and exit.
40 --version
42 Display version information and exit.
43 -l|--license
45 Display copyright license information and exit.
46 Options for building EPS files
48 --ly2eps
49 Direct lilypond(1) to create Encapsulated PostScript (EPS)
50 files. This is the default.
51 --pdf2eps
53 The program glilypond generates a PDF file using lilypond. Then
54 the EPS file is generated by pdf2ps and ps2eps.
55 Directories and files
57 -e|--eps_dir directory_name
58 Normally all EPS files are sent to the temporary directory.
59 With this option, you can generate your own directory, in which
60 all useful EPS files are send. So at last, the temporary direc‐
61 tory can be removed.
62 -p|--prefix begin_of_name
64 Normally all temporary files get names that start with the ly...
65 prefix. With this option, you can freely change this prefix.
66 -k|--keep_all
68 Normally all temporary files without the eps files are deleted.
69 With this option, all generated files either by the lilypond
70 program or other format transposers are kept.
71 -t|--temp_dir dir
73 With this option, you call a directory that is the base for the
74 temporary directory. This directory name is used as is without
75 any extensions. If this directory does not exist it is be cre‐
76 ated. The temporary directory is created by Perl's security op‐
77 erations directly under this directory. In this temporary di‐
78 rectory, the temporary files are stored.
79 Output
81 -o|--output file_name
82 Normally all groff output of this program is sent to STDOUT.
83 With this option, that can be changed, such that the output is
84 stored into a file named in the option argument file_name.
85 -v|-V|--verbose
87 A lot more of information is sent to STDERR.
88 Short option collections
90 The argument handling of options
91 Short options are arguments that start with a single dash -. Such an
93 argument can consist of arbitrary many options without option argument,
94 composed as a collection of option characters following the single
95 dash.
96 Such a collection can be terminated by an option character that expects
98 an option argument. If this option character is not the last character
99 of the argument, the following final part of the argument is the option
100 argument. If it is the last character of the argument, the next argu‐
101 ment is taken as the option argument.
102 This is the standard for POSIX and GNU option management.
104 For example,
106 -kVe some_dir
108 is a collection of the short options -k and -V without option
109 argument, followed by the short option -e with option argument
110 that is the following part of the argument some_dir. So this
111 argument could also be written as several arguments -k -V -e
112 some_dir.
113 Handling of long options
115 Arguments that start with a double dash -- are so-called long options R
116 . Each double dash argument can only have a single long option.
117 Long options have or have not an option argument. An option argument
119 can be the next argument or can be appended with an equal sign = to the
120 same argument as the long option.
121 --help is a long option without an option argument.
123 --eps_dir some_dir
125 --eps_dir=some_dir
126 is the long option --eps_dir with the option argument some_dir.
127 Moreover the program allows abbreviations of long options, as much as
129 possible.
130 The long option --keep_all can be abbreviated from --keep_al up to --k
132 because the program does not have another long option whose name starts
133 with the character k.
134 On the other hand, the option --version cannot be abbreviated further
136 than --vers because there is also the long option --verbose that can be
137 abbreviated up to --verb.
138 An option argument can also be appended to an abbreviation. So is
140 --e=some_dir the same as --eps_dir some_dir.
141 Moreover the program allows an arbitrary usage of upper and lower case
143 in the option name. This is Perl style.
144 For example, the long option --keep_all can as well be written as
146 --Keep_All or even as an abbreviation like --KeE.
147
149 Integrated LilyPond code
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 A groff input can have several of these lilypond parts.
156 When processing such a lilypond part between .lilypond start and .lily‐
158 pond end we say that the glilypond program is in lilypond mode.
159 These lilypond parts are sent into temporary lilypond files with the
161 file name extension .ly. These files are transformed later on into EPS
162 files.
163 Inclusion of .ly files
165 An additional command line for file inclusion of lilypond files is
166 given by
167 .lilypond include file_name
168 in groff input. For each such include command, one file of lilypond
169 code can be included into the groff code. Arbitrarily many of these
170 commands can be included in the groff input.
171 These include commands can only be used outside the lilypond parts.
173 Within the lilypond mode, this inclusion is not possible. So .lilypond
174 include may not be used in lilypond mode, i.e. between .lilypond start
175 and .lilypond end. These included ly-files are also transformed into
176 EPS files.
177
179 By the transformation process of lilypond parts into EPS files, there
180 are many files generated. By default, these files are regarded as tem‐
181 porary files and as such stored in a temporary directory.
182 This process can be changed by command-line options.
184 Command-line options for directories
186 The temporary directory for this program is either created automati‐
187 cally or can be named by the option -t|--temp_dir dir.
188 Moreover, the EPS files that are later on referred by .PSPIC command in
190 the final groff output can be stored in a different directory that can
191 be set by the command-line option -e|--eps_dir directory_name. With
192 this option, the temporary directory can be removed completely at the
193 end of the program.
194 The beginning of the names of the temporary files can be set by the
196 command-line options -p or --prefix.
197 All of the temporary files except the EPS files are deleted finally.
199 This can be changed by setting the command-line options -k or
200 --keep_files. With this, all temporary files and directories are kept,
201 not deleted.
202 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
208 Mode pdf2eps
209 This mode is the actual default and can also be chosen by the option
210 --pdf2eps.
211 In this mode, the .ly files are transformed by the lilypond(1) program
213 into PDF files, using
214 lilypond --pdf --output=file-name
215 for each .ly file. The file-name must be provided without the exten‐
216 sion .pdf. By this process, a file file-name.pdf is generated.
217 The next step is to transform these PDF files into a PS file. This is
219 done by the pdf2ps(1) program using
220 $ pdf2ps file-name.pdf file-name.pds
221 The next step creates an EPS file from the PS file. This is done by
222 the ps2eps(1) program using
223 $ ps2eps file-name.ps
224 By that, a file file-name.eps is created for each lilypond part in the
226 groff file or standard input.
227 The last step to be done is replacing all lilypond parts by the groff
229 command
230 .PSPIC file-name.eps
231 Mode ly2eps
233 In earlier time, this mode was the default. But now it does not work
234 any more, so accept the new default pdf2eps. For testing, this mode
235 can also be chosen by the glilypond option --ly2eps.
236 In this mode, the .ly files are transformed by the lilypond program
238 into many files of different formats, including eps files, using
239 $ lilypond --ps -dbackend=eps -dgs-load-fonts --output=file-name
240 for each .ly file. The output file-name must be provided without an
241 extension, its directory is temporary.
242 There are many EPS files created. One having the complete transformed
244 ly file, named file-name.eps.
245 Moreover there are EPS files for each page, named file-name-digit.eps.
247 The last step to be done is replacing all lilypond parts by the collec‐
249 tion of the corresponding EPS page files. This is done by groff com‐
250 mands
251 .PSPIC file-name-digit.eps
252
254 The new groff(7) structure generated by glilypond is either
255 1) sent to standard output and can there be saved into a file or
257 piped into groff(1) or
258 2) stored into a file by given the option -o | --output file_name
260
262 glilypond was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
263
265 groff(1)
266 describes the usage of the groff command and contains pointers
267 to further documentation of the groff system.
268 groff_tmac(5)
270 describes the .PSPIC request.
271 lilypond(1)
273 briefly describes the lilypond command and contains pointers to
274 further documentation.
275 pdf2ps(1)
277 transforms a PDF file into a PostScript format.
278 ps2eps(1)
280 transforms a PS file into an EPS format.
281groff 1.23.0 2 November 2023 glilypond(1)