-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
@node Running LilyPond
@chapter Running LilyPond
@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},
This mode is used by default by lilypond-book.
@item svg
- for SVG (Scalable Vector Graphics)
+ for SVG (Scalable Vector Graphics). This dumps every page as a separate
+@file{SVG} file, with embedded fonts.
@cindex SVG (Scalable Vector Graphics)
+ You need a SVG viewer which supports embedded fonts, or a SVG
+ viewer which is able to replace the embedded fonts with OTF fonts.
+ Under Unix, you may use @uref{http://www.inkscape.org,Inkscape}
+ (version 0.42 or later), after copying the OTF fonts in directory
+ @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
@item scm
for a dump of the raw, internal Scheme-based drawing commands.
@cindex Scheme dump
@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
@item --dvi
Generate DVI files. In this case, the @TeX{} backend should be
-specified, i.e., @code{-f tex}.
+specified, i.e., @code{-b tex}.
@item --png
Generate pictures of each page, in PNG format. This implies
@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
+
+Alternatively, you may add this directory to your path. Modify (or create)
+a file called @code{.profile} in your home directory such that it contains
+
+@example
+export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
+@end example
+
+@noindent
+This file should end with a blank line.
+
+Note that @var{path/to} will generally be @code{/Applications/}.
+
+
@node Error messages
@section Error messages
@node Updating files with convert-ly
@section Updating with @command{convert-ly}
+@cindex Updating a LilyPond file
+@cindex @code{convert-ly}
+
The LilyPond input syntax is routinely changed to simplify it or improve
it in different ways. As a side effect of this, the LilyPond interpreter
often is no longer compatible with older input files. To remedy this,
@ignore
Copy and paste from CVS, last updated
-May 26, 2005
+Aug 18, 2005
http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
@end ignore
\magnify isn't changed to \fontsize.
- \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
remove-tag isn't changed.
- - \applymusic #(remove-tag '. . .) => \keepWithTag #'. . .
- firstpagenumber isn't changed.
- - firstpagenumber no => printfirstpagenumber = ##f
+ - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
+ first-page-number isn't changed.
+ - first-page-number no => printfirst-page-number = ##f
Line breaks in header strings aren't converted.
- \\\\ as line break in \header strings => \markup \center-align <
"First Line" "Second Line" >
\markup{ \center-align <{ ... }> } should be converted to:
\markup{ \center-align {\line { ... }} }
but now, \line is missing.
+2.4->2.6
+ Special LaTeX characters such as $~$ in text are not converted to UTF8.
@end verbatim
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 to @email{bug-lilypond@@gnu.org}.
+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.5.18"
-\relative c''@{
+\version "2.7.32"
+\layout { ragged-right = ##t }
+\relative c'' {
a4 b cis d
-@}
-@end example
+}
+@end verbatim
@lilypond[quote]
-\version "2.5.18"
+\layout { ragged-right = ##t }
\relative c''{
\override Accidental #'extra-offset = #'(1.0 . 0)
a4 b cis d
manuals using Info. If @file{lilypond-mode} is not installed on your
platform, then read the
@ifhtml
-@uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
+@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
@end ifhtml
@ifnothtml
installation instructions.
For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied, along
with syntax coloring tools. For more information, refer to the
@ifhtml
-@uref{source/Documentation/topdocs/out-www/INSTALL.html,installation instructions}.
+@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
@end ifhtml
@ifnothtml
installation instructions.
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 indentifier, 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
- raggedright = ##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
projects / lilypond.git / blobdiff