path: root/contrib/lilypond/groff_lilypond.man

.TH groff_lilypond @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
.SH NAME
groff\-lilypond \[em] integrate \f[CI]lilypond\f[] 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: 22 Feb 2013
..
.
.
.de copying
groff_lilypond \[em] integrate lilypond into groff files
.
.P
.EX
Source file position: <groff-source>/contrib/lilypond/groff_lilypond.man
Installed position: <prefix>/share/man/man1/groff_lilypond.1
.EE
.
.P
Copyright \(co 2013
.RS
.ft CI
Free Software Foundation, Inc.
.ft R
.RE
.
.P
This file is part of
.ft CI
GNU groff\\f[R].
.
.P
.ft CI
GNU groff
.ft R
is free software is free software: you can redistribute it and/or modify it
under the terms of the
.ft CI
GNU General Public License
.ft R
as published by the
.ft CI
Free Software Foundation\fR, either
.ft CI
version 3
.ft R
of the
.IR License ,
or
.RI ( "at your option" )
any later version.
.
.P
.ft CI
GNU groff
.ft R
is distributed in the hope that it will be useful, but
.ft CI
WITHOUT ANY WARRANTY\fR; without even the implied warranty of
.ft CI
MERCHANTABILITY
.ft R
or
.ft CI FITNESS FOR A PARTICULAR PURPOSE\fR.
See the
.ft CI
GNU General Public License
.ft R
for more details.
.
.P
.P
You should have received a copy of the
.nh
.ft CI
GNU General Public License
.ft R
.hy
along with
.ft CI
groff\\f[R], see the files
.nh
.ft CB
COPYING
.ft R
and
.ft CB
LICENSE
.ft R
.hy
in the top directory of the
.ft CI
groff
.ft R
source package.
.
If not, see
.UR http://\\:www.gnu.org/\\:licenses/
 the
.ft CI
GNU licenses
.ft R
.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
..
.
.
.\" --------------------------------------------------------------------
.SH "SYNOPSIS"
.\" --------------------------------------------------------------------
.
.SY groff_lilypond
.OP options
.OP -
.OP --
.OP \%filespec \*[Ellipsis]
.YS
.
.
.\" --------------------------------------------------------------------
.SH DESCRIPTION
.\" --------------------------------------------------------------------
.
.FONT CB groff_lilypond
transforms sheet music in the
.FONT CI lilypond
language in a
.FONT CI groff
file such that
.FONT CB groff
can display them.
.
.
.P
Without arguments or without
.I filespec
arguments,
.FONT CB groff_lilypond
reads from standard input.
.
Several files can be used; the minus character
.FONT CB \[em]
stands for standard input.
.
.
.\" --------------------------------------------------------------------
.SH "OPTION OVERVIEW"
.\" --------------------------------------------------------------------
.
.\" --------------------------------------------------------------------
.SS "Breaking Options"
.\" --------------------------------------------------------------------
.TP
.I breaking options
.RS
.P
.SY
.OP -h\~\fR|\fB\~--help
.OP -v\~\fR|\fB\~--version
.OP \fB\~--license
.YS
.RE
.
.
.TP
.I \%groff_lilypond mode options
.RS
.
.TP
.OP --pdf2eps
The program
.FONT CB groff_lilypond
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 .
.
.
.TP
.OP --ly2eps
Here the
.FONT CB lilypond
program creates
.FONT CI eps
files directly.
.
.
.RE
.
.
.TP
.I \%directories and files
.RS
.
.TP
.OP --file_prefix 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 --keep_files
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 --temp_dir dir
With this option, you can change the directory in which the temporary
files are stored.
.
No extensions are used for this directory.
.
If the directory does not exist it will be created.
.
.
.RE
.
.
.\" --------------------------------------------------------------------
.SH "FINDING THE LILYPOND PARTS IN A ROFF FILE OR STANDARD INPUT"
.\" --------------------------------------------------------------------
.
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
file can have several of these
.FONT CI lilypond
parts.
.
.
.P
These
.FONT CI lilypond
parts are sent into temporary files with the file name extension
.FONT CB .ly R .
.
There a 2 modes to transform these files.
.
.
.\" --------------------------------------------------------------------
.SH "LY\-FILE INCLUSION"
.\" --------------------------------------------------------------------
.
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
files.
.
One file can be included per
.FONT CI include
command.
.
.
.P
If this command is written outside a
.FONT CI lilypond
part, one new
.FONT CB .ly  R file
is created for all files in the argument, which will be transformed
afterwards when writing is done.
.
.
.P
Within a
.FONT CI lilypond
part, this inclusion is not possible.
.
So
.FONT CB ".lilypond include"
may not be used between
.FONT CB ".lilypond start"
and
.FONT CB ".lilypond end" .R .
.
.
.\" --------------------------------------------------------------------
.SH "TRANSFORMATION 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
.
.
.\" --------------------------------------------------------------------
.SH "TRANSFORMATION 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
.FONT CB lilypond
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
.FONT CB pdf2ps
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
.FONT CB ps2eps
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 "NEW ROFF STRUCTURE"
.\" --------------------------------------------------------------------
.
The new
.BR groff (@MAN7EXT@)
structure generated by
.FONT CB groff_lilypond
is sent to standard output.
.
It can either be saved in a file or piped to
.BR groff (@MAN1EXT@)
or
.BR groffer (@MAN1EXT@)
for a display.
.
.
.\" --------------------------------------------------------------------
.SH "TEMPORARY FILES"
.\" --------------------------------------------------------------------
.
By the transformation process, there are many temporary files
generated.
.
All of them except the
.FONT CI EPS
files are deleted when the
.FONT CB groff_lilypond
process is finished.
.
.
.P
These
.FONT CI EPS
files are stored in a temporary directory.
.
But they cannot be deleted by the transformation process because they
are needed for the display which can take a long time.
.
.
.\" --------------------------------------------------------------------
.SH "DISPLAY"
.\" --------------------------------------------------------------------
.
The display maps each
.FONT CI lilypond
part on a complete page, preceded and followed by a page break.
.
I do not know how to change this or what very long music sheets will
do.
.
.
.\" --------------------------------------------------------------------
.SH "AUTHORS"
.\" --------------------------------------------------------------------
.authors
.
.
.\" --------------------------------------------------------------------
.SH "COPYING"
.\" --------------------------------------------------------------------
.copying
.
.
.\" --------------------------------------------------------------------
.\" Emacs settings
.\" --------------------------------------------------------------------
.
.\" Local Variables:
.\" mode: nroff
.\" End: