From 9605455437b9daaab6b32c110768b338d15a0451 Mon Sep 17 00:00:00 2001 From: James Lowe Date: Sat, 31 Dec 2011 12:33:45 +0000 Subject: [PATCH] Doc: Usage --include option layout consistency Tracker 2135 Made description arguments consistent with others, so also had to swap two paras around so that '-i' came before '-I'. Also some minor blank line deletion (tidy up) to keep layout in tex file consistent. Added and hopfully improved some @cindex entries --- Documentation/usage/running.itely | 203 ++++++++++++++++-------------- 1 file changed, 108 insertions(+), 95 deletions(-) diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely index 4cc95d990a..7f49e9802d 100644 --- a/Documentation/usage/running.itely +++ b/Documentation/usage/running.itely @@ -133,38 +133,6 @@ The following options are supported: @table @code -@item -e,--evaluate=@var{expr} -Evaluate the Scheme @var{expr} before parsing any @file{.ly} files. -Multiple @option{-e} options may be given, they will be evaluated -sequentially. - -The expression will be evaluated in the @code{guile-user} module, so -if you want to use definitions in @var{expr}, use - -@example -lilypond -e '(define-public a 42)' -@end example - -@noindent -on the command-line, and include - -@example -#(use-modules (guile-user)) -@end example - -@warning{Windows users must use double quotes instead of single quotes.} - -@noindent -at the top of the @code{.ly} file. - -@item -f,--format=@var{format} -which formats should be written. Choices for @code{format} are -@code{ps}, @code{pdf}, and @code{png}. - -Example: @code{lilypond -fpng @var{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 @@ -288,12 +256,14 @@ SVG output should be compatible with any SVG editor or user agent. @item scm @cindex Scheme dump +@cindex output, Scheme dump for a dump of the raw, internal Scheme-based drawing commands. @item null do not output a printed score; has the same effect as @option{-dno-print-pages}. + @end table Example: @code{lilypond -dbackend=svg @var{filename}.ly} @@ -327,86 +297,62 @@ useful in combination with @option{-dpreview}. @end table -@item -h,--help -Show a summary of usage. - -@item -H,--header=@var{FIELD} -Dump a header field to file @file{BASENAME.@var{FIELD}}. - -@cindex file searching -@cindex search path - -@item --include, -I=@var{directory} -Add @var{directory} to the search path for input files. - -Multiple -I options may be given. The search will start in the first -defined directory, and if the file to be included is not found the -search will continue in subsequent directories. - -@item -i,--init=@var{file} -Set init file to @var{file} (default: @file{init.ly}). - -@cindex loglevel -@cindex output verbosity, setting - -@item -l,--loglevel=@var{LEVEL} -Set the verbosity of the console output to @var{LEVEL}. Possible values -are: +@cindex Scheme, expression evaluation +@cindex expression evalusation, Scheme -@table @code - -@item NONE -No output at all, not even error messages. - -@item ERROR -Only error messages, no warnings or progress messages. +@item -e,--evaluate=@var{expr} +Evaluate the Scheme @var{expr} before parsing any @file{.ly} files. +Multiple @option{-e} options may be given, they will be evaluated +sequentially. -@item WARN -Warnings and error messages, no progress. +The expression will be evaluated in the @code{guile-user} module, so +if you want to use definitions in @var{expr}, use -@item BASIC_PROGRESS -Basic progress messages (success), warnings and errors. +@example +lilypond -e '(define-public a 42)' +@end example -@item PROGRESS -All progress messages, warnings and errors. +@noindent +on the command-line, and include -@item INFO (default) -Progress messages, warnings, errors and further execution information. +@example +#(use-modules (guile-user)) +@end example -@item DEBUG -All possible messages, including verbose debug output. -@end table +@warning{Windows users must use double quotes instead of single quotes.} -@cindex folder, directing output to -@cindex output filename, setting +@noindent +at the top of the @code{.ly} file. -@item -o,--output=@var{FILE} or @var{FOLDER} -Set the default output file to @var{FILE} or, if a folder with that name -exists, direct the output to @var{FOLDER}, taking the file name from the -input file. The appropriate suffix will be added (e.g. @code{.pdf} for -pdf) in both cases. +@cindex output, format +@cindex format, output +@item -f,--format=@var{format} +which formats should be written. Choices for @code{format} are +@code{ps}, @code{pdf}, and @code{png}. -@cindex PostScript output +Example: @code{lilypond -fpng @var{filename}.ly} -@item --ps -Generate PostScript. +@item -h,--help +Show a summary of usage. -@cindex Portable Network Graphics (PNG) output +@item -H,--header=@var{FIELD} +Dump a header field to file @file{BASENAME.@var{FIELD}}. -@item --png -Generate pictures of each page, in PNG format. This implies -@option{--ps}. The resolution in DPI of the image may be set with -@example --dresolution=110 -@end example +@item -i,--init=@var{file} +Set init file to @var{file} (default: @file{init.ly}). -@cindex Portable Document Format (PDF) output +@cindex file searching +@cindex search path -@item --pdf -Generate PDF. This implies @option{--ps}. +@item -I, --include=@var{directory} +Add @var{directory} to the search path for input files. +Multiple -I options may be given. The search will start in the first +defined directory, and if the file to be included is not found the +search will continue in subsequent directories. +@cindex chroot jail, running inside @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir} Run @command{lilypond} in a chroot jail. @@ -430,6 +376,7 @@ LilyPond is able to find whatever it needs to compile the source @emph{inside the jail}. A typical setup comprises the following items: @table @asis + @item Setting up a separate filesystem A separate filesystem should be created for LilyPond, so that it can be mounted with safe options such as @code{noexec}, @code{nodev}, and @@ -465,8 +412,73 @@ possibly using @command{sudo}. It is a good idea to limit the number of seconds of CPU time LilyPond can use (e.g., using @command{ulimit -t}), and, if your operating system supports it, the amount of memory that can be allocated. + @end table +@cindex loglevel +@cindex output, verbosity + +@item -l,--loglevel=@var{LEVEL} +Set the verbosity of the console output to @var{LEVEL}. Possible values +are: + +@table @code + +@item NONE +No output at all, not even error messages. + +@item ERROR +Only error messages, no warnings or progress messages. + +@item WARN +Warnings and error messages, no progress. + +@item BASIC_PROGRESS +Basic progress messages (success), warnings and errors. + +@item PROGRESS +All progress messages, warnings and errors. + +@item INFO (default) +Progress messages, warnings, errors and further execution information. + +@item DEBUG +All possible messages, including verbose debug output. + +@end table + +@cindex directory, redirect output +@cindex output, setting filename +@cindex output, directory + +@item -o,--output=@var{FILE} or @var{FOLDER} +Set the default output file to @var{FILE} or, if a folder with that name +exists, direct the output to @var{FOLDER}, taking the file name from the +input file. The appropriate suffix will be added (e.g. @code{.pdf} for +pdf) in both cases. + +@cindex PS (Postscript), output +@cindex Postscript (PS), output +@cindex output, PS (Postscript) + +@item --ps +Generate PostScript. + +@cindex PNG (Portable Network Graphics), output +@cindex output, PNG (Portable Network Graphics) + +@item --png +Generate pictures of each page, in PNG format. This implies +@option{--ps}. The resolution in DPI of the image may be set with +@example +-dresolution=110 +@end example + +@cindex PDF (Portable Document Format), output +@cindex output, PDF (Portable Document Format) + +@item --pdf +Generate PDF. This implies @option{--ps}. @item -v,--version Show version information. @@ -478,6 +490,7 @@ information. @item -w,--warranty Show the warranty with which GNU LilyPond comes. (It comes with @strong{NO WARRANTY}!) + @end table -- 2.39.2