X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frunning.itely;h=0b992069c119cda3091e249d79fd87630f9c39d5;hb=651180d1740e69825d07eb83e1454b3cf534b734;hp=e6ed8fa9044a8f6d328a2b0055b3a73a3126b27f;hpb=38e0fd809d01de319d40224b5d2279888304b2d3;p=lilypond.git diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely index e6ed8fa904..0b992069c1 100644 --- a/Documentation/user/running.itely +++ b/Documentation/user/running.itely @@ -1,5 +1,5 @@ @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 @@ -13,31 +13,43 @@ This chapter details the technicalities of running LilyPond. -Some of these commands are run from the command-line. By -@q{command-line}, we mean the command -line in the operating system. Windows users -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 -this part of an operating system is outside the scope of this -manual; please consult other documentation on this topic if -you are unfamiliar with the command-line. - @menu -* Invoking lilypond:: -* Notes for the MacOS X app:: +* Normal usage:: +* Command-line usage:: +* Error messages:: * Updating files with convert-ly:: * Reporting bugs:: -* Error messages:: -* Editor support:: -* Point and click:: @end menu -@node Invoking lilypond -@section Invoking lilypond + +@node Normal usage +@section Normal usage + +Most users run LilyPond through a GUI; see @ruser{First steps} if +you have not read this already. + + +@node Command-line usage +@section Command-line usage + +This section contains extra information about using LilyPond on the +command-line. This may be desirable to pass extra options to the +program. In addition, there are certain extra @q{helper} programs (such +as @code{midi2ly}) which are only available on the command-line. + +By @q{command-line}, we mean the command line in the operating system. +Windows users 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{MacOS X +on the command-line}. + +Describing how to use this part of an operating system is outside the +scope of this manual; please consult other documentation on this topic +if you are unfamiliar with the command-line. + + +@subsection Invoking lilypond + @cindex Invoking LilyPond @cindex command line options @cindex options, command line @@ -64,6 +76,21 @@ they will each be processed independently. @footnote{The status of 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 @@ -99,7 +126,81 @@ which formats should be written. Choices for @code{format} are Example: @code{lilypond -fpng filename.ly} -@item -b,--backend=@var{format} + + +@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 + +@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 @@ -139,38 +240,20 @@ This mode is used by default by lilypond-book. @cindex Scheme dump @end table -Example: @code{lilypond -bsvg filename.ly} +Example: @code{lilypond -dbackend=svg filename.ly} @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 --dno-point-and-click -@end example - -@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. @@ -196,7 +279,7 @@ Generate PostScript. @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 @@ -208,50 +291,6 @@ 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} @@ -351,65 +390,85 @@ uses more CPU time. The default value is @code{70}. @end table -@node Notes for the MacOS X app -@section Notes for the MacOS X app +@node Error messages +@section Error messages -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. +@cindex error messages +Different error messages can appear while compiling a file: -@example -@var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond -@end example +@table @emph -@noindent -The same is true of the other scripts in that directory, including -lilypond-book, convert-ly, abc2ly, etc. +@item Warning +@cindex 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. -Alternatively, you may create scripts which add the path -automatically. Create a directory to store these scripts, +@item Error +Something is definitely wrong. The current processing step (parsing, +interpreting, or formatting) will be finished, but the next step will +be skipped. -@example -mkdir -p ~/bin -cd ~/bin -@end example +@item Fatal error +@cindex error +@cindex fatal error +Something is definitely wrong, and LilyPond cannot continue. This +happens rarely. The most usual cause is misinstalled fonts. -Create a file called @code{lilypond} which contains +@item Scheme error +@cindex trace, Scheme +@cindex call trace +@cindex 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 of the offending +function call is printed. -@example -exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@" -@end example +@item Programming error +@cindex 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. -Create similar files @code{lilypond-book}, @code{convert-ly}, and -any other helper programs you use (@code{abc2ly}, @code{midi2ly}, -etc). Simply replace the @code{bin/lilypond} with -@code{bin/convert-ly} (or other program name) in the above file. +@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 bug-report. +@end table -Make the file executable, +@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 -chmod u+x lilypond +@var{filename}:@var{lineno}:@var{columnno}: @var{message} +@var{offending input line} @end example -Now, add this directory to your path. Modify (or create) -a file called @code{.profile} in your home directory such that it contains +A line-break is inserted in the offending line to indicate the column +where the error was found. For example, @example -export PATH=$PATH:~/bin +test.ly:2:19: error: not a duration: 5: + @{ c'4 e'5 + g' @} @end example -@noindent -This file should end with a blank line. - -Note that @var{path/to} will generally be @code{/Applications/}. +These locations are LilyPond's best guess about where the warning or +error occurred, but (by their very nature) warnings and errors occur +when something unexpected happens. If you can't see an error in the +indicated line of your input file, try checking one or two lines +above the indicated position. @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 @@ -419,16 +478,21 @@ syntax changes between LilyPond versions. It uses @code{\version} statements in the input files to detect the old version number. In most cases, to upgrade your input file it is -sufficient to run@footnote{MacOS X users may execute this command -under the menu entry @samp{Compile > Update syntax}.} +sufficient to run @example convert-ly -e myfile.ly @end example +@noindent +MacOS X users may execute this command under the menu entry +@samp{Compile > Update syntax}. + If there are no changes to myfile.ly and file called myfile.ly.NEW is created, then myfile.ly is already updated. +@subsection Command line options + @command{convert-ly} always converts up to the last syntax change handled by it. This means that the @code{\version} number left in the file is usually lower than the version of @command{convert-ly} itself. @@ -439,6 +503,12 @@ To upgrade LilyPond fragments in texinfo files, use 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 @@ -480,39 +550,26 @@ Print usage help. @end table -@refbugs +@menu +* Problems with convert-ly:: +@end menu + + +@node Problems with convert-ly +@subsection Problems with @code{convert-ly} Not all language changes are handled. Only one output option can be specified. Automatically updating scheme and lilypond scheme interfaces is quite unlikely; be prepared to tweak scheme code manually. - -@c We might want to make this a completely new section, along with more -@c info about how to upgrade old input files. -gp - -@ignore -Copy and paste from CVS, last updated -Aug 18, 2005 - -http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/ -convert-ly.txt?rev=HEAD&content-type=text/plain - -NEW: not exactly copied; this list has been modified. Since we're -changing the bug system, it doesn't make sense to copy from -the bug CVS any more. I'll figure out something else. -gp -@end ignore @verbatim +There are a few things that the convert-ly cannot handle. Here's a list +of limitations that the community has complained about. -There are a few things that the convert-ly cannot handle. Here's a list of -limitations -that the community has complained about. - -This bug report structure has been chosen because convert-ly has a structure -that doesn't -allow to smoothly implement all needed changes. Thus this is just a wishlist, -placed -here for reference. +This bug report structure has been chosen because convert-ly has a +structure that doesn't allow to smoothly implement all needed changes. +Thus this is just a wishlist, placed here for reference. 1.6->2.0: Doesn't always convert figured bass correctly, specifically things like {< @@ -577,217 +634,8 @@ bug by following the directions on @uref{http://lilypond.org/web/devel/participating/bugs} -Please construct submit @ref{Minimal examples} of bug reports. We do not +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. -@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 of the offending -function call is printed. - -@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 bug-report. - - -@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 the offending line to indicate the column -where the error was found. For example, - -@example -test.ly:2:19: error: not a duration: 5: - @{ c'4 e'5 - g' @} -@end example - -These locations are LilyPond's best guess about where the warning or -error occurred, but (by their very nature) warnings and errors occur -when something unexpected happens. If you can't see an error in the -indicated line of your input file, try checking one or two lines -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 LilyPondTool - -Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit} text -editor, LilyPondTool is the most feature-rich text-based tool for editing -LilyPond scores. Its features include a Document Wizard with lyrics -support to set up documents easier, and embedded PDF viewer with advanced -point-and-click support. For screenshots, demos and installation -instructions, visit @uref{http://lilypondtool@/.organum@/.hu} - -@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