@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond.tely
+@c This file is part of lilypond-program.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
@node Running LilyPond
@chapter Running LilyPond
This chapter details the technicalities of running LilyPond.
Some of these commands are run from the command-line. By
-``command-line'', we mean the command
+@q{command-line}, we mean the command
line in the operating system. Windows users
-might be more familiar with the terms ``DOS shell'' or
-``command shell''; OSX users might be more familiar with the
-terms ``terminal'' or ``console''. OSX users should also
+might be more familiar with the terms @q{DOS shell} or
+@q{command shell}; OSX users might be more familiar with the
+terms @q{terminal} or @q{console}. OSX users should also
consult @ref{Notes for the MacOS X app}.
Describing how to use
@menu
* Invoking lilypond::
-* Notes for the MacOS X app::
* Updating files with convert-ly::
* Reporting bugs::
* Error messages::
-* Editor support::
-* Point and click::
@end menu
@node Invoking lilypond
GUILE is not reset after processing a @code{.ly} file, so be careful
not to change any system defaults from within Scheme.}
+In addition, the value of @code{output-suffix} will be inserted between
+the basename and the number. An input file containing
+
+@example
+#(define output-suffix "violin")
+\book @{ @dots{} @}
+#(define output-suffix "cello")
+\book @{ @dots{} @}
+@end example
+
+@noindent
+will output @var{base}@file{-violin.ps} and
+@var{base}@file{-cello-1.ps}.
+
+
@subsection Command line options
at the top of the @code{.ly} file.
@item -f,--format=@var{format}
-which formats should be written. Choices are @code{svg}, @code{ps},
-@code{pdf}, @code{png}, @code{tex}, @code{dvi}.
+which formats should be written. Choices for @code{format} are
+@code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
+
+Example: @code{lilypond -fpng filename.ly}
+
+
+
+@item -d,--define-default=@var{var}=@var{val}
+This sets the internal program option @var{var} to the Scheme value
+@var{val}. If @var{val} is not supplied, then @var{#t} is used. To
+switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
+
+@cindex point and click, command line
+
+@example
+-dno-point-and-click
+@end example
-@item -b,--backend=@var{format}
-the output format to use for the back-end. Choices are
+@noindent
+is the same as
+@example
+-dpoint-and-click='#f'
+@end example
+
+Here are a few interesting options.
+
+@table @samp
+@item help
+Running @code{lilypond -dhelp} will print all of the @code{-d} options
+available.
+
+@item paper-size
+This option sets the default paper-size,
+@example
+-dpaper-size=\"letter\"
+@end example
+
+@noindent
+Note that the string must be enclosed in escaped quotes ( @code{\"} ).
+
+
+@item safe
+Do not trust the @code{.ly} input.
+
+When LilyPond formatting is available through a web server, either the
+@code{--safe} or the @code{--jail} option @b{MUST} be passed. The
+@code{--safe} option will prevent inline Scheme code from wreaking
+havoc, for example
+
+@quotation
+@verbatim
+#(system "rm -rf /")
+{
+ c4^#(ly:export (ly:gulp-file "/etc/passwd"))
+}
+@end verbatim
+@end quotation
+
+The @code{-dsafe} 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{scm/@/safe@/-lily@/.scm}.
+
+In addition, safe mode disallows @code{\include} directives and
+disables the use of backslashes in @TeX{} strings.
+
+In safe mode, it is not possible to import LilyPond variables
+into Scheme.
+
+safe does @emph{not} detect resource overuse. It is still possible to
+make the program hang indefinitely, for example by feeding cyclic data
+structures into the backend. Therefore, if using LilyPond on a
+publicly accessible webserver, the process should be limited in both
+CPU and memory usage.
+
+The safe mode will prevent many useful LilyPond snippets from being
+compiled. The @code{--jail} is a more secure alternative, but
+requires more work to set up.
+
+@item backend
+the output format to use for the back-end. Choices for @code{format} are
@table @code
@item tex
for @TeX{} output, to be processed with La@TeX{}. If present, the file
@cindex Scheme dump
@end table
-@cindex output format, setting
-
-@item -d,--define-default=@var{var}=@var{val}
-This sets the internal program option @var{var} to the Scheme value
-@var{val}. If @var{val} is not supplied, then @var{#t} is used. To
-switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
-
-@cindex point and click, command line
+Example: @code{lilypond -dbackend=svg filename.ly}
-@example
--dno-point-and-click
-@end example
+@cindex output format, setting
-@noindent
-is the same as
-@example
--dpoint-and-click='#f'
-@end example
+@item preview
+Generate an output file containing the titles and the first system
-Another notable option is
+@item print-pages
+Generate the full pages, the default. @code{-dno-print-pages} is
+useful in combination with @code{-dpreview}.
-@example
--dpaper-size=\"letter\"
-@end example
+@end table
-@noindent
-Note that the string must be enclosed in escaped quotes ( @code{\"} ).
-Setting the @code{-dhelp} option will print a summary of the options
-available, and exit.
@item -h,--help
Show a summary of usage.
@item --dvi
Generate DVI files. In this case, the @TeX{} backend should be
-specified, i.e., @code{-b tex}.
+specified, i.e., @code{-dbackend=tex}.
@item --png
Generate pictures of each page, in PNG format. This implies
@item --pdf
Generate PDF. This implies @code{--ps}.
-@item --preview
-Generate an output file containing the titles and the first system
-
-@item --no-pages
-Do not generate the full pages. Useful in combination with
-@code{--preview}.
-
-@item -s,--safe
-Do not trust the @code{.ly} input.
-
-When LilyPond formatting is available through a web server, either the
-@code{--safe} or the @code{--jail} option @b{MUST} be passed. The
-@code{--safe} option will prevent inline Scheme code from wreaking
-havoc, for example
-
-@quotation
-@verbatim
-#(system "rm -rf /")
-{
- c4^#(ly:export (ly:gulp-file "/etc/passwd"))
-}
-@end verbatim
-@end quotation
-
-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{scm/@/safe@/-lily@/.scm}.
-
-In addition, @code{--safe} disallows @code{\include} directives and
-disables the use of backslashes in @TeX{} strings.
-
-In @code{--safe} mode, it is not possible to import LilyPond variables
-into Scheme.
-
-@code{--safe} does @emph{not} detect resource overuse. It is still
-possible to make the program hang indefinitely, for example by feeding
-cyclic data structures into the backend. Therefore, if using LilyPond
-on a publicly accessible webserver, the process should be limited in
-both CPU and memory usage.
-
-Note that @code{--safe} will prevent many useful LilyPond snippets from
-being compiled. For a softer but secure alternative you can use the
-@code{--jail} option.
@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
@cindex LANG
-@cindex LILYPONDPREFIX
+@cindex LILYPOND_DATADIR
@code{Lilypond} recognizes the following environment variables:
@table @code
-@item LILYPONDPREFIX
+@item LILYPOND_DATADIR
This specifies a directory where locale messages and
data files will be looked up by default. The directory should contain
subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
@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, and even
-lilypond itself) 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/lilypond
-@end example
-
-@noindent
-The same is true of the other scripts in that directory, including
-lilypond-book, convert-ly, abc2ly, etc.
-
-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 Updating files with convert-ly
@section Updating with @command{convert-ly}
@cindex Updating a LilyPond file
-@funindex convert-ly
+@cindex 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
convert-ly --from=... --to=... --no-version *.itely
@end example
+To see the changes in the LilyPond syntax between two versions, use
+
+@example
+convert-ly --from=... --to=... -s
+@end example
+
To upgrade many files at once, combine @code{convert-ly} with
standard unix commands. This example will upgrade all @code{.ly}
files in the current directory
@cindex reporting bugs
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. 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.
+that is a bug. There is a list of current bugs on our google bug tracker,
-@item Don't forget to tell which version of LilyPond you use!
+@uref{http://code.google.com/p/lilypond/issues/list}
-@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
+If you have discovered a bug which is not listed, please report the
+bug by following the directions on
-@ignore
-@c the bug database is not up to date enough.
-
-When you've found a bug, have a look at our
-@uref{http://@/lilypond@/.org/@/bugs/@/v2.8/@/,bug database} to see if
-it has already been reported. You could also try to do a few searches
-on the mailing list for the bug. Sometimes the bug will have already
-been reported and a fix or workaround is already known.
-@end ignore
+@uref{http://lilypond.org/web/devel/participating/bugs}
-Here is an example of a good bug report:
+Please construct submit @ruser{Minimal examples}, of bug reports. We do not
+have the resources to investigate reports which are not as small as possible.
-@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, lilypond 2.7.32
-
-\version "2.9.13"
-\layout { ragged-right = ##t }
-\relative c'' {
- a4 b cis d
-}
-@end verbatim
-
-@lilypond[quote]
-\layout { ragged-right = ##t }
-\relative c''{
- \override Accidental #'extra-offset = #'(1.0 . 0)
- a4 b cis d
-}
-@end lilypond
@node Error messages
@section Error messages
above the indicated position.
-@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 @file{lilypond-mode} is not installed on your
-platform, then read the
-@ifhtml
-@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}.
-@end ifhtml
-@ifnothtml
-installation instructions.
-@end ifnothtml
-
-@item VIM
-
-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/INSTALL.html,installation instructions}.
-@end ifhtml
-@ifnothtml
-installation instructions.
-@end ifnothtml
-
-
-@item JEdit
-
-The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
-This plugin includes a DVI viewer, integrated help and viewing via
-GhostScript. It can be installed by doing @key{Plugins > Plugin
-Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
-
-@end table
-
-All these editors can be made to jump into the input file to the source
-of a symbol in the graphical output. See @ref{Point and click}.
-
-
-@node Point and click
-@section Point and click
-@cindex point and click
-
-
-Point and click lets you find notes in the input by clicking on them
-in the PDF viewer. This makes it easier to find input that causes
-some error in the sheet music.
-
-When this functionality is active, LilyPond adds hyperlinks to the PDF
-file. These hyperlinks are sent to the web-browser, which opens a
-text-editor with the cursor in the right place.
-
-To make this chain work, you should configure your PDF viewer to
-follow hyperlinks using the @file{lilypond-invoke-editor} script
-supplied with LilyPond.
-
-For Xpdf on Unix, the following should be present in
-@file{xpdfrc}@footnote{On unix, this file is found either in
-@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
-
-@example
-urlCommand "lilypond-invoke-editor %s"
-@end example
-
-The program @file{lilypond-invoke-editor} is a small helper
-program. It will invoke an editor for the special @code{textedit}
-URIs, and run a web browser for others. It tests the environment
-variable @code{EDITOR} for the following patterns,
-
-@table @code
-@item emacs
- this will invoke
-@example
-emacsclient --no-wait +@var{line}:@var{column} @var{file}
-@end example
-@item vim
- this will invoke
-@example
-gvim --remote +:@var{line}:norm@var{char} @var{file}
-@end example
-
-@item nedit
-this will invoke
-@example
- nc -noask +@var{line} @var{file}'
-@end example
-@end table
-
-The environment variable @code{LYEDITOR} is used to override this. It
-contains the command line to start the editor, where @code{%(file)s},
-@code{%(column)s}, @code{%(line)s} is replaced with the file, column
-and line respectively. The setting
-
-@example
-emacsclient --no-wait +%(line)s:%(column)s %(file)s
-@end example
-
-@noindent
-for @code{LYEDITOR} is equivalent to the standard emacsclient
-invocation.
-
-
-@cindex file size, output
-
-The point and click links enlarge the output files significantly. For
-reducing the size of PDF and PS files, point and click may be switched
-off by issuing
-
-@example
-#(ly:set-option 'point-and-click #f)
-@end example
-
-@noindent
-in a @file{.ly} file. Alternately, you may pass this as an command-line
-option
-
-@example
-lilypond -dno-point-and-click file.ly
-@end example
projects / lilypond.git / blobdiff