contrib/glilypond/glilypond.man

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