* Documentation/user/lilypond.tely: Add dir entries for

[lilypond.git] / Documentation / user / invoking.itexi

@c -*-texinfo-*-
@node Invoking LilyPond
@chapter Invoking LilyPond

@menu
* Reporting bugs::              
* Website::                     
* Invoking ly2dvi::           Titling LilyPond scores.
@end menu

@cindex Invoking LilyPond
@cindex command line options
@cindex options, command line
@cindex switches

Usage:

@example
        lilypond [@var{option}]@dots{} @var{file}@dots{}
@end example


When invoked with a filename that has no extension, LilyPond will try
to add @file{.ly} as an extension first.  To have LilyPond read from
stdin, use a dash @code{-} for @var{file}.

When LilyPond processes @file{filename.ly} it will produce
@file{filename.tex} as output (or @file{filename.ps} for PostScript
output).  If @file{filename.ly} contains more than one @code{\score}
block, then LilyPond will output the rest in numbered files, starting
with @file{filename-1.tex}.  Several files can be specified; they will
each be processed independently.  @footnote{The status of GUILE is not
reset across invocations, so be careful not to change any default
settings from within Scheme .}


@section Command line options

The following options are supported:

@table @code

@item -e,--evaluate=@var{code}
  Evaluates the Scheme @var{code} before parsing @file{.ly}
files. Multiple @code{-e} options may be given. They will be evaluated
sequentially. The function @code{set-lily-option} may be invoked to
set various debugging options.



@item -f,--format=@var{format}
@c
@c
Output format for sheet music. Choices are @code{tex} (for @TeX{}
output, to be processed with plain @TeX{}, or through ly2dvi),
@code{pdftex} for PDF@TeX{} input, @code{ps} (for PostScript),
@code{scm} (for a Scheme dump), @code{sk} (for Sketch) and @code{as}
(for ASCII-art).

@strong{This option is only for developers}. Only the @TeX{} output of
these is usable for real work. More information can be found at
@uref{http://lilypond.org/wiki?OutputFormats}.


@cindex output format, setting
@cindex Sketch output
@cindex ASCII-art output
@cindex PDFTeX output
@cindex PostScript output
@cindex Scheme dump

@item -h,--help
Show a summary of usage.
@item --include, -I=@var{directory}
Add @var{directory} to the search path for input files.
@cindex file searching
@cindex search path
@item -i,--init=@var{file}
Set init file to @var{file} (default: @file{init.ly}).
@item -m,--no-paper
@cindex MIDI
Disable @TeX{} output. If you have a @code{\midi} definition midi output
will be generated.
@item -M,--dependencies
Output rules to be included in Makefile.
@item -o,--output=@var{FILE}
Set the default output file to @var{FILE}.

@ignore
@item -s,--safe
Disallow untrusted @code{\include} directives, in-line
Scheme evaluation, backslashes in @TeX{}, code.

@strong{WARNING}: the @code{--safe} option has not been reviewed for a
long time. Do not rely on it for automatic invocation (e.g. over the
web). Volunteers are welcome to do a new audit.
@end ignore

@item -v,--version
Show version information 
@item -V,--verbose
Be verbose: show full paths of all  files read, and give timing
information.

@item -w,--warranty
Show the warranty with which GNU LilyPond comes. (It comes with 
@strong{NO WARRANTY}!)
@end table

@section Environment variables


For processing both the @TeX{} and the PostScript output, you must
have appropriate environment variables set.  Scripts to do this are
included in @file{buildscripts/out/lilypond-profile} (for sh shells)
and @file{buildscripts/out/lilypond-login} (for C-shells), and should
normally be sourced as part of your login process. If these scripts
are not run from the system wide login process, then you must run it
yourself.

@cindex installing LilyPond

If you use sh, bash, or a similar shell, then add the following to
your @file{.profile}
@example
        . lilypond-profile
@end example

If you use csh, tcsh or a similar shell, then add the following to
your @file{~/.login}
@example
        source lilypond-login
@end example

These scripts set the following variables
@table @code
@item TEXMF
 To make sure that @TeX{} and lilypond find data files (among
others @file{.tex}, @file{.mf} and @file{.tfm}),
you have to set @code{TEXMF} to point to the lilypond data
file tree. A typical setting would be
@example
@{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
@end example


@item GS_LIB
For processing PostScript output (obtained with
@code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
point to the directory containing LilyPond PS files.

@item GS_FONTPATH
For processing PostScript output (obtained with
@code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
point to the directory containing LilyPond PFA files.

When you print direct PS output, remember to send the PFA files to the
printer as well.
@end table


@cindex ghostscript
@cindex PostScript
@cindex GS_FONTPATH
@cindex GS_LIB
@cindex TEXMF
@cindex printing postscript

The LilyPond binary itself recognizes the following environment variables
@table @code
@item LILYPONDPREFIX
This specifies a directory where locale messages and
data files will be looked up by default. The directory should contain
subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.

@item LANG
This selects the language for the warning messages of LilyPond.
@end table

@cindex LANG
@cindex LILYPONDPREFIX



@cindex bugs
@cindex reporting bugs

@node Reporting bugs
@section Reporting bugs

Since there is no finder's fee which doubles every year, there is no
need to wait for the prize money to grow. So send a bug report today!

LilyPond development moves quickly, so if you have a problem, it is
wise to check if it has been fixed in a newer release.  If you think
you found a bug, please send in a bugreport.  When you send us a
bugreport, we have to diagnose the problem and if possible, duplicate
it.  To make this possible, it is important that you include the
following information in your report:

@itemize @bullet

@item A sample input which causes the error.  Please have mercy on the
developers, send a @emph{small} sample file.

@item The version number of lilypond.

@item A description of the platform you use (i.e., operating system,
system libraries, whether you downloaded a binary release)

@item If necessary, send a description of the bug itself.  If you
include output a ly2dvi run, please use @code{--verbose} option of
ly2dvi.

@end itemize

You can send the report to @email{bug-lilypond@@gnu.org}. This is a
mailinglist, but you don't have to be subscribed to it to post.

@node Website
@section Website

If you are reading this manual in print, it is possible that the
website contains updates to the manual. You can find the lilypond
website at @uref{http://www.lilypond.org/}.


@node Invoking ly2dvi
@section Invoking ly2dvi

Nicely titled output is created through a separate program:
@file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
nicely titled piece of sheet music, in DVI format or PostScript.

@example
        ly2dvi [@var{option}]@dots{} @var{file}@dots{}
@end example

To have ly2dvi read from stdin, use a dash @code{-} for @var{file}.

Ly2dvi supports the following options:

@table @code
@item -k,--keep
    Keep the temporary directory including LilyPond and ly2dvi output
files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
@item -d,--dependencies
    Write makefile dependencies for every input file.
@item -h,--help
    Print usage help.
@item -I,--include=@var{dir}
    Add @var{dir} to LilyPond's include path.
@item -m,--no-paper
    Produce MIDI output only.
@item --no-lily
    Do not run LilyPond; useful for debugging ly2dvi.
@item -o,--output=@var{file}
    Generate output to @var{file}.  The extension of @var{file} is ignored.
@item -P,--postscript
    Also generate PostScript output, using dvips.  The postscript uses
the standard @TeX{} bitmap fonts for your printer.
@item -p,--pdf
    Also generate Portable Document Format (PDF).  This option will
generate a PS file using scalable fonts, and will run the PS file
through @code{ps2pdf} producing a PDF file.

@cindex PDF
@cindex Scalable fonts
    
    If you use lilypond-book or your own wrapper files, don't use
@code{\usepackage[[T1]@{fontenc@}} in the file header but don't forget
@code{\usepackage[latin1]@{inputenc@}} if you use any other
non-anglosaxian characters.

    @item --preview
    Also generate a picture of the first system of the score.
@item -s,--set=@var{key}=@var{val}
    Add @var{key}= @var{val} to the settings, overriding those specified
in the files. Possible keys: @code{language}, @code{latexheaders},
@code{latexpackages}, @code{latexoptions}, @code{papersize},
@code{pagenumber}, @code{linewidth}, @code{orientation},
@code{textheight}.
@item -v,--version
Show version information 
@item -V,--verbose
Be verbose
@item -w,--warranty
Show the warranty with which GNU LilyPond comes. (It comes with 
@strong{NO WARRANTY}!)
@end table

@subsection Titling layout

Ly2dvi extracts the following header fields from the LY files to
generate titling:

@table @code
@item title
    The title of the music. Centered on top of the first page.
@item subtitle
    Subtitle, centered below the title.
@item poet
    Name of the poet, left flushed below the subtitle.
@item composer
    Name of the composer, right flushed below the subtitle.
@item meter
    Meter string, left flushed below the poet.
@item opus
    Name of the opus, right flushed below the composer.
@item arranger
    Name of the arranger, right flushed below the opus.
@item instrument
    Name of the instrument, centered below the arranger
@item piece
    Name of the piece, left flushed below the instrument
@item head
    A text to print in the header of all pages. It is not called
@code{header}, because @code{\header} is a reserved word in LilyPond.
@item copyright
    A text to print in the footer of the first page. Default is to 
    print the standard footer also on the first page.
@item footer
    A text to print in the footer of all but the last page.
@item tagline
    Line to print at the bottom of last page. The default text is ``Lily
was here, @var{version-number}''.
@end table


@cindex header
@cindex footer
@cindex page layout
@cindex titles



@subsection Additional parameters

Ly2dvi responds to several parameters specified in a @code{\paper}
section of the LilyPond file. They can be overridden by supplying a
@code{--set} command line option.

@table @code
@item language
    Specify La@TeX{} language: the @code{babel} package will be
included.  Default: unset.

        Read from the @code{\header} block.

@item latexheaders
    Specify additional La@TeX{} headers file.

        Normally read from the @code{\header} block. Default value: empty

@item latexpackages
    Specify additional La@TeX{} packages file. This works cumulative,
so you can add multiple packages using multiple @code{-s=latexpackages} options.
       Normally read from the @code{\header} block. Default value:
@code{geometry}.

@item latexoptions
    Specify additional options for the La@TeX{}
@code{\documentclass}. You can put any valid value here. This was
designed to allow ly2dvi to produce output for double-sided paper,
with balanced margins and pagenumbers on alternating sides. To achieve
this specify @code{twoside}

@item orientation
    Set orientation. Choices are @code{portrait} or @code{landscape}. Is
read from the @code{\paper} block, if set.
        
@item textheight
    The vertical extension of the music on the page. It is normally 
    calculated automatically, based on the paper size.

@item linewidth
        The music line width. It is normally read from the @code{\paper}
block.

@item papersize
   The paper size (as a name, e.g. @code{a4}). It is normally read from
the @code{\paper} block.

@item pagenumber
   If set to @code{no}, no page numbers will be printed.  If set to a
positive integer, start with this value as the first page number.

  
  @item fontenc
     The font encoding, should be set identical to the @code{font-encoding}
     property in the score.
@end table

@subsection Environment variables

@table @code
@item LANG
selects the language for the warning messages of Ly2dvi and LilyPond.

@item GUILE_MAX_SEGMENT_SIZE
is an option for GUILE, the scheme interpreter; it sets the size of
the chunks of memory allocated by GUILE.  By increasing this from its
default 8388608, the performance of LilyPond on large scores is
slightly improved.


@end table