contrib/glilypond/glilypond.1.man

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