* scripts/lilypond-book.py (option_definitions): typo

[lilypond.git] / Documentation / user / invoking.itexi

diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi
index ab2b5bd1aba1876bd14d1c29072ef5841ce4a903..feaa644aafe3b72b40480284344c6560448d2b09 100644 (file)
--- a/Documentation/user/invoking.itexi
+++ b/Documentation/user/invoking.itexi
@@ -2,36 +2,49 @@
 @node Invoking LilyPond
 @chapter Invoking LilyPond
 
 @node Invoking LilyPond
 @chapter Invoking LilyPond
 

+This chapter details the technicalities of running LilyPond.
+
+ 

 @menu
 @menu

+* Invoking the lilypond binary::  

 * Reporting bugs::              
 * Reporting bugs::              

-* Website::                     
-* Invoking ly2dvi::           Titling LilyPond scores.
+* Point and click::             
+* Invoking ly2dvi::             Titling LilyPond scores.

 @end menu
 
 @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
 
 @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
 
 
 
 @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}
 @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
 
 
 @section Command line options


@@ -57,8 +70,7 @@ output, to be processed with plain @TeX{}, or through ly2dvi),
 (for ASCII-art).
 
 @strong{This option is only for developers}. Only the @TeX{} output of
 (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
 
 
 @cindex output format, setting


@@ -78,7 +90,7 @@ Add @var{directory} to the search path for input files.
 Set init file to @var{file} (default: @file{init.ly}).
 @item -m,--no-paper
 @cindex MIDI
 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.
 will be generated.
 @item -M,--dependencies
 Output rules to be included in Makefile.


@@ -96,7 +108,7 @@ web). Volunteers are welcome to do a new audit.
 @end ignore
 
 @item -v,--version
 @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.
 @item -V,--verbose
 Be verbose: show full paths of all  files read, and give timing
 information.


@@ -109,19 +121,19 @@ Show the warranty with which GNU LilyPond comes. (It comes with
 @section Environment variables
 
 
 @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}
 
 @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
 
 @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
 
 
 @cindex installing LilyPond
 


@@ -152,12 +164,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
 @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
 
 @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.
 
 When you print direct PS output, remember to send the PFA files to the
 printer as well.


@@ -171,7 +183,7 @@ printer as well.
 @cindex TEXMF
 @cindex printing postscript
 
 @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
 @table @code
 @item LILYPONDPREFIX
 This specifies a directory where locale messages and


@@ -179,7 +191,7 @@ data files will be looked up by default. The directory should contain
 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
 
 @item LANG
 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
 @end table
 
 @cindex LANG


@@ -187,28 +199,31 @@ This selects the language for the warning messages of LilyPond.
 
 
 
 
 
 

-@cindex bugs
-@cindex reporting bugs

 
 @node Reporting bugs
 @section 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
 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.
 
 
 @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)
 
 @item A description of the platform you use (i.e., operating system,
 system libraries, whether you downloaded a binary release)


@@ -219,15 +234,143 @@ ly2dvi.
 
 @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.
+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
 
 
 @node Invoking ly2dvi


@@ -250,7 +393,7 @@ Ly2dvi supports the following options:
     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
     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}
 @item -h,--help
     Print usage help.
 @item -I,--include=@var{dir}


@@ -272,8 +415,8 @@ through @code{ps2pdf} producing a PDF file.
 @cindex PDF
 @cindex Scalable fonts
     
 @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{\usepackage[latin1]@{inputenc@}} if you use any other
 non-anglosaxian characters.
 


@@ -300,7 +443,7 @@ in the files. Possible keys: @code{language}, @code{latexheaders},
 @code{pagenumber}, @code{linewidth}, @code{orientation},
 @code{textheight}.
 @item -v,--version
 @code{pagenumber}, @code{linewidth}, @code{orientation},
 @code{textheight}.
 @item -v,--version

-Show version information .
+Show version information.

 @item -V,--verbose
 Be verbose.
 @item --debug
 @item -V,--verbose
 Be verbose.
 @item --debug


@@ -333,8 +476,8 @@ generate titling. An example demonstrating all these fields is in
     Name of the arranger, right flushed below the opus.
 @item instrument
     Name of the instrument, centered below the arranger
     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
 @item piece
     Name of the piece, left flushed below the instrument
 @item head


@@ -361,7 +504,7 @@ was here, @var{version-number}''.
 @subsection Additional parameters
 
 Ly2dvi responds to several parameters specified in a @code{\paper}
 @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
 @code{--set} command line option.
 
 @table @code


@@ -415,19 +558,4 @@ positive integer, start with this value as the first page number.
      property in the score.
 @end table
 
      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
-