Debian Codegraph @

upstream/debian-unstable/man1/glilypond.1

raw
1 .TH glilypond 1 "2026-04-22" "groff 1.24.1"
2 .SH Name
3 glilypond \- embed LilyPond musical notation in
4 .I groff
5 documents
6 .
7 .
8 .\" TODO: This page needs a thorough edit by a fluent English speaker.
9 .
10 .\" ====================================================================
11 .\" Legal Terms
12 .\" ====================================================================
13 .\"
14 .\" Copyright 2013-2020 Free Software Foundation, Inc.
15 .\"
16 .\" This file is part of glilypond.
17 .\"
18 .\" glilypond is distributed with groff, the GNU roff typesetting
19 .\" system.
20 .\"
21 .\" groff is free software; you can redistribute it and/or modify it
22 .\" under the terms of the GNU General Public License as published by
23 .\" the Free Software Foundation, either version 3 of the License, or
24 .\" (at your option) any later version.
25 .\"
26 .\" groff is distributed in the hope that it will be useful, but WITHOUT
27 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
28 .\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
29 .\" License for more details.
30 .\"
31 .\" You should have received a copy of the GNU General Public License
32 .\" along with this program. If not, see
33 .\" <https://www.gnu.org/licenses/>.
34 .
35 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
36 .do nr *groff_glilypond_1_man_C \n[.cp]
37 .cp 0
38 .
39 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
40 .nr do-fallback 0
41 .if !\n(.f .nr do-fallback 1 \" mandoc
42 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
43 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
44 .if \n[do-fallback] \{\
45 . de MR
46 . ie \\n(.$=1 \
47 . I \%\\$1
48 . el \
49 . IR \%\\$1 (\\$2)\\$3
50 . .
51 .\}
52 .rr do-fallback
53 .
54 .
55 .\" ====================================================================
56 .SH Synopsis
57 .\" ====================================================================
58 .
59 .SY glilypond
60 .RB [ \-k ]
61 .RB [{ \-\-ly2eps | \-\-pdf2eps }]
62 .RB [ \-e
63 .IR directory ]
64 .RB [ \-o
65 .IR output-file ]
66 .RB [ \-p
67 .IR filename-prefix ]
68 .RB [ \-t
69 .IR tdir ]
70 .RB [{ \-v | \-V }]
71 .RB [ \-\- ]
72 .RI [ file\~ .\|.\|.]
73 .YS
74 .
75 .SY glilypond
76 .RB [{ \-\-ly2eps | \-\-pdf2eps }]
77 .RB [ \-\-eps_dir
78 .IR directory ]
79 .RB [ \-\-keep_all ]
80 .RB [ \-\-output
81 .IR output-file ]
82 .RB [ \-\-prefix
83 .IR filename-prefix ]
84 .RB [ \-\-temp_dir
85 .IR tdir ]
86 .RB [ \-\-verbose ]
87 .RB [ \-\- ]
88 .RI [ file\~ .\|.\|.]
89 .YS
90 .
91 .
92 .P
93 .SY glilypond
94 .B \-?
95 .YS
96 .
97 .SY glilypond
98 .B \-h
99 .YS
100 .
101 .SY glilypond
102 .B \-\-help
103 .YS
104 .
105 .SY glilypond
106 .B \-\-usage
107 .YS
108 .
109 .
110 .P
111 .SY glilypond
112 .B \-l
113 .YS
114 .
115 .SY glilypond
116 .B \-\-license
117 .YS
118 .
119 .
120 .P
121 .SY glilypond
122 .B \%\-\-version
123 .YS
124 .
125 .
126 .\" ====================================================================
127 .SH Description
128 .\" ====================================================================
129 .
130 .I glilypond
131 is a
132 .MR groff 7
133 preprocessor that enables the embedding of LilyPond music scores in
134 .I groff
135 documents.
136 .\".
137 .\".B .PDFPIC
138 .\"is available, but does not yet work with lilypond.
139 .
140 If no operands are given,
141 or if
142 .I file
143 is
144 .RB \[lq] \- \[rq],
145 .I glilypond
146 reads the standard input stream.
147 .
148 A double-dash argument
149 .RB (\[lq] \-\- \[rq])
150 causes all subsequent arguments to be interpreted as
151 .I file
152 operands,
153 even if their names start with a dash.
154 .
155 .
156 .P
157 .I \%glilypond
158 requires the
159 .I \%File::\:HomeDir
160 Perl module,
161 available via
162 .UR \%https://\:www\:.cpan\:.org/
163 CPAN
164 .UE .
165 .
166 .
167 .\" ====================================================================
168 .SH Usage
169 .\" ====================================================================
170 .
171 At present,
172 .I glilypond
173 works with the
174 .I groff
175 .BR ps ,
176 .BR dvi ,
177 .BR html ,
178 and
179 .B xhtml
180 devices.
181 .
182 The
183 .B lbp
184 and
185 .B lj4
186 devices are untested.
187 .
188 Unfortunately,
189 the
190 .B pdf
191 device does not yet work.
192 .
193 .
194 .\" ====================================================================
195 .SH "Option overview"
196 .\" ====================================================================
197 .
198 .
199 .TP
200 .BR \-? | \-h | \-\-help | \-\-usage
201 Display usage information and exit.
202 .
203 .TP
204 .B \%\-\-version
205 Display version information and exit.
206 .
207 .TP
208 .BR \-l | \-\-license
209 Display copyright license information and exit.
210 .
211 .
212 .\" ====================================================================
213 .SS "Options for building EPS files"
214 .\" ====================================================================
215 .
216 .TP
217 .B \-\-ly2eps
218 Direct
219 .MR lilypond 1
220 to create Encapsulated PostScript (EPS) files.
221 .
222 This is the default.
223 .
224 .
225 .TP
226 .B \-\-pdf2eps
227 The program
228 .I glilypond
229 generates a PDF file using
230 .IR lilypond .
231 .
232 Then the EPS file is generated by
233 .I pdf2ps
234 and
235 .IR ps2eps .
236 .
237 .
238 .\" ====================================================================
239 .SS "Directories and files"
240 .\" ====================================================================
241 .
242 .TP
243 .BR \-e | \-\-eps_dir "\fI directory_name\fP"
244 Normally all
245 .I EPS
246 files are sent to the temporary directory.
247 .
248 With this option,
249 you can generate your own directory,
250 in which all useful
251 .I EPS
252 files are send.
253 .
254 So at last, the temporary directory can be removed.
255 .
256 .
257 .TP
258 .BR \-p | \-\-prefix "\fI begin_of_name\fP"
259 Normally all temporary files get names that start with the
260 .BI ly .\|.\|.\&
261 prefix.
262 .
263 With this option, you can freely change this prefix.
264 .
265 .
266 .TP
267 .BR \-k | \-\-keep_all
268 Normally all temporary files without the
269 .I eps
270 files are deleted.
271 .
272 With this option, all generated files either by the
273 .I lilypond
274 program or other format transposers are kept.
275 .
276 .
277 .TP
278 .BR \-t | \-\-temp_dir "\fI dir\fP"
279 With this option, you call a directory that is the base for the
280 temporary directory.
281 .
282 This directory name is used as is without any extensions.
283 .
284 If this directory does not exist it is be created.
285 .
286 The temporary directory is created by Perl's security operations
287 directly under this directory.
288 .
289 In this temporary directory, the temporary files are stored.
290 .
291 .
292 .\" ====================================================================
293 .SS Output
294 .\" ====================================================================
295 .
296 .TP
297 .BR \-o | \-\-output "\fI file_name\fP"
298 Normally all
299 .I groff
300 output of this program is sent to
301 .BR STDOUT .
302 .
303 With this option, that can be changed, such that the output is stored
304 into a file named in the option argument
305 .IR file_name .
306 .
307 .
308 .TP
309 .BR \-v | \-V | \-\-verbose
310 A lot more of information is sent to STDERR.
311 .
312 .
313 .\" ====================================================================
314 .SS "Short option collections"
315 .\" ====================================================================
316 .
317 The argument handling of options
318 .
319 .
320 .P
321 .I "Short options"
322 are arguments that start with a single dash
323 .BR \- .
324 .
325 Such an argument can consist of arbitrary many options without option
326 argument, composed as a collection of option characters following the
327 single dash.
328 .
329 .
330 .P
331 Such a collection can be terminated by an option character that
332 expects an option argument.
333 .
334 If this option character is not the last character of the argument,
335 the following final part of the argument is the option argument.
336 .
337 If it is the last character of the argument, the next argument is
338 taken as the option argument.
339 .
340 .
341 .P
342 This is the standard for
343 .I POSIX
344 and
345 .I GNU
346 option management.
347 .
348 .
349 .P
350 For example,
351 .
352 .TP
353 .BI \-kVe " some_dir"
354 is a collection of the short options
355 .B \-k
356 and
357 .B \-V
358 without option argument, followed by the short option
359 .B \-e
360 with option argument that is the following part of the argument
361 .IR some_dir .
362 .
363 So this argument could also be written as several arguments
364 .B \-k \-V \-e
365 .IR some_dir .
366 .
367 .
368 .\" ====================================================================
369 .SS "Handling of long options"
370 .\" ====================================================================
371 .
372 Arguments that start with a double dash
373 .B \-\-
374 are so-called
375 .I "long options" R .
376 .
377 Each double dash argument can only have a single long option.
378 .
379 .
380 .P
381 .I "Long options"
382 have or have not an option argument.
383 .
384 An option argument can be the next argument or can be appended with an
385 equal sign
386 .B =
387 to the same argument as the long option.
388 .
389 .
390 .TP
391 .B \-\-help
392 is a long option without an option argument.
393 .
394 .TP
395 .BI \-\-eps_dir " some_dir"
396 .TQ
397 .BI \-\-eps_dir= some_dir
398 is the long option
399 .B \-\-eps_dir
400 with the option argument
401 .IR some_dir .
402 .
403 .
404 .P
405 Moreover the program allows abbreviations of long options, as much as
406 possible.
407 .
408 .
409 .P
410 The
411 .I "long option"
412 .B \-\-keep_all
413 can be abbreviated from
414 .B \-\-keep_al
415 up to
416 .B \-\-k
417 because the program does not have another
418 .I "long option"
419 whose name starts with the character
420 .BR k .
421 .
422 .
423 .P
424 On the other hand, the option
425 .B \%\-\-version
426 cannot be abbreviated further than
427 .B \-\-vers
428 because there is also the
429 .I long option
430 .B \-\-verbose
431 that can be abbreviated up to
432 .BR \-\-verb .
433 .
434 .
435 .P
436 An option argument can also be appended to an abbreviation.
437 .
438 So is
439 .BI \-\-e= some_dir
440 the same as
441 .B \-\-eps_dir
442 .IR some_dir .
443 .
444 .
445 .P
446 Moreover the program allows an arbitrary usage of upper and lower case
447 in the option name.
448 .
449 This is
450 .I Perl
451 style.
452 .
453 .
454 .P
455 For example, the
456 .I "long option"
457 .B \-\-keep_all
458 can as well be written as
459 .B \-\-Keep_All
460 or even as an abbreviation like
461 .BR \-\-KeE .
462 .
463 .
464 .br
465 .ne 6v
466 .\" ====================================================================
467 .SH "LilyPond regions in \f[I]roff\f[] input"
468 .\" ====================================================================
469 .
470 .\" ====================================================================
471 .SS "Integrated LilyPond code"
472 .\" ====================================================================
473 .
474 A
475 .I lilypond
476 part within a structure written in the
477 .I groff
478 language is the whole part between the marks
479 .RS
480 .EX
481 .B ".lilypond start"
482 .EE
483 .RE
484 and
485 .RS
486 .EX
487 .B ".lilypond end"
488 .EE
489 .RE
490 .
491 A
492 .I groff
493 input can have several of these
494 .I lilypond
495 parts.
496 .
497 .
498 .P
499 When processing such a
500 .I lilypond
501 part between
502 .B ".lilypond start"
503 and
504 .B ".lilypond end"
505 we say that the
506 .B glilypond
507 program is in
508 .IR "lilypond mode" .
509 .
510 .
511 .P
512 These
513 .I lilypond
514 parts are sent into temporary
515 .I lilypond
516 files with the file name extension
517 .BR .ly .
518 .
519 These files are transformed later on into
520 .I EPS
521 files.
522 .
523 .
524 .\" ====================================================================
525 .SS "Inclusion of \f[I].ly\f[] files"
526 .\" ====================================================================
527 .
528 An additional command line for file inclusion of
529 .I lilypond
530 files is given by
531 .EX
532 .BI ".lilypond include" " file_name"
533 .EE
534 in
535 .I groff
536 input.
537 .
538 For each such
539 .I include
540 command, one file of
541 .I lilypond
542 code can be included into the
543 .I groff
544 code.
545 .
546 Arbitrarily many of these commands can be included in the
547 .I groff
548 input.
549 .
550 .
551 .P
552 These include commands can only be used outside the
553 .I lilypond
554 parts.
555 .
556 Within the
557 .IR "lilypond mode" ,
558 this inclusion is not possible.
559 .
560 So
561 .B ".lilypond include"
562 may not be used in
563 .IR "lilypond mode" ,
564 i.e.\& between
565 .B ".lilypond start"
566 and
567 .BR ".lilypond end" .
568 .
569 .
570 These included
571 .IR ly -files
572 are also transformed into
573 .I EPS
574 files.
575 .
576 .
577 .\" ====================================================================
578 .SH "Generated files"
579 .\" ====================================================================
580 .
581 By the transformation process of
582 .I lilypond
583 parts into
584 .I EPS
585 files, there are many files generated.
586 .
587 By default, these files are regarded as temporary files and as such
588 stored in a temporary directory.
589 .
590 This process can be changed by command-line options.
591 .
592 .
593 .\" ====================================================================
594 .SS "Command-line options for directories"
595 .\" ====================================================================
596 .
597 The temporary directory for this program is either created
598 automatically or can be named by the option
599 .BR \-t | \-\-temp_dir
600 .IR dir .
601 .
602 .
603 .P
604 Moreover, the
605 .I EPS
606 files that are later on referred by
607 .B .PSPIC
608 command in the final
609 .I groff
610 output can be stored in a different directory that can be set by the
611 command-line option
612 .BR \-e | \-\-eps_dir
613 .IR directory_name .
614 .
615 With this option, the temporary directory can be removed completely at
616 the end of the program.
617 .
618 .
619 .P
620 The beginning of the names of the temporary files can be set by the
621 command-line options
622 .B \-p
623 or
624 .BR \-\-prefix .
625 .
626 .
627 .P
628 All of the temporary files except the
629 .I EPS
630 files are deleted finally.
631 .
632 This can be changed by setting the command-line options
633 .B \-k
634 or
635 .BR \-\-keep_files .
636 .
637 With this, all temporary files and directories are kept, not deleted.
638 .
639 .
640 .P
641 These
642 .I EPS
643 files are stored in a temporary or
644 .I EPS
645 directory.
646 .
647 But they cannot be deleted by the transformation process because they
648 are needed for the display which can take a long time.
649 .
650 .
651 .\" ====================================================================
652 .SH "Transformation processes for generating EPS files"
653 .\" ====================================================================
654 .
655 .\" ====================================================================
656 .SS "Mode pdf2eps"
657 .\" ====================================================================
658 .
659 In this mode,
660 the current default,
661 .B .ly
662 files are transformed by the
663 .MR lilypond 1
664 program into
665 .I PDF
666 files, using
667 .RS
668 .EX
669 .BI "lilypond \-\-pdf \-\-output=" file-name
670 .EE
671 .RE
672 for each
673 .B .ly
674 file.
675 .
676 The
677 .I file-name
678 must be provided without the extension
679 .BR .pdf .
680 .
681 By this process, a file
682 .IB file-name .pdf
683 is generated.
684 .
685 .
686 .P
687 The next step is to transform these
688 .I PDF
689 files into a
690 .I PS
691 file.
692 .
693 This is done by the
694 .MR pdf2ps 1
695 program using
696 .RS
697 .EX
698 $\~\c
699 .B pdf2ps\~\c
700 .IB file-name .pdf\~\c
701 .IB file-name .pds
702 .EE
703 .RE
704 .
705 .
706 The next step creates an
707 .I EPS
708 file from the
709 .I PS
710 file.
711 .
712 This is done by the
713 .MR ps2eps 1
714 program using
715 .RS
716 .EX
717 .RB "$ " "ps2eps " \fIfile-name\fP ".ps"
718 .EE
719 .RE
720 .
721 .
722 .P
723 By that, a file
724 .IB file-name .eps
725 is created for each
726 .I lilypond
727 part in the
728 .I groff
729 file or standard input.
730 .
731 .
732 .P
733 The last step to be done is replacing all
734 .I lilypond
735 parts by the
736 .I groff
737 command
738 .RS
739 .EX
740 .BI ".PSPIC " file-name .eps
741 .EE
742 .RE
743 .
744 .
745 .\" ====================================================================
746 .SS "Mode ly2eps"
747 .\" ====================================================================
748 .
749 In earlier time, this mode was the default.
750 .
751 But now it does not work any more, so accept the new default
752 .IR pdf2eps .
753 .
754 For testing, this mode can also be chosen by the
755 .I glilypond
756 option
757 .BR \-\-ly2eps .
758 .
759 .
760 .P
761 In this mode, the
762 .B .ly
763 files are transformed by the
764 .I lilypond
765 program into many files of different formats, including
766 .I eps
767 files, using
768 .RS
769 .EX
770 $\~\c
771 .B lilypond \-\-ps \-dbackend=eps \-dgs\-load\-fonts \-\-output=\c
772 .I file-name
773 .EE
774 .RE
775 for each
776 .B .ly
777 file.
778 .
779 The output
780 .I file\-name
781 must be provided without an extension, its directory is temporary.
782 .
783 .
784 .P
785 There are many
786 .I EPS
787 files created.
788 .
789 One having the complete transformed
790 .B ly
791 file, named
792 .IB file\-name .eps \fR.\fP
793 .
794 .
795 .P
796 Moreover there are
797 .I EPS
798 files for each page, named
799 .IB file\-name \- digit .eps \fR.\fP
800 .
801 .
802 .P
803 The last step to be done is replacing all
804 .I lilypond
805 parts by the collection of the corresponding
806 .I EPS
807 page files.
808 .
809 This is done by
810 .I groff
811 commands
812 .EX
813 .BI ".PSPIC " file-name \- digit .eps
814 .EE
815 .
816 .
817 .\" ====================================================================
818 .SH "Generated \f[I]groff\f[] output"
819 .\" ====================================================================
820 .
821 The new
822 .MR groff 7
823 structure generated by
824 .I glilypond
825 is either
826 .
827 .TP
828 1)
829 sent to standard output and can there be saved into a file or piped into
830 .MR groff 1
831 or
832 .
833 .TP
834 2)
835 stored into a file by given the option
836 .BR \-o\ \~| \~\-\-output
837 .I file_name
838 .
839 .
840 .\" ====================================================================
841 .SH Authors
842 .\" ====================================================================
843 .
844 .I glilypond
845 was written by
846 .MT groff\-bernd\:.warken\-72@\:web\:.de
847 Bernd Warken
848 .ME .
849 .
850 .
851 .\" ====================================================================
852 .SH "See also"
853 .\" ====================================================================
854 .
855 .TP
856 .MR groff 1
857 describes the usage of the
858 .I groff
859 command and contains pointers to further documentation of the
860 .I groff
861 system.
862 .
863 .
864 .TP
865 .MR groff_tmac 5
866 describes the
867 .B .PSPIC
868 request.
869 .
870 .
871 .TP
872 .MR lilypond 1
873 briefly describes the
874 .I lilypond
875 command and contains pointers to further documentation.
876 .
877 .
878 .TP
879 .MR pdf2ps 1
880 transforms a
881 .I PDF
882 file into a
883 .I PostScript
884 format.
885 .
886 .
887 .TP
888 .MR ps2eps 1
889 transforms a
890 .I PS
891 file into an
892 .I EPS
893 format.
894 .
895 .
896 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
897 .cp \n[*groff_glilypond_1_man_C]
898 .do rr *groff_glilypond_1_man_C
899 .
900 .
901 .\" Local Variables:
902 .\" fill-column: 72
903 .\" mode: nroff
904 .\" End:
905 .\" vim: set filetype=groff textwidth=72: