diff options
Diffstat (limited to 'contrib/glilypond/glilypond.man')
| -rw-r--r-- | contrib/glilypond/glilypond.man | 916 |
1 files changed, 916 insertions, 0 deletions
diff --git a/contrib/glilypond/glilypond.man b/contrib/glilypond/glilypond.man new file mode 100644 index 00000000..80532730 --- /dev/null +++ b/contrib/glilypond/glilypond.man @@ -0,0 +1,916 @@ +.TH glilypond @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" +.SH NAME +glilypond \[em] integrate \f[CI]lilypond\f[P] parts into \f[CI]groff\f[] +. +.\" This .SH was moved to this place in order to appease `apropos'. +. +.\" -------------------------------------------------------------------- +.\" Legalese +.\" -------------------------------------------------------------------- +. +.de authors +This file was written by Bernd Warken +.MT groff\-bernd.warken\-72@web.de +.ME . +. +Last update: 24 Mar 2013 +.. +. +. +.\" The following macro .copying contains the license information for this file. +.de copying +.nh +.nf +glilypond - integrate lilypond into groff files + +Source file position: <groff-source>/contrib/lilypond/glilypond.man +Installed position: <prefix>/share/man/man1/glilypond.1 + +Copyright \(co 2013 + Free Software Foundation, Inc. + +This file is part of GNU groff. + +GNU groff is free software: you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation, either version 3 of the License, or ("at +your option") any later version. + +GNU groff is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with groff], see the files COPYING and LICENSE in the top +directory of the groff source package. + +.hy +.fi +If not, see the GNU licenses at +.UR http://www.gnu.org/licenses/ +.UE . +.. +. +. +.\" -------------------------------------------------------------------- +.\" Setup +.\" -------------------------------------------------------------------- +. +.ds Ellipsis "\&.\|.\|.\&\" +. +. +.\" -------------------------------------------------------------------- +.\" Macro definitions +.\" -------------------------------------------------------------------- +. +.\" -------------------------------------------------------------------- +.\" .FONT (<font name> <text> [<font name> <text> ...]) +.\" +.\" Print in different fonts: R, I, B, CR, CI, CB +.\" +.de1 FONT +. if (\\n[.$] = 0) \{\ +. nop \&\f[P]\& +. return +. \} +. ds result \& +. while (\\n[.$] >= 2) \{\ +. as result \,\f[\\$1]\\$2 +. if !"\\$1"P" .as result \f[P] +. shift 2 +. \} +. if (\\n[.$] = 1) .as result \,\f[\\$1] +. nh +. nop \\*[result]\& +. hy +.. +. +. +.\" -------------------------------------------------------------------- +.\" .OP+ (<option> [ [ | option] ...] [<optarg> [<end>] ]) +.\" +.\" like .OP, but with 1st arg split and and optional final character +.\" Example: `.OP+ -p | --prefix ly .' gets `[-t|--prefix ly].' +.\" Example: `.OP+ -h | --help | --usage' gets `[-h|--help|--usage]' +.\" Example: `.OP+ -v | --version "" ,' gets `[-v|--version],' +.\" +.de1 OP+ +. if ( \\n[.$] == 0 ) \{\ +. nop \&\f[CR][]\fR\& +. return +. \} +. nh +. ds result \&\f[CR][\f[CB]\\$1 +. shift +. while (\\n[.$] >= 2) \{\ +. ie '\\$1'|' .as result \f[CR]|\f[CB]\\$2 +. el \{\ +. ie '\\$1'' .as result \f[CR]]\fR\\$2 +. el .as result \fI\ \\$1\f[CR]]\fR\\$2 +. nop \\*[result]\& +. hy +. return +. \} +. shift 2 +. \} +. as result \fI\ \\$1\f[CR]]\fR +. nop \\*[result]\& +. hy +.. +. +.\" -------------------------------------------------------------------- +.SH "SYNOPSIS" +.\" -------------------------------------------------------------------- +. +.SY glilypond +.OP+ options +.OP+ - +.OP+ -- +.OP+ \%filespec \*[Ellipsis] +.YS +. +. +.\" -------------------------------------------------------------------- +.SH DESCRIPTION +.\" -------------------------------------------------------------------- +. +.FONT CB glilypond +transforms sheet music written in the +.FONT CI lilypond +language into the +.BR groff (@MAN7EXT@) +language using the +.FONT CB .PSPIC +request, such that +.BR groff (@MAN1EXT@) +can transform it into a format that can be displayed directly. +. +. +.P +Files in +.FONT CI groff +language and +.FONT CI "standard input" +can be provided as arguments. +. +. +.\" -------------------------------------------------------------------- +.SH "OPTION OVERVIEW" +.\" -------------------------------------------------------------------- +. +.\" -------------------------------------------------------------------- +.SS "Breaking Options" +.\" -------------------------------------------------------------------- +. +.SY +.OP+ -? | -h | --help | --usage +.YS +.SY +.OP+ -v | --version +.YS +.SY +.OP+ -l | --license +.YS +. +. +.\" -------------------------------------------------------------------- +.SS "Options for building EPS Files" +.\" -------------------------------------------------------------------- +. +.TP +.OP+ --ly2eps +Here the +.FONT CB lilypond +program creates +.FONT CI eps +files directly. +. +This is the default. +. +. +.TP +.OP+ --pdf2eps +The program +.FONT CB glilypond +generates a +.FONT CI pdf +file using +.FONT CB lilypond R . +. +Then the +.FONT CI eps +file is generated by +.FONT CB pdf2ps +and +.FONT CB ps2eps R . +. +. +.\" -------------------------------------------------------------------- +.SS "Directories and Files" +.\" -------------------------------------------------------------------- +. +.TP +.OP+ -e | --eps_dir directory_name +Normally all +.FONT CI EPS +files are sent to the temporary directory. +. +With this option, you can generate your own directory, in which all useful +.FONT CI EPS +files are send. +. +So at last, the temporary directory can be removed. +. +. +.TP +.OP+ -p | --prefix begin_of_name +Normally all temporary files get names that start with the +.FONT CB ly CI \*[Ellipsis] +prefix. +. +With this option, you can freely change this prefix. +. +. +.TP +.OP+ -k | --keep_all +Normally all temporary files without the +.FONT CI eps +files are deleted. +. +With this opton, all generated files either by the +.FONT CB lilypond +program or other format transposers are kept. +. +. +.TP +.OP+ -t | --temp_dir dir +With this option, you call a directory that is the base for the +temporary directory. +. +This directory name is used as is without any extensions. +. +If this directory does not exist it is be created. +. +The temporary directory is created by Perl's security operations +directly under this directory. +. +In this temporary directory, the temporary files are stored. +. +. +.\" -------------------------------------------------------------------- +.SS "Output" +.\" -------------------------------------------------------------------- +. +.TP +.OP+ -o | --output file_name +Normally all +.FONT CI groff +output of this program is sent to +.FONT CB STDOUT R . +. +With this option, that can be changed, such that the output is stored +into a file named in the option argument +.IR file_name . +. +. +.TP +.OP+ -V | --verbose +A lot more of information is sent to STDERR. +. +. +.\" -------------------------------------------------------------------- +.SS "Short Option Collections" +.\" -------------------------------------------------------------------- +. +The argument handling of options +. +. +.P +.FONT CI "Short options" +are arguments that start with a single dash +.FONT CB \- R . +. +Such an argument can consist of arbitrary many options without option +argument, composed as a collection of option characters following the +single dash. +. +. +.P +Such a collection can be terminated by an option character that +expects an option argument. +. +If this option character is not the last character of the argument, +the follwing final part of the argument is the option argument. +. +If it is the last character of the argument, the next argument is +taken as the option argument. +. +. +.P +This is the standard for +.FONT CI POSIX +and +.FONT CI GNU +option management. +. +. +.P +For example, +. +.TP +.FONT CB \-kVesome_dir +is a collection of the short options +.FONT CB \-k +and +.FONT CB \-V +without option argument, followed by the short option +.FONT \-e +with option argument that is the following part of the argument +.FONT CB some_dir R . +. +So this argument could also be written as several arguments +.FONT CB "\-k \-V \-e some_dir" R . +. +. +.\" -------------------------------------------------------------------- +.SS "Handling of Long Options" +.\" -------------------------------------------------------------------- +. +Arguments that start with a double dash +.FONT CB \-\- +are so-called +.FONT CI "long options" R . +. +Each double dash argument can only have a single long option. +. +. +.P +.FONT CI "Long options" +have or have not an option argument. +. +An option argument can be the next argument or can be appended with an +equal sign +.FONT CB = +to the same argument as the long option. +. +. +.TP +.FONT CB \-\-help +is a long option without an option argument. +. +.TP +.FONT CB "\-\-eps_dir some_dir" +.TQ +.FONT CB "\-\-eps_dir=some_dir" +is the long option +.FONT CB "\-\-eps_dir +with the option argument +.FONT CB some_dir R . +. +. +.P +Moreover the program allows abbreviations of long options, as much as +possible. +. +. +.P +The +.FONT CI "long option" +.FONT CB \-\-keep_all +can be abbreviated from +.FONT CB \-\-keep_al +up to +.FONT CB \-\-k +because the program does not have another +.FONT CI "long option" +whose name starts with the character +.FONT CB k R . +. +. +.P +On the other hand, the option +.FONT \-\-version +cannot be abbreviated further than +.FONT \-\-vers +because there is also the +.FONT CI "long option " CB \-\-verbose +that can be abbreviated up to +.FONT \-\-verb R . +. +. +.P +An option argument can also be appended to an abbreviation. +. +So is +.FONT CB \-\-e=some_dir +the same as +.FONT CB "\-\-eps_dir some_dir" R . +. +. +.P +Moreover the program allows an arbitrary usage of upper and lower case +in the option name. +. +This is +.FONT CI Perl +style. +. +. +.P +For example, the +.FONT CI long option +.FONT CB \-\-keep_all +can as well be written as +.FONT CB \-\-Keep_All +or even as an abbreviation like +.FONT CB \-\-KeE R . +. +. +.\" -------------------------------------------------------------------- +.SH FILESPEC ARGUMENTS +.\" -------------------------------------------------------------------- +. +An argument that is not an option or an option argument is called a +.FONT CI filespec +argument. +. +. +.P +Without any +.I filespec +argument, +.FONT CI "standard input" +is read. +. +. +.P +Each +.I filespec +argument must either be the name of a readable file or a dash +.FONT CB - +for +.FONT CI "standard input" R . +. +Each input must be written in the +.FONT CI roff +or +.FONT CI groff +language and can include +.FONT CI lilypond +parts. +. +. +.P +Normally arguments starting with a dash +.FONT CB \- +are interpreted as an option. +. +But if you use an argument that consists only of a doubled dash +.FONT CB \-\- R , +all following arguments are taken as +.FONT CI filespec +argument, even if such an argument starts with a dash. +. +This is handled according to the +.FONT CI GNU +standard. +. +. +.\" -------------------------------------------------------------------- +.SH "THE LILYPOND PARTS IN ROFF INPUT" +.\" -------------------------------------------------------------------- +. +.\" -------------------------------------------------------------------- +.SS "Integrated Lilypond Codes" +.\" -------------------------------------------------------------------- +. +A +.FONT CI lilypond +part within a structure written in the +.FONT CI groff +language is the whole part between the marks +.EX +.FONT CB ".lilypond start" +.EE +and +.EX +.FONT CB ".lilypond end" +.EE +. +. +.P +A +.FONT CI groff +input can have several of these +.FONT CI lilypond +parts. +. +. +.P +When processing such a +.FONT CI lilypond +part between +.FONT CB ".lilypond start" +and +.FONT CB ".lilypond end" +we say that the +.FONT CB glilypond +program is in +.FONT CI "lilypond mode" R . +. +. +.P +These +.FONT CI lilypond +parts are sent into temporary +.FONT CI lilypond +files with the file name extension +.FONT CB .ly R . +. +These files are transformed later on into +.FONT CI EPS +files. +. +. +.\" -------------------------------------------------------------------- +.SS "Inclusion of ly-Files" +.\" -------------------------------------------------------------------- +. +An additional command line for file inclusion of +.FONT CI lilypond +files is given by +.EX +.FONT CB ".lilypond include" I " file_name" +.EE +in +.FONT CI groff +input. +. +For each such +.FONT CI include +command, one file of +.FONT CI lilypond +code can be included into the +.FONT CI groff +code. +. +Arbitrarily many of these commands can be included in the +.FONT CI groff +input. +. +. +.P +These include commands can only be used outside the +.FONT CI lilypond +parts. +. +Within the +.FONT CI "lilypond mode" R , +this inclusion is not possible. +. +So +.FONT CB ".lilypond include" +may not be used in +.FONT CI "lilypond mode" R , +i.e. between +.FONT CB ".lilypond start" +and +.FONT CB ".lilypond end" R . +. +. +These included +.FONT CI ly R -files +are also transformed into +.FONT CI EPS +files. +. +. +.\" -------------------------------------------------------------------- +.SH "GENERATED FILES" +.\" -------------------------------------------------------------------- +. +By the transformation process of +.FONT CI lilypond +parts into +.FONT CI EPS +files, there are many files generated. +. +By default, these files are regarded as temporary files and as such +stored in a temporary directory. +. +. +.P +This process can be changed by command line options. +. +. +.\" -------------------------------------------------------------------- +.SS "Command Line Options for Directories" +.\" -------------------------------------------------------------------- +. +The temporary directory for this program is either created +automatically or can be named by the option +.OP+ -t | --temp_dir dir . +. +. +.P +Moreover, the +.FONT CI EPS +files that are later on referred by +.FONT CB .PSPIC +command in the final +.FONT CI groff +output can be stored in a different directory that can be set by the +command line option +.OP+ -e | --eps_dir directory_name . +. +With this option, the temporary directory can be removed completely at +the end of the program. +. +. +.P +The beginning of the names of the temporary files can be set by the +command line option +.OP+ -p | --prefix begin_of_name . +. +. +.P +All of the temporary files except the +.FONT CI EPS +files are deleted finally. +. +This can be changed by setting the command line option +.OP+ -k | --keep_files +. +With this, all temporary files and directories are kept, not deleted. +. +. +.P +These +.FONT CI EPS +files are stored in a temporary or +.FONT CI EPS +directory. +. +But they cannot be deleted by the transformation process because they +are needed for the display which can take a long time. +. +. +.\" -------------------------------------------------------------------- +.SH "TRANSFORMATION PROCESSES FOR GENERATING EPS FILES" +.\" -------------------------------------------------------------------- +. +.\" -------------------------------------------------------------------- +.SS "Mode ly2eps" +.\" -------------------------------------------------------------------- +. +This mode is the default. +. +It can also be chosen by the option +.FONT CB --ly2eps R . +. +. +.P +In this mode, the +.FONT CB .ly +files are transformed by the +.FONT CB lilypond +program into many files of different formats, including +.FONT CI eps +files, using +.EX +.FONT CB "$ lilypond \-\-ps \-dbackend=eps \-dgs\-load\-fonts \-\-output=" I file\-name +.EE +for each +.FONT CB .ly +file. +. +The output +.I file\-name +must be provided without an extension, its directory is temporary.. +. +. +.P +There are many +.FONT CI EPS +files created. +. +One having the complete transformed +.FONT CB ly +file, named +.FONT I file\-name CB .eps R . +. +. +.P +Moreover there are +.FONT CI EPS +files for each page, named +.FONT I file\-name CB \- I digit CB .eps R . +. +. +.P +The last step to be done is replacing all +.FONT CI lilypond +parts by the collection of the corresponding +.FONT CI EPS +page files. +. +This is done by +.FONT CI groff +commands +.EX +.FONT CB ".PSPIC " CI file-name CB \- I digit CB .eps +.EE +. +. +.\" -------------------------------------------------------------------- +.SS "Mode pdf2eps" +.\" -------------------------------------------------------------------- +. +This mode can be chosen by the option +.FONT CB --pdf2eps R . +. +. +.P +In this mode, the +.FONT CB .ly +files are transformed by the +.BR lilypond (1) +program into +.FONT CI pdf +files, using +.EX +.FONT CB "lilypond \-\-pdf \-\-output=" I file-name +.EE +for each +.FONT CB .ly +file. +. +The +.I file-name +must be provided without the extension +.FONT CB .pdf R . +. +By this process, a file +.FONT CI file-name CB .pdf +is generated. +. +. +.P +The next step is to transform these +.FONT CI PDF +files into a +.FONT CI PS +file. +. +This is done by the +.BR pdf2ps (1) +program using +.EX +.FONT R "$ " CB "pdf2ps " CI file-name CB ".pdf " CI file-name CB ".ps" +.EE +. +. +The next step creates an +.FONT CI EPS +file from the +.FONT CI PS +file. +. +This is done by the +.BR ps2eps (1) +program using +.EX +.FONT R "$ " CB "ps2eps " CI file-name CB ".ps" +.EE +. +. +.P +By that, a file +.FONT CI file-name CB .eps +is created for each +.FONT CI lilypond +part in the +.FONT CI groff +file or standard input. +. +. +.P +The last step to be done is replacing all +.FONT CI lilypond +parts by the +.FONT CI groff +command +.EX +.FONT CB ".PSPIC " CI file-name CB .eps +.EE +. +. +.\" -------------------------------------------------------------------- +.SH "THE GENERATED NEW ROFF STRUCTURE" +.\" -------------------------------------------------------------------- +. +The new +.BR groff (@MAN7EXT@) +structure generated by +.FONT CB glilypond +is either +. +.TP +1) +sent to standard output and can there be saved into a file or piped into +.BR groff (@MAN1EXT@) +or +.BR groffer (@MAN1EXT@) +or +. +.TP +2) +stored into a file by given the option +.OP -o\fR|\fB\~--output file_name +. +. +.\" -------------------------------------------------------------------- +.SH "SEE ALSO" +.\" -------------------------------------------------------------------- +. +.TP +.BR groff (@MAN1EXT@) +the usage of the groff program and pointers to the documentation and +availability of the +.FONT CI groff +system. +. +The main source of information for the +.FONT CI groff +szstem is the +.FONT CB groff +.BR info (1) +file. +. +. +.TP +.BR groff (@MAN7EXT@) +documents the +.FONT CI groff +language. +. +. +.TP +.BR groff_tmac (@MAN5EXT@) +contains documentation of the +.FONT CB .PSPIC +request. +. +. +.TP +.BR lilypond (1) +The documentation of the +.FONT CB lilypond +program. +. +The main source of information for the +.FONT CI lilypond +language is the +.FONT CB lilypond +.BR info (1) +file. +. +. +.TP +.BR pdf2ps (1) +transform a +.FONT CI PDF +file into a +.FONT CI Postscript +format. +. +. +.TP +.BR ps2eps (1) +transform a +.FONT CI PS +file into an +.FONT CI EPS +format. +. +. +.\" -------------------------------------------------------------------- +.SH "AUTHORS" +.\" -------------------------------------------------------------------- +.authors +. +. +.\" -------------------------------------------------------------------- +.SH "COPYING" +.\" -------------------------------------------------------------------- +.copying +. +. +.\" -------------------------------------------------------------------- +.\" Emacs settings +.\" -------------------------------------------------------------------- +. +.\" Local Variables: +.\" mode: nroff +.\" End: |