+@c -*-texinfo-*-
@node Invoking LilyPond
@chapter Invoking LilyPond
@menu
-* Reporting bugs::
-* Website::
-* Titling LilyPond scores::
+* Reporting bugs::
+* Website::
+* Invoking ly2dvi:: Titling LilyPond scores.
@end menu
@cindex Invoking LilyPond
Usage:
@example
- lilypond [@var{options}] @var{file}@dots{}
+ 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}.
@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 -e,--evaluate=@var{expr}
+Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
+Multiple @code{-e} options may be given, they will be evaluated
+sequentially. The function @code{ly-set-option} allows for access to
+some internal variables. Use @code{-e '(ly-option-usage')} for more
+information.
+
+@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}.
-@item -f,--format=@var{format} 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), and @code{as} (for
-ASCII-art).
+@cindex output format, setting
+@cindex Sketch output
+@cindex ASCII-art output
+@cindex PDFTeX output
+@cindex PostScript output
+@cindex Scheme dump
-Unless you have special requirements, you should use @TeX{}
-output. All other options are experimental.
@item -h,--help
Show a summary of usage.
@item --include, -I=@var{directory}
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.
+have appropriate environment variables set. The following scripts do
+this:
+
+@itemize @bullet
+@item @file{buildscripts/out/lilypond-profile}
+(for sh shells)
+@item @file{buildscripts/out/lilypond-login} (for C-shells)
+@end itemize
+
+They 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
website at @uref{http://www.lilypond.org/}.
-@node Titling LilyPond scores
-@section Titling LilyPond scores
+@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.
-@subsection Invoking ly2dvi
-
-@c ly2dvi needs at least one FILE, can't act as filter yet
@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 -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.
-@item --preview
+ 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
@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}
+ 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
the @code{\paper} block.
@item pagenumber
- If set to @code{no}, no page numbers will be printed.
-
+ 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
@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