@menu
-* Invoking lilypond:: Titling LilyPond scores.
-* Invoking the lilypond binary::
+* Invoking lilypond::
* Error messages::
* Reporting bugs::
* Editor support::
* Point and click::
+* Invoking lilypond-latex::
@end menu
@node Invoking lilypond
@section Invoking lilypond
-
-Nicely titled output is created through a separate program:
-@file{@code{lilypond}} is a script that uses the LilyPond formatting
-engine (which is in a separate program) and La@TeX{} to create a
-nicely titled piece of sheet music, in PDF (Portable Document Format)
-format.
-
-@example
- @code{lilypond} [@var{option}]@dots{} @var{file}@dots{}
-@end example
-
-To have @code{lilypond} read from stdin, use a dash @code{-} for
-@var{file}. The program supports the following options.
-
-@table @code
-@item -k,--keep
- Keep the temporary directory with all output
-files. The temporary directory is created in the current directory as @code{@code{lilypond}.dir}.
-@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 @file{lilypond-bin}. Useful for debugging @code{lilypond}.
-@item -o,--output=@var{file}
- Generate output to @var{file}. The extension of @var{file} is ignored.
-@item --no-pdf
- Do not generate (PDF) or PS.
-
-@cindex PDF
-@cindex Scalable fonts
-
-@item --png
- Also generate pictures of each page, in PNG format.
-@item --psgz
- Gzip the postscript file.
-@item --html
- Make a .HTML file with links to all output files.
-@item --preview
- Also generate a picture of the first system of the score.
-
-@cindex preview
-@cindex picture
-@cindex bitmap
-@cindex pixmap
-@cindex thumbnail
-@cindex screen shot
-
-@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. This prints out commands as they are executed, and more
-information about the formatting process is printed.
-@item --debug
-Print even more information. This is useful when generating bug reports.
-@item -w,--warranty
-Show the warranty with which GNU LilyPond comes. (It comes with
-@strong{NO WARRANTY}!)
-@end table
-
-@subsection Titling layout
-
-@code{lilypond} extracts the following header fields from the LY files
-to generate titling; an example demonstrating all these fields is in
-@inputfileref{input/test,lilypond-testpage.ly}:
-
-@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 dedication
- To whom the piece is dedicated.
-@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. Note that if the
- score consists of only a single page, the first page is also the
- last page, and in this case, the tagline is printed instead of the
- copyright.
-@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 ``Engraved
-by LilyPond @var{version-number}''.
-@end table
-
-
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
-
-
-
-@subsection Additional parameters
-
-The @code{lilypond} program responds to several parameters specified
-in a @code{\paper} section of the input 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 @code{lilypond} to produce output for double-sided
-paper, with balanced margins and page numbers 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
-
-
-
-@node Invoking the lilypond binary
-@section Invoking the lilypond binary
@cindex Invoking LilyPond
@cindex command line options
@cindex options, command line
@cindex switches
-The formatting system consists of two parts: a binary executable
-(@file{lilypond-bin}), which is responsible for the formatting
-functionality, and support scripts, which post-process the resulting
-output. Normally, the support scripts are called, which in turn invoke
-the @code{lilypond-bin} binary. However, @code{lilypond-bin} may be
-called directly as follows.
+The @code{lilypond} may be called as follows from the command line.
@example
- lilypond-bin [@var{option}]@dots{} @var{file}@dots{}
+ lilypond [@var{option}]@dots{} @var{file}@dots{}
@end example
block, then the rest of the scores will be output 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
- system defaults from within Scheme.}
-
-We strongly advise against making LilyPond formatting available
-through a web server. That is, processing input from untrusted users,
-and returning the resulting PDF file. LilyPond is a big and complex
-program. It was not written with security in mind. Making it available
-to the outside world is a huge risk; consider the security
-implications of
-
-@verbatim
- #(system "rm -rf /")
- \score {
- c4^#(ly:export (ly:gulp-file "/etc/passwd"))
- }
-@end verbatim
+GUILE is not reset across invocations, so be careful not to change any
+system defaults from within Scheme.}
@section Command line options
@item -f,--format=@var{format}
@c
@c
-Output format for sheet music. Choices are @code{tex} (for @TeX{}
-output, to be processed with La@TeX{}, or through @code{lilypond}),
-@code{pdftex} for PDF@TeX{} input, @code{ps} (for PostScript),
-@code{scm} (for a Scheme dump), @code{sk} (for Sketch).
+A comma separated list of back-end output formats to use. Choices are
+@code{tex} (for @TeX{} output, to be processed with La@TeX{}, and
+@code{ps} for PostScript.
-@strong{This option is only for developers}. Only the @TeX{} output of
-these is usable for real work.
+Other output options are intended for developers.
@cindex output format, setting
-@cindex Sketch output
-@cindex PDFTeX output
@cindex PostScript output
@cindex Scheme dump
@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 -o,--output=@var{FILE}
-Set the default output file to @var{FILE}.
+ Set the default output file to @var{FILE}.
+@item --ps
+ Generate PostScript.
+@item --dvi
+ Generate DVI files. In this case, the @TeX{} backend should be
+ specified, i.e. @code{-f tex}.
+@item --png
+ Generate pictures of each page, in PNG format. This implies @code{--ps}.
+@item --pdf
+ Generate PDF. This implies @code{--ps}.
+@item --preview
+ Generate an output file containing the titles and the first system
+of the score.
@item -s,--safe
-Disallow untrusted @code{\include} directives, limit available in-line
-Scheme function, disable backslashes in @TeX{}, code.
+Do not trust the @code{.ly} input.
+
+When LilyPond formatting available through a web server, the
+@code{--safe} @b{MUST} be passed. This will prevent code like
+
+@verbatim
+ #(system "rm -rf /")
+ \score {
+ c4^#(ly:export (ly:gulp-file "/etc/passwd"))
+ }
+@end verbatim
+
+The @code{--safe} option works by evaluating in-line Scheme
+expressions in a special safe module. This safe module is derived from
+GUILE @file{safe-r5rs} module, but adds a number of functions of the
+LilyPond API. These functions are listed in @file{safe-lily.scm}.
+
+In addition, @code{--safe} disallows @code{\include} directives and
+disables the use of backslashes in @TeX{} strings.
+
+In @code{--safe} mode, it is not possible to import LilyPond variables
+into Scheme.
@item -v,--version
Show version information.
ignored. Sometimes, they come in such big quantities that they obscure
other output. In this case, file a bug-report.
+@item Aborted (core dumped)
+This signals a serious programming error that caused the program to
+crash. Such errors are considered critical. If you stumble on one,
+send a bugreport.
+
+
@end table
@cindex errors, message format
users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
+
+@node Invoking lilypond-latex
+@section Invoking lilypond-latex
+
+Before LilyPond 3.0, the @code{lilypond} program only generated music
+notation. Titles and page layout was done in a separate wrapper
+program. For compatibility with older files, this wrapper program has
+been retained as @code{lilypond-latex}. It uses the LilyPond program
+and La@TeX{} to create a nicely titled piece of sheet music. Use of
+this program is only necessary if the input file contains special
+La@TeX{} options or formatting codes in markup texts.
+
+The @code{lilypond-latex} wrapper is invoked from the command-line as
+follows
+@example
+ @code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{}
+@end example
+
+To have @code{lilypond-latex} read from stdin, use a dash @code{-} for
+@var{file}. The program supports the following options.
+
+@cindex stdin, reading
+
+@table @code
+@item -k,--keep
+ Keep the temporary directory with all output
+files. The temporary directory is created in the current directory as @code{@code{lilypond}.dir}.
+@item -h,--help
+ Print usage help.
+@item -I,--include=@var{dir}
+ Add @var{dir} to LilyPond's include path.
+@item -o,--output=@var{file}
+ Generate output to @var{file}. The extension of @var{file} is ignored.
+@item --png
+ Also generate pictures of each page, in PNG format.
+@item --preview
+ Also generate a picture of the first system of the score.
+
+@cindex preview
+@cindex picture
+@cindex bitmap
+@cindex pixmap
+@cindex thumbnail
+@cindex screen shot
+
+@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{linewidth}, @code{orientation},
+@code{textheight}.
+@item -v,--version
+Show version information.
+@item -V,--verbose
+Be verbose. This prints out commands as they are executed, and more
+information about the formatting process is printed.
+@item --debug
+Print even more information. This is useful when generating bug reports.
+@item -w,--warranty
+Show the warranty with which GNU LilyPond comes. (It comes with
+@strong{NO WARRANTY}!)
+@end table
+
+
+
+@subsection Additional parameters
+
+The @code{lilypond} program responds to several parameters specified
+in a @code{\paper} section of the input 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 @code{lilypond} to produce output for double-sided
+paper, with balanced margins and page numbers 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 fontenc
+ The font encoding, should be set identical to the @code{font-encoding}
+ property in the score.
+@end table
+
+
+
projects / lilypond.git / blobdiff