+@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 [OPTION]... [MUDELA-FILE]...
+ lilypond [@var{option}]@dots{} @var{file}@dots{}
@end example
-@unnumberedsec Command Options
+
+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.
+@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}
-Output format for sheet music. Choices are tex (for @TeX{}
-output), ps (for PostScript) and scm (for a Scheme
-dump).
+@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).
-For processing both the @TeX{} and the PostScript output, you must
-have appropriate environment variables set. For @TeX{}, you have to
-set @code{MFINPUTS} and @code{TEXINPUTS} to point to the directory
-containing LilyPond metafont and .tex files. For processing the
-PostScript with Ghostscript, you have to set @code{GS_FONTPATH} to
-point to the directory containing LilyPond @file{pfa} files.
+@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}.
-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 run as part of your login process.
+@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=DIRECTORY
-Add @file{DIRECTORY} to the search path for input files.
+@item --include, -I=@var{directory}
+Add @var{directory} to the search path for input files.
@cindex file searching
@cindex search path
-@item -i,--init=FILE
-Set init file to @file{FILE} (default: @file{init.ly}).
+@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, it will do the
-midi output only.
+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=FILE
-Set the default output file to @file{FILE}.
+@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
+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
+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
-When invoked with a filename that has no extension, LilyPond will try
-adding `@file{.ly}' as an extension first.
-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 .}
+For processing both the @TeX{} and the PostScript output, you must
+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
+
+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
-@section Environment variables
+@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 LILYINCLUDE
-additional directories for finding lilypond data. The
-format is like the format of @file{PATH}.
@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
-selects the language for the warning messages of LilyPond.
+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
projects / lilypond.git / blobdiff