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

NAME

6       glilypond - integrate lilypond parts into groff
7

SYNOPSIS

9       glilypond [{--ly2eps|--pdf2eps}] [-e directory] [-k] [-o output-file]
10                 [-p filename-prefix] [-t tdir] [{-v|-V}] [-] [--] [filespec
11                 ...]
12       glilypond [{--ly2eps|--pdf2eps}] [--eps_dir directory] [--keep_all]
13                 [--output output-file] [--prefix filename-prefix] [--temp_dir
14                 tdir] [--verbose] [-] [--] [filespec ...]
15
16       glilypond -?
17       glilypond -h
18       glilypond --help
19       glilypond --usage
20
21       glilypond -l
22       glilypond --license
23
24       glilypond --version
25

DESCRIPTION

27       glilypond  transforms sheet music written in the lilypond language into
28       the groff(7) language using the .PSPIC request, such that groff(1)  can
29       transform  it into a format that can be displayed directly.  .PDFPIC is
30       available, but does on yet work with lilypond.
31
32       Files in groff language and standard input can  be  provided  as  argu‐
33       ments.
34

WORKING GLILYPOND

36       Together with .PSPIC, glilypond can work only for troff devices without
37       PDF and X devices.
38
39       I.e., the following  groff  devices  work,  -Tps,  -Tdvi,  -Thtml,  and
40       -Txhtml.
41
42       I'm not sure about the ldp and lj4 devices.
43
44       In  groffer,  it  is easier to use the following device options, either
45       --ps, --div, --html, or --xhtml.
46
47       Unfortunately, the groff option -Tpdf does not  work  and  the  groffer
48       default PDF works neither.
49
50       But  groffer has an additional pdf mode, not available in groff.  It is
51       based on the ps mode in groff and  is  called  through  groffer  --pdf2
52       roff-file-with-lilypond.
53

OPTION OVERVIEW

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

FILESPEC ARGUMENTS

167       An argument that is not an option or an option  argument  is  called  a
168       filespec argument.
169
170       Without any filespec argument, standard input is read.
171
172       Each  filespec argument must either be the name of a readable file or a
173       dash - for standard input.  Each input must be written in the  roff  or
174       groff language and can include lilypond parts.
175
176       Normally arguments starting with a dash - are interpreted as an option.
177       But if you use an argument that consists only of a doubled dash -- R  ,
178       all following arguments are taken as filespec argument, even if such an
179       argument starts with a dash.  This is  handled  according  to  the  GNU
180       standard.
181

THE LILYPOND PARTS IN ROFF INPUT

183   Integrated Lilypond Codes
184       A lilypond part within a structure written in the groff language is the
185       whole part between the marks
186              .lilypond start
187       and
188              .lilypond end
189
190       A groff input can have several of these lilypond parts.
191
192       When processing such a lilypond part between .lilypond start and .lily‐
193       pond end we say that the glilypond program is in lilypond mode.
194
195       These  lilypond  parts  are sent into temporary lilypond files with the
196       file name extension .ly.  These files are transformed later on into EPS
197       files.
198
199   Inclusion of ly-Files
200       An  additional  command  line  for  file inclusion of lilypond files is
201       given by
202       .lilypond include file_name
203       in groff input.  For each such include command, one  file  of  lilypond
204       code  can  be  included into the groff code.  Arbitrarily many of these
205       commands can be included in the groff input.
206
207       These include commands can only be used  outside  the  lilypond  parts.
208       Within the lilypond mode, this inclusion is not possible.  So .lilypond
209       include may not be used in lilypond mode, i.e. between .lilypond  start
210       and  .lilypond  end.  These included ly-files are also transformed into
211       EPS files.
212

GENERATED FILES

214       By the transformation process of lilypond parts into EPS  files,  there
215       are many files generated.  By default, these files are regarded as tem‐
216       porary files and as such stored in a temporary directory.
217
218       This process can be changed by command-line options.
219
220   Command Line Options for Directories
221       The temporary directory for this program is  either  created  automati‐
222       cally or can be named by the option -t|--temp_dir dir.
223
224       Moreover, the EPS files that are later on referred by .PSPIC command in
225       the final groff output can be stored in a different directory that  can
226       be  set  by  the command-line option -e|--eps_dir directory_name.  With
227       this option, the temporary directory can be removed completely  at  the
228       end of the program.
229
230       The  beginning  of  the  names of the temporary files can be set by the
231       command-line option [-p |] begin_of_name.
232
233       All of the temporary files except the EPS files  are  deleted  finally.
234       This  can  be  changed  by  setting the command-line option [-k |] With
235       this, all temporary files and directories are kept, not deleted.
236
237       These EPS files are stored in a temporary or EPS directory.   But  they
238       cannot be deleted by the transformation process because they are needed
239       for the display which can take a long time.
240

TRANSFORMATION PROCESSES FOR GENERATING EPS FILES

242   Mode pdf2eps
243       This mode is the actual default and can also be chosen  by  the  option
244       --pdf2eps.
245
246       In  this mode, the .ly files are transformed by the lilypond(1) program
247       into PDF files, using
248              lilypond --pdf --output=file-name
249       for each .ly file.  The file-name must be provided without  the  exten‐
250       sion .pdf.  By this process, a file file-name.pdf is generated.
251
252       The  next step is to transform these PDF files into a PS file.  This is
253       done by the pdf2ps(1) program using
254              $  pdf2ps file-name .pdf file-name .ps
255       The next step creates an EPS file from the PS file.  This  is  done  by
256       the ps2eps(1) program using
257              $ ps2eps file-name.ps
258
259       By  that, a file file-name.eps is created for each lilypond part in the
260       groff file or standard input.
261
262       The last step to be done is replacing all lilypond parts by  the  groff
263       command
264              .PSPIC file-name.eps
265
266   Mode ly2eps
267       In  earlier  time, this mode was the default.  But now it does not work
268       any more, so accept the new default pdf2eps.  For  testing,  this  mode
269       can also be chosen by the glilypond option --ly2eps.
270
271       In  this  mode,  the  .ly files are transformed by the lilypond program
272       into many files of different formats, including eps files, using
273              $ lilypond --ps -dbackend=eps -dgs-load-fonts --output=file-name
274       for each .ly file.  The output file-name must be  provided  without  an
275       extension, its directory is temporary.
276
277       There  are many EPS files created.  One having the complete transformed
278       ly file, named file-name.eps.
279
280       Moreover there are EPS files for each page, named file-name-digit.eps.
281
282       The last step to be done is replacing all lilypond parts by the collec‐
283       tion  of  the corresponding EPS page files.  This is done by groff com‐
284       mands
285       .PSPIC file-name-digit.eps
286

THE GENERATED NEW ROFF STRUCTURE

288       The new groff(7) structure generated by glilypond is either
289
290       1)     sent to standard output and can there be saved into  a  file  or
291              piped into groff(1) or groffer(1) or
292
293       2)     stored into a file by given the option -o  | --output file_name
294

AUTHORS

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

SEE ALSO

299       groff(1)
300              describes  the  usage of the groff command and contains pointers
301              to further documentation of the groff system.
302
303       groff_tmac(5)
304              describes the .PSPIC request.
305
306       lilypond(1)
307              briefly describes the lilypond command and contains pointers  to
308              further documentation.
309
310       pdf2ps(1)
311              transforms a PDF file into a PostScript format.
312
313       ps2eps(1)
314              transforms a PS file into an EPS format.
315
316
317
318groff 1.22.4                    3 November 2020                   glilypond(1)
Impressum