X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frunning.itely;h=0bbd4d14bb75befa94fc4b698639a762658b2e33;hb=3f62fde29b68361cf3ac3951428eb760799b16f5;hp=91510f12d0f86d81dfcf0447531fb9c7b1bc9319;hpb=57653e68f63cc5950968b0eed11cbb15c0f7c250;p=lilypond.git diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely index 91510f12d0..0bbd4d14bb 100644 --- a/Documentation/user/running.itely +++ b/Documentation/user/running.itely @@ -7,7 +7,7 @@ version that you are working on. See TRANSLATION for details. @end ignore -@c \version "2.11.38" +@c \version "2.11.61" @node Running LilyPond @@ -16,18 +16,18 @@ This chapter details the technicalities of running LilyPond. @menu -* Normal usage:: -* Command-line usage:: -* Error messages:: -* Updating files with convert-ly:: -* Reporting bugs:: +* Normal usage:: +* Command-line usage:: +* Error messages:: +* Updating files with convert-ly:: +* Reporting bugs:: @end menu @node Normal usage @section Normal usage -Most users run LilyPond through a GUI; see @ruser{First steps} if +Most users run LilyPond through a GUI; see @rlearning{First steps} if you have not read this already. @@ -42,18 +42,24 @@ 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}; MacOS@tie{}X users might be more familiar with the terms -@q{terminal} or @q{console}. They should also consult @ref{MacOS X -on the command-line}. +@q{terminal} or @q{console}. They should also consult @ref{Setup +for MacOS X}. 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:: +* Command line options for lilypond:: +* Environment variables:: +@end menu -@subsection Invoking lilypond +@node Invoking lilypond +@subsection Invoking @command{lilypond} -@cindex Invoking LilyPond -@cindex command line options +@cindex Invoking @command{lilypond} +@cindex command line options for @command{lilypond} @cindex options, command line @cindex switches @@ -69,32 +75,32 @@ 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 @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 the rest of the scores will be output in numbered files, -starting with @file{filename-1.tex}. Several files can be specified; +When @file{filename.ly} is processed it will produce @file{filename.ps} +and @file{filename.pdf} as output. Several files can be specified; 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 +If @file{filename.ly} contains more than one @code{\score} +block, then the rest of the scores will be output in numbered files, +starting with @file{filename-1.pdf}. 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{} @} +\book @{ @dots{} @} #(define output-suffix "cello") -\book @{ @dots{} @} +\book @{ @dots{} @} @end example @noindent -will output @var{base}@file{-violin.ps} and -@var{base}@file{-cello-1.ps}. +will output @var{base}@file{-violin.pdf} and +@var{base}@file{-cello-1.pdf}. - -@subsection Command line options +@node Command line options for lilypond +@subsection Command line options for @command{lilypond} The following options are supported: @@ -126,7 +132,7 @@ at the top of the @code{.ly} file. 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} +Example: @code{lilypond -fpng @var{filename}.ly} @@ -155,14 +161,14 @@ Running @code{lilypond -dhelp} will print all of the @code{-d} options available. @item paper-size -This option sets the default 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{\"} ). - +@c Match " in previous line to help context-sensitive editors @item safe Do not trust the @code{.ly} input. @@ -192,7 +198,7 @@ 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 +@code{-dsafe} 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 @@ -226,7 +232,7 @@ currently missing due to heavy restructuring of the source code. @file{EPS} file, without fonts, and as one collated @file{EPS} file with all pages (systems) including fonts. -This mode is used by default by lilypond-book. +This mode is used by default by @command{lilypond-book}. @item svg for SVG (Scalable Vector Graphics). This dumps every page as a separate @@ -235,14 +241,14 @@ This mode is used by default by lilypond-book. You need a SVG viewer which supports embedded fonts, or a SVG viewer which is able to replace the embedded fonts with OTF fonts. Under UNIX, you may use @uref{http://www.inkscape.org,Inkscape} - (version 0.42 or later), after copying the OTF fonts in directory - @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}. + (version 0.42 or later), after copying the OTF fonts from the LilyPond directory + (typically @file{/usr/share/lilypond/VERSION/fonts/otf/}) to @file{~/.fonts/}. @item scm for a dump of the raw, internal Scheme-based drawing commands. @cindex Scheme dump @end table -Example: @code{lilypond -dbackend=svg filename.ly} +Example: @code{lilypond -dbackend=svg @var{filename}.ly} @cindex output format, setting @@ -260,8 +266,8 @@ useful in combination with @code{-dpreview}. @item -h,--help Show a summary of usage. -@item -H,--header=FIELD -Dump a header field to file BASENAME.FIELD +@item -H,--header=@var{FIELD} +Dump a header field to file @file{BASENAME.@var{FIELD}}. @item --include, -I=@var{directory} Add @var{directory} to the search path for input files. @@ -273,7 +279,7 @@ Set init file to @var{file} (default: @file{init.ly}). @item -o,--output=@var{FILE} Set the default output file to @var{FILE}. The appropriate -suffix will be added (ie @code{.pdf} for pdf, @code{.tex} +suffix will be added (i.e. @code{.pdf} for pdf, @code{.tex} for tex, etc). @item --ps @@ -366,7 +372,7 @@ Show the warranty with which GNU LilyPond comes. (It comes with @strong{NO WARRANTY}!) @end table - +@node Environment variables @subsection Environment variables @@ -454,9 +460,9 @@ 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' @} +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 @@ -467,7 +473,7 @@ above the indicated position. @node Updating files with convert-ly -@section Updating with @command{convert-ly} +@section Updating files with @command{convert-ly} @cindex Updating a LilyPond file @cindex convert-ly @@ -493,7 +499,13 @@ MacOS@tie{}X users may execute this command under the menu entry 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 +@menu +* Command line options for convert-ly:: +* Problems with convert-ly:: +@end menu + +@node Command line options for convert-ly +@subsection Command line options for @command{convert-ly} @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 @@ -552,11 +564,6 @@ Print usage help. @end table -@menu -* Problems with convert-ly:: -@end menu - - @node Problems with convert-ly @subsection Problems with @code{convert-ly} @@ -636,7 +643,7 @@ bug by following the directions on @uref{http://lilypond.org/web/devel/participating/bugs} -Please construct submit @ruser{Minimal examples}, of bug reports. We do not +Please construct and submit minimal examples of bugs in reports. We do not have the resources to investigate reports which are not as small as possible.