@node Invoking LilyPond
@chapter Invoking LilyPond
+This chapter details the technicalities of running LilyPond.
+
+
@menu
+* Invoking the lilypond binary::
* Reporting bugs::
-* Website::
-* Invoking ly2dvi:: Titling LilyPond scores.
+* Point and click::
+* Invoking ly2dvi:: Titling LilyPond scores.
@end menu
+
+
+@node Invoking the lilypond binary
+@section Invoking the lilypond binary
@cindex Invoking LilyPond
@cindex command line options
@cindex options, command line
@cindex switches
-Usage:
+
+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} binary. However,
+@code{lilypond} may be called directly as follows.
@example
lilypond [@var{option}]@dots{} @var{file}@dots{}
@end example
-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 invoked with a filename that has no extension, the @file{.ly}
+extension is tried first. To read input from stdin, use a
+dash @code{-} for @var{file}.
-When LilyPond processes @file{filename.ly} it will produce
+When @file{filename.ly} is processed 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 .}
+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
+ default settings from within Scheme.}
@section Command line options
(for ASCII-art).
@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}.
+these is usable for real work.
@cindex output format, setting
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
+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.
@end ignore
@item -v,--version
-Show version information
+Show version information.
@item -V,--verbose
Be verbose: show full paths of all files read, and give timing
information.
@section Environment variables
-For processing both the @TeX{} and the PostScript output, you must
-have appropriate environment variables set. The following scripts do
-this:
+For processing both the @TeX{} and the PostScript output, the
+appropriate environment variables must be set. The following scripts
+do this:
@itemize @bullet
@item @file{buildscripts/out/lilypond-profile}
-(for sh shells)
+(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.
+They should normally be sourced as part of the login process. If these
+scripts are not run from the system wide login process, then you must
+run it yourself.
@cindex installing LilyPond
@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.
+point to the directory containing library 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.
+point to the directory containing PFA files.
When you print direct PS output, remember to send the PFA files to the
printer as well.
@cindex TEXMF
@cindex printing postscript
-The LilyPond binary itself recognizes the following environment variables
+The binary itself recognizes the following environment variables
@table @code
@item LILYPONDPREFIX
This specifies a directory where locale messages and
subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
@item LANG
-This selects the language for the warning messages of LilyPond.
+This selects the language for the warning messages
@end table
@cindex LANG
-@cindex bugs
-@cindex reporting bugs
@node Reporting bugs
@section Reporting bugs
+@cindex bugs
+@cindex 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!
+need to wait for the prize money to grow. 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:
+Development moves quickly, so if you have a problem, it is
+wise to check if it has been fixed in a newer release. If not, please
+send in a bugreport. When you send us a bugreport, we have to
+diagnose the problem and if necessary, 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 The version number
@item A description of the platform you use (i.e., operating system,
system libraries, whether you downloaded a binary release)
@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.
+You can send the report to @email{bug-lilypond@@gnu.org}.
+
+@node Point and click
+@section Point and click
+@cindex poind and click
+
+Point and click lets you find notes in the input by clicking on them in
+the Xdvi window. This makes it easier to find input that causes some
+error in the sheet music.
+
+To use it, you need the following software
+@itemize @bullet
+@item A dvi viewer that supports src specials.
+@itemize @bullet
+@item Xdvi, version 22.36 or newer. Available from
+@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
+
+ Most @TeX{} distributions ship with xdvik, which is always
+ a few versions behind the official Xdvi. To find out which Xdvi you
+ are running, try @code{xdvi -version} or @code{xdvi.bin -version}.
+@item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or
+newer. Enable option @emph{Inverse search} in the menu @emph{Settings}.
+
+Apparently, KDVI does not process PostScript specials correctly. Beams
+and slurs will not be visible in KDVI.
+
+@cindex Xdvi
+@cindex KDVI
+@cindex KDE
+
+
+
+@end itemize
+@item An editor with a client/server interface (or a lightweight GUI
+editor).
+
+@cindex editor
+
+@itemize @bullet
+@item Emacs. Emacs is an extensible text-editor. It is available from
+@uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
+column location.
+
+@c move this elsewhere?
+
+There is also support for emacs: lilypond-mode for emacs 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.
+
+@cindex emacs
+@cindex emacs mode
+@cindex lilypond-mode for emacs
+@cindex syntax coloring
+
+@item XEmacs. Xemacs is very similar to emacs.
+
+@cindex XEmacs
+
+@item NEdit. NEdit runs under Windows, and Unix.
+ It is available from @uref{http://www.nedit.org}.
-@node Website
-@section Website
+@cindex NEdit
+
+@item GVim. GVim is a GUI variant of VIM, the popular VI
+clone. It is available from @uref{http://www.vim.org}.
+
+@cindex GVim
+@cindex Vim
+
+@end itemize
+@end itemize
+
+
+Xdvi must be configured to find the @TeX{} fonts and music
+fonts. Refer to the Xdvi documentation for more information.
+
+To use point-and-click, add one of these lines to the top of your .ly
+file.
+@example
+#(ly:set-point-and-click 'line)
+@end example
+@cindex line-location
+
+When viewing, Control-Mousebutton 1 will take you to the originating
+spot in the @file{.ly} file. Control-Mousebutton 2 will show all
+clickable boxes.
+
+If you correct large files with point-and-click, be sure to start
+correcting at the end of the file. When you start at the top, and
+insert one line, all following locations will be off by a line.
+
+@cindex Emacs
+For using point-and-click with emacs, add the following
+In your emacs startup file (usually @file{~/.emacs}),
+@example
+(server-start)
+@end example
+
+Make sure that the environment variable @var{XEDITOR} is set to
+@example
+emacsclient --no-wait +%l %f
+@end example
+@cindex @var{XEDITOR}
+If you use xemacs instead of emacs, you use @code{(gnuserve-start)} in
+your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}
+
+For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
+use this argument with Xdvi's @code{-editor} option.
+
+@cindex NEdit
+For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
+use this argument with Xdvi's @code{-editor} option.
+
+If can also make your editor jump to the exact location of the note
+you clicked. This is only supported on Emacs and VIM. Users of Emacs version
+20 must apply the patch @file{emacsclient.patch}. Users of version 21
+must apply @file{server.el.patch} (version 21.2 and earlier). At the
+top of the @code{ly} file, replace the @code{set-point-and-click} line
+with the following line,
+@example
+#(ly:set-point-and-click 'line-column)
+@end example
+@cindex line-colomn-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.
-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
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.
+ Write @code{Makefile} dependencies for every input file.
@item -h,--help
Print usage help.
@item -I,--include=@var{dir}
@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
+ If you use lilypond-book or your own wrapper files, do not use
+@code{\usepackage[[T1]@{fontenc@}} in the file header but do not forget
@code{\usepackage[latin1]@{inputenc@}} if you use any other
non-anglosaxian characters.
@code{pagenumber}, @code{linewidth}, @code{orientation},
@code{textheight}.
@item -v,--version
-Show version information .
+Show version information.
@item -V,--verbose
Be verbose.
@item --debug
Name of the arranger, right flushed below the opus.
@item instrument
Name of the instrument, centered below the arranger
-@item dedication
- [docme]
+@item dedication
+ To whom the piece is dedicated.
@item piece
Name of the piece, left flushed below the instrument
@item head
@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
+section of the input file. They can be overridden by supplying a
@code{--set} command line option.
@table @code
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