path: root/contrib/glilypond/glilypond.man

.TH glilypond @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
.SH NAME
glilypond \- integrate lilypond parts into groff
.
.\" 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: 25 Apr 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 "\&.\|.\|.\&\"
.ad l
.
.
.\" --------------------------------------------------------------------
.\" 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 optional final character
.\" Example: `.OP+ -p | --prefix ly .' gets `[-p|--prefix ly].'
.\" Example: `.OP+ -h | --help | --usage' gets `[-h|--help|--usage]'
.\" Example: `.OP+ -v | --verbose "" ,' gets `[-v|--verbose],'
.\"
.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
.  \}
.  ie ( \\n[.$] == 0 ) .as result \f[CR]]\fR
.  el .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+ --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 option, 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 | -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 following 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 CB \-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 CB \-\-version
cannot be abbreviated further than
.FONT CB \-\-vers
because there is also the
.FONT CI "long option " CB \-\-verbose
that can be abbreviated up to
.FONT CB \-\-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: