]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/invoking.itexi
* scm/page-layout.scm (plain-header): add printpagenumber boolean
[lilypond.git] / Documentation / user / invoking.itexi
index 67bafae06f01d3064498e207aa2d92177cbee82c..9d1b0008a028b9a2bfd8214f40a923c95d2acb97 100644 (file)
@@ -2,36 +2,45 @@
 @node Invoking LilyPond
 @chapter Invoking LilyPond
 
+This chapter details the technicalities of running LilyPond.
+
 @menu
+* Invoking lilypond::           
+* Error messages::              
 * Reporting bugs::              
-* Website::                     
-* Invoking ly2dvi::           Titling LilyPond scores.
+* Editor support::              
+* Point and click::             
+* Invoking lilypond-latex::     
 @end menu
 
+@node Invoking lilypond
+@section Invoking lilypond
 @cindex Invoking LilyPond
 @cindex command line options
 @cindex options, command line
 @cindex switches
 
-Usage:
+
+The @code{lilypond} may be called as follows from the command line.
 
 @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
+system defaults from within Scheme.}
 
 
 @section Command line options
@@ -43,28 +52,21 @@ The following options are supported:
 @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.  The function @code{ly-set-option} allows for access to
-some internal variables.  Use @code{-e '(ly-option-usage')} for more
+sequentially.  The function @code{ly:set-option} allows for access to
+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 ly2dvi),
-@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 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. More information can be found at
-@uref{http://lilypond.org/wiki?OutputFormats}.
+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
 
@@ -76,27 +78,47 @@ Add @var{directory} to the search path for input files.
 @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 -M,--dependencies
-Output rules to be included in Makefile.
 @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.
 
-@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
+
+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.
 
-@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
+In @code{--safe} mode, it is not possible to import LilyPond variables
+into Scheme. 
 
 @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.
@@ -109,35 +131,38 @@ Show the warranty with which GNU LilyPond comes. (It comes with
 @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
 
 If you use sh, bash, or a similar shell, then add the following to
-your @file{.profile}
+your @file{.profile}:
 @example
-       . lilypond-profile
+       . @var{/the/path/to/}lilypond-profile
 @end example
 
 If you use csh, tcsh or a similar shell, then add the following to
-your @file{~/.login}
+your @file{~/.login}:
 @example
-       source lilypond-login
+       source @var{/the/path/to/}lilypond-login
 @end example
 
-These scripts set the following variables
+Of course, in both cases, you should substitute the proper location of
+either script.
+
+These scripts set the following variables:
 @table @code
 @item TEXMF
  To make sure that @TeX{} and lilypond find data files (among
@@ -152,12 +177,12 @@ file tree. A typical setting would be
 @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.
@@ -171,7 +196,7 @@ 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
@@ -179,171 +204,337 @@ data files will be looked up by default. The directory should contain
 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 LILYPONDPREFIX
 
+@node Error messages
+@section Error messages
+
+@cindex error messages
+Different error messages can appear while compiling a file:
+
+@table @emph
+@cindex warning
+
+@item Warning
+  Something looks suspect. If you are requesting something out of the
+ordinary then you will understand the message, and can ignore it.
+However, warnings usually indicate that something is wrong with the
+input file.
+
+@item Error
+Something is definitely wrong.  The current processing step (parsing,
+interpreting, or formatting) will be finished, but the next step will
+be skipped.
+
+@cindex error
+@cindex fatal error
+@item Fatal error
+Something is definitely wrong, and LilyPond cannot continue. This
+happens rarely. The most usual cause is misinstalled fonts.
+
+@cindex trace, Scheme
+@cindex call trace
+@cindex Scheme error
+@item Scheme error
+Errors that occur while executing Scheme code are caught by the Scheme
+interpreter. If running with the verbose option (@code{-V} or
+@code{--verbose}) then a call trace is printed of the offending
+function call.
+
+@cindex Programming error
+@item Programming error
+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, 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.
 
 
-@cindex bugs
-@cindex reporting bugs
+@end table
+
+@cindex errors, message format
+If warnings and errors can
+be linked to some part of the input file, then error messages have the
+following form
+
+@example
+  @var{filename}:@var{lineno}:@var{columnno}: @var{message}
+  @var{offending input line}
+@end example 
+
+A line-break is inserted in offending line to indicate the column
+where the error was found. For example, 
+
+@example
+test.ly:2:19: error: not a duration: 5:
+  \notes @{ c'4 e'5 
+                   g' @}
+@end example
+
 
 @node Reporting bugs
 @section 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!
+@cindex bugs
+@cindex reporting bugs
+
+If you have input that results in a crash or an erroneous output, then
+that is a bug. We try respond to bug-reports promptly, and fix them as
+soon as possible. For this, we need to reproduce and isolate the
+problem. 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 you use, and on which
+platform you run it.  Send the report to
+@email{bug-lilypond@@gnu.org}.
+
+@node Editor support
+@section Editor support
+
+@cindex editors
+@cindex vim
+@cindex emacs
+@cindex modes, editor 
+@cindex syntax coloring
+@cindex coloring, syntax
+
+There is support from different editors  for LilyPond.
+
+@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 point and click
+
+@cindex source specials
+@cindex specials, source
+
+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
+
+
 
-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:
+@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?
+
+
+@cindex Emacs
+@cindex Emacs mode
+@cindex lilypond-mode for Emacs
+@cindex syntax coloring
+
+@item XEmacs. XEmacs is very similar to Emacs.
 
-@item A sample input which causes the error.  Please have mercy on the
-developers, send a @emph{small} sample file.
+@cindex XEmacs
 
-@item The version number of lilypond.
+@item NEdit.  NEdit runs under Windows, and Unix.
+  It is available from @uref{http://www.nedit.org}.
 
-@item A description of the platform you use (i.e., operating system,
-system libraries, whether you downloaded a binary release)
+@cindex NEdit
 
-@item If necessary, send a description of the bug itself.  If you
-include output a ly2dvi run, please use @code{--verbose} option of
-ly2dvi.
+@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
 
-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.
 
-@node Website
-@section Website
+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-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}.
 
-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
-@section Invoking ly2dvi
+@node Invoking lilypond-latex
+@section Invoking lilypond-latex
 
-Nicely titled output is created through a separate program:
-@file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
-nicely titled piece of sheet music, in DVI format or PostScript.
+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
-        ly2dvi [@var{option}]@dots{} @var{file}@dots{}
+        @code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{}
 @end example
 
-To have ly2dvi read from stdin, use a dash @code{-} for @var{file}.
+To have @code{lilypond-latex} read from stdin, use a dash @code{-} for
+@var{file}.  The program supports the following options.
 
-Ly2dvi supports the following options:
+@cindex stdin, reading
 
 @table @code
 @item -k,--keep
-    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.
+    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 LilyPond; useful for debugging ly2dvi.
 @item -o,--output=@var{file}
     Generate output to @var{file}.  The extension of @var{file} is ignored.
-@item -P,--postscript
-    Also generate PostScript output, using dvips.  The postscript uses
-the standard @TeX{} bitmap fonts for your printer.
-@item -p,--pdf
-    Also generate Portable Document Format (PDF).  This option will
-generate a PS file using scalable fonts, and will run the PS file
-through @code{ps2pdf} producing a PDF file.
-
-@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
-@code{\usepackage[latin1]@{inputenc@}} if you use any other
-non-anglosaxian characters.
-
-    @item --preview
+@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{pagenumber}, @code{linewidth}, @code{orientation},
+@code{linewidth}, @code{orientation},
 @code{textheight}.
 @item -v,--version
-Show version information 
+Show version information.
 @item -V,--verbose
-Be 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
-
-Ly2dvi extracts the following header fields from the LY files to
-generate titling:
-
-@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 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.
-@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 ``Lily
-was here, @var{version-number}''.
-@end table
-
-
-@cindex header
-@cindex footer
-@cindex page layout
-@cindex titles
-
 
 
 @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
-@code{--set} command line option.
+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
@@ -354,8 +545,7 @@ included.  Default: unset.
 
 @item latexheaders
     Specify additional La@TeX{} headers file.
-
-        Normally read from the @code{\header} block. Default value: empty
+        Normally read from the @code{\header} block. Default value: empty.
 
 @item latexpackages
     Specify additional La@TeX{} packages file. This works cumulative,
@@ -366,9 +556,9 @@ so you can add multiple packages using multiple @code{-s=latexpackages} options.
 @item latexoptions
     Specify additional options for the La@TeX{}
 @code{\documentclass}. You can put any valid value here. This was
-designed to allow ly2dvi to produce output for double-sided paper,
-with balanced margins and pagenumbers on alternating sides. To achieve
-this specify @code{twoside}
+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
@@ -385,30 +575,11 @@ 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
+@item fontenc
      The font encoding, should be set identical to the @code{font-encoding}
      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