.TH "lily2image" "1" "1.2" "Jonathan Kulp, Patrick Horgan" "Lilypond Helper Tools"
.SH "NAME"
.LP 
lily2image \- Convert lilypond source files into cropped musical examples in a variety of image formats.
.SH "SYNTAX"
.LP 
lily2image [\fIoption\fP] [\fIoption\fP] <\fIfilename.ly\fP>
.br 
.SH "DESCRIPTION"
.LP 
This program is designed to use Lilypond source files to create musical examples suitable for insertion in documents and web pages.  It requires the \fBnetpbm\fR package of image\-manipulation tools and supports a large variety of image formats. Without options, it gathers user preferences interactively to set the following parameters: resolution, background transparency, and desired output format. 
.SH "OPTIONS"
.LP 
.TP 
\fB\-r=<res>, \-\-resolution=<res>\fR
Set resolution to DPI specified by numeric value.
.TP 
\fB\-f=<frmt>, \-\-format=<frmt>\fR
Set desired image format.  For a full list of supported formats, see manpages for the pnmto<format> and ppmto<format> tools from \fBnetpbm\fR.
.TP 
\fB\-q, \-\-quiet\fR
All echo messages are suppressed and terminal is silent throughout conversion process. If any parameters are not set at command line, program assumes defaults (-f=png, -r=150).  If any errors occur, check return status for error codes.
.TP 
\fB\-p\fR
Preview. Display converted image in default image viewer, or in user\-specified viewer if set with \-V.
.TP 
\fB\-t, \-\-transparency\fR 
Set background to transparent (without this option background is white). Only png and gif formats support transparent background.
.TP 
\fB\-a, \-\-about\fR
Output program information end exit. 
.TP 
\fB\-u\fR
Output usage information and exit.
.TP 
\fB\-v\fR
Output version information and exit.
.TP 
\fB\-V=<viewer>\fR
Specify image viewer. Options are "evince", eye of gnome ("eog"), and "gwenview" in Linux; "preview" in OSX.
.TP 
.SH "EXAMPLES"
.LP 
Since no options are set, this example will run the program in interactive mode:
.LP 
     lily2image filename.ly
.LP 
You may specify options at the command line. The following example creates a gif image with transparent background at a resolution of 300 dpi:
.LP 
     lily2image \-r=300 \-f=gif \-t filename.ly
.LP 
The next example converts to png. Since resolution is not set, user will be prompted to enter resolution value:
.LP 
     lily2image \-f=png filename.ly
.LP 
In this example, the resolution is still not set, but user will NOT be prompted to enter resolution value because quiet mode is specified.  Resolution will be the default 150 DPI:
.LP 
     lily2image \-f=png \-q filename.ly
.LP 
The last example will produce a gif image at 250 DPI with transparent background. It will run in quiet mode (suppressing all echo messages) but will display image in Evince viewer when finished since the \-p option is set and Evince is selected:
.LP 
     lily2image \-f=gif \-r=250 \-t \-q \-p \-V=evince filename.ly
.SH "EXIT STATUS"
.LP
In quiet mode, program exits with various return codes.
.PD 0
.TP
.I 0
Conversion successful.
.TP
.I 40
Transparency not set and no default.
.TP
.I 41
Format not set and no default.
.TP
.I 42
Resolution not set and no default.
.TP
.I 43
Netpbm utilities not installed.
.TP
.I 44
Unable to find conversion program for desired output.
.TP
.I 45
Resolution from command line not positive numeric.
.TP
.I 46
Format from command line invalid

.SH "AUTHORS"
.LP 
Jonathan Kulp, Patrick Horgan.
.SH "SEE ALSO"
.LP 
netpbm, lilypond.