Debian Codegraph @

upstream/debian-trixie/man1/glilypond.1

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