@menu
* Invoking lilypond::
+* Notes for the MacOS X app::
* Error messages::
* Updating files with convert-ly::
* Reporting bugs::
* Editor support::
-* File structure::
-* Including LilyPond files::
@end menu
@node Invoking lilypond
@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.
+sequentially.
+
+The expression will be evaluated in the @code{guile-user} module, so
+if you want to use definitions in @var{expr}, use
+
+@example
+lilypond -e '(define-public a 42)'
+@end example
+
+@noindent
+on the command-line, and include
+
+@example
+#(use-modules (guile-user))
+@end example
+
+@noindent
+at the top of the @code{.ly} file.
@item -f,--format=@var{format}
which formats should be written. Choices are @code{svg}, @code{ps},
@item -h,--help
Show a summary of usage.
+@item -H,--header=FIELD
+Dump a header field to file BASENAME.FIELD
+
@item --include, -I=@var{directory}
Add @var{directory} to the search path for input files.
@cindex file searching
@end table
+@node Notes for the MacOS X app
+@section Notes for the MacOS X app
+
+The scripts (such as lilypond-book, convert-ly, abc2ly, etc.) are also
+included inside MacOS X .app. They can be run from the command line by
+invoking them directly, e.g.
+
+@example
+@var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly
+@end example
+
@node Error messages
@section Error messages
If you have input that results in a crash or an erroneous output, then
that is a bug. We try to respond to bug-reports promptly, and fix them as
soon as possible. Help us by sending a defective input file, so we can
-reproduce the problem. Make it small, so we can easily debug the
-problem. Don't forget to tell which version of LilyPond you use! Send
-the report via
+reproduce the problem. Send the report via:
@example
@uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
@end example
+A few tips:
+@itemize @bullet
+
+@item Try to produce a very small input file which demonstrates the problem;
+one or two bars is often sufficient to reproduce a bug. The smaller the
+input file is, the easier it is for us to debug the problem.
+
+@item Don't forget to tell which version of LilyPond you use!
+
+@item If possible, use @code{ragged-right} in your example. This makes sure
+that the bug can be reproduced in all paper sizes.
+@end itemize
+
@ignore
@c the bug database is not up to date enough.
Here is an example of a good bug report:
-@example
+@verbatim
It seems that placement of accidentals is broken. In the
following example, the accidental touches the note head.
Using Mac OSX 10.3.7, fink package lilypond-devel
\version "2.7.32"
-\relative c''@{
+\layout { ragged-right = ##t }
+\relative c'' {
a4 b cis d
-@}
-@end example
+}
+@end verbatim
@lilypond[quote]
-\version "2.7.32"
+\layout { ragged-right = ##t }
\relative c''{
\override Accidental #'extra-offset = #'(1.0 . 0)
a4 b cis d
of a symbol in the graphical output. See @ref{Point and click}.
-@node File structure
-@section File structure
-
-The major part of this manual is concerned with entering various
-forms of music in LilyPond. However, many music expressions are not
-valid input on their own, for example, a @code{.ly} file containing
-only a note
-@example
-c'4
-@end example
-
-@noindent
-will result in a parsing error. Instead, music should be inside other
-expressions, which may be put in a file by themselves. Such
-expressions are called toplevel expressions. This section enumerates
-them all.
-
-A @code{.ly} file contains any number of toplevel expressions, where a
-toplevel expression is one of the following
-
-@itemize @bullet
-@item
-An output definition, such as @code{\paper}, @code{\midi}, and
-@code{\layout}. Such a definition at the toplevel changes the default
-settings for the block entered.
-
-@item
-A @code{\header} block. This sets the global header block. This
-is the block containing the definitions for book-wide settings, like
-composer, title, etc.
-
-@item
-An @code{\addquote} statement. See @ref{Quoting other voices}
-for more information.
-
-@item
-A @code{\score} block. This score will be collected with other
-toplevel scores, and combined as a single @code{\book}.
-
-This behavior can be changed by setting the variable
-@code{toplevel-score-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-
-The @code{\score} must begin with music, and may contain only
-one music block.
-
-@item
-A @code{\book} block logically combines multiple movements
-(i.e., multiple @code{\score} blocks) in one document. A number of
-@code{\scores} creates a single output file, where all movement are
-concatenated.
-
-This behavior can be changed by setting the variable
-@code{toplevel-book-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-
-@item
-A compound music expression, such as
-@example
-@{ c'4 d' e'2 @}
-@end example
-
-This will add the piece in a @code{\score} and format it in a
-single book together with all other toplevel @code{\score}s and music
-expressions.
-
-This behavior can be changed by setting the variable
-@code{toplevel-music-handler} at toplevel. The default handler is
-defined in the init file @file{scm/@/lily@/.scm}.
-
-@item
-A markup text, a verse for example
-@example
-\markup @{
- 2. The first line verse two.
-@}
-@end example
-
-Markup texts are rendered above, between or below the scores or music
-expressions, wherever they appear.
-
-@item
-An identifier, such as
-@example
-foo = @{ c4 d e d @}
-@end example
-
-This can be used later on in the file by entering @code{\foo}. The
-name of an identifier should have alphabetic characters only; no
-numbers, underscores or dashes.
-
-@end itemize
-
-The following example shows three things that may be entered at
-toplevel
-
-@example
-\layout @{
- % movements are non-justified by default
- ragged-right = ##t
-@}
-
-\header @{
- title = "Do-re-mi"
-@}
-
-@{ c'4 d' e2 @}
-@end example
-
-
-At any point in a file, any of the following lexical instructions can
-be entered:
-
-@itemize @bullet
-@item @code{\version}
-@item @code{\include}
-@item @code{\renameinput}
-@end itemize
-
-
-@node Including LilyPond files
-@section Including LilyPond files
-
-@cindex @code{\include}
-@cindex including files
-
-A large project may be split up into separate files. To refer to another
-file, use
-
-@example
-\include "otherfile.ly"
-@end example
-
-The line @code{\include "file.ly"} is equivalent to pasting the contents
-of file.ly into the current file at the place where you have the
-\include. For example, for a large project you might write separate files
-for each instrument part and create a ``full score'' file which brings
-together the individual instrument files.
-
-The initialization of LilyPond is done in a number of files that are
-included by default when you start the program, normally transparent to the
-user. Run lilypond --verbose to see a list of paths and files that Lily
-finds.
-
-Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
-VERSION is in the form ``2.6.1'') are on the path and available to
-@code{\include}. Files in the
-current working directory are available to \include, but a file of the same
-name in LilyPond's installation takes precedence. Files are
-available to \include from directories in the search path specified as an
-option when invoking @code{lilypond --include=DIR} which adds DIR to the search
-path.
-
-The @code{\include} statement can use full path information, but with the Unix
-convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
-if @file{stuff.ly} is located one directory higher than the current working
-directory, use
-
-@example
-\include "../stuff.ly"
-@end example