X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frunning.itely;h=981e71867a5d2fcd8e5c7a418361215b82bf3a57;hb=c74523f061cba5fb50d307ff04e3507c8b36f5c8;hp=5670f9e28b15e641a053f98fbbb5188ef6077ba9;hpb=0b7c17f1e09fe86a282b863809fbd942f82893f0;p=lilypond.git diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely index 5670f9e28b..981e71867a 100644 --- a/Documentation/user/running.itely +++ b/Documentation/user/running.itely @@ -99,7 +99,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 +213,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 +252,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 +264,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} @@ -330,11 +342,11 @@ Show the warranty with which GNU LilyPond comes. (It comes with @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. @@ -439,6 +451,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