@code{lilypond} [@var{option}]@dots{} @var{file}@dots{}
@end example
-To have @code{lilypond} read from stdin, use a dash @code{-} for @var{file}.
+To have @code{lilypond} read from stdin, use a dash @code{-} for
+@var{file}. The program supports the following options.
-The @code{lilypond} 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 -d,--dependencies
- Write @code{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 @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 bitmap
@cindex pixmap
@cindex thumbnail
-@cindex screenshot
+@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{linewidth}, @code{orientation},
@code{textheight}.
@item -v,--version
Show version information.
@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
@item latexheaders
Specify additional La@TeX{} headers file.
-
+<
Normally read from the @code{\header} block. Default value: empty.
@item latexpackages
@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
+@item fontenc
The font encoding, should be set identical to the @code{font-encoding}
property in the score.
@end table
@cindex switches
-The LilyPond system consists of two parts: a binary executable, 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 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.
@example
lilypond-bin [@var{option}]@dots{} @var{file}@dots{}
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.}
+GUILE is not reset across invocations, so be careful not to change any
+system defaults from within Scheme.}
@section Command line options
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
+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 @code{lilypond}),
-@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).
+A comma separated list of output formats. 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 ASCII-art output
-@cindex PDFTeX output
@cindex PostScript output
@cindex Scheme dump
@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.
+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
-@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
+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.
There was some internal inconsistency. These error messages are
intended to help the programmers and debuggers. Usually, they can be
ignored. Sometimes, they come in such big quantities that they obscure
-other output. In this case, a bug-report should be filed.
+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
There is support from different editors for LilyPond.
-Emacs has a @file{lilypond-mode}, which provides keyword
+@table @asis
+@item Emacs
+ Emacs has a @file{lilypond-mode}, which provides keyword
autocompletion, indentation, LilyPond specific parenthesis matching
and syntax coloring, handy compile short-cuts and reading LilyPond
manuals using Info. If lilypond-mode is not installed on your
platform, then refer to the installation instructions for more
information.
+@item VIM
+
For @uref{http://www.vim.org,VIM}, a vimrc is supplied, along with
syntax coloring tools. For more information, refer to the
@ifhtml
@uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
@end ifhtml
-
@ifnothtml
installation instructions.
@end ifnothtml
+
For both editors, there is also a facility to jump in the input file
to the source of errors in the graphical output. See @ref{Point and
click}.
+@item JEdit
+
There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to
the @uref{http://lily4jedit.sourceforge.net,plugin website} for more
information.
+@end table
@node Point and click
@section Point and click
-@cindex poind and click
+@cindex point and click
@cindex source specials
@cindex specials, source
@example
#(ly:set-point-and-click 'line-column)
@end example
-@cindex line-colomn-location
+@cindex line-column-location
and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim
users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
-
-@refbugs
-
-When you convert the @TeX{} file to PostScript using @code{dvips}, it
-will complain about not finding @code{src:X:Y} files. These complaints
-are harmless, and can be ignored.
-
-
-
projects / lilypond.git / blobdiff