Documentation/user/invoking.itexi

   1 @node Invoking LilyPond
   2 @chapter Invoking LilyPond
   3
   4 @menu
   5 * Reporting bugs::
   6 * Website::
   7 * Titling LilyPond scores::
   8 @end menu
   9
  10 @cindex Invoking LilyPond
  11 @cindex command line options
  12 @cindex options, command line
  13 @cindex switches
  14
  15 Usage:
  16
  17 @example
  18         lilypond [@var{option}]@dots{} @var{file}@dots{}
  19 @end example
  20
  21
  22
  23 When invoked with a filename that has no extension, LilyPond will try
  24 to add @file{.ly} as an extension first.  To have LilyPond read from
  25 stdin, use a dash @code{-} for @var{file}.
  26
  27 When LilyPond processes @file{filename.ly} it will produce
  28 @file{filename.tex} as output (or @file{filename.ps} for PostScript
  29 output).  If @file{filename.ly} contains more than one @code{\score}
  30 block, then LilyPond will output the rest in numbered files, starting
  31 with @file{filename-1.tex}.  Several files can be specified; they will
  32 each be processed independently.  @footnote{The status of GUILE is not
  33 reset across invocations, so be careful not to change any default
  34 settings from within Scheme .}
  35
  36
  37 @section Command line options
  38
  39 The following options are supported:
  40
  41 @table @code
  42
  43 @item -e,--evaluate=@var{code}
  44   Evaluates the Scheme @var{code} before parsing @file{.ly}
  45 files. Multiple @code{-e} options may be given. They will be evaluated
  46 sequentially. The function @code{set-lily-option} may be invoked to
  47 set various debugging options.
  48
  49
  50
  51 @item -f,--format=@var{format} Output format for sheet music. Choices
  52 are @code{tex} (for @TeX{} output, to be processed with plain @TeX{},
  53 or through ly2dvi), @code{pdftex} for PDF@TeX{} input, @code{ps} (for
  54 PostScript), @code{scm} (for a Scheme dump), and @code{as} (for
  55 ASCII-art).
  56
  57 Unless you have special requirements, you should use @TeX{}
  58 output. All other options are experimental.
  59 @item -h,--help
  60 Show a summary of usage.
  61 @item --include, -I=@var{directory}
  62 Add @var{directory} to the search path for input files.
  63 @cindex file searching
  64 @cindex search path
  65 @item -i,--init=@var{file}
  66 Set init file to @var{file} (default: @file{init.ly}).
  67 @item -m,--no-paper
  68 @cindex MIDI
  69 Disable @TeX{} output. If you have a @code{\midi} definition midi output
  70 will be generated.
  71 @item -M,--dependencies
  72 Output rules to be included in Makefile.
  73 @item -o,--output=@var{FILE}
  74 Set the default output file to @var{FILE}.
  75
  76 @ignore
  77 @item -s,--safe
  78 Disallow untrusted @code{\include} directives, in-line
  79 Scheme evaluation, backslashes in @TeX{}, code.
  80
  81 @strong{WARNING}: the @code{--safe} option has not been reviewed for a
  82 long time. Do not rely on it for automatic invocation (e.g. over the
  83 web). Volunteers are welcome to do a new audit.
  84 @end ignore
  85
  86 @item -v,--version
  87 Show version information
  88 @item -V,--verbose
  89 Be verbose: show full paths of all  files read, and give timing
  90 information.
  91
  92 @item -w,--warranty
  93 Show the warranty with which GNU LilyPond comes. (It comes with
  94 @strong{NO WARRANTY}!)
  95 @end table
  96
  97 @section Environment variables
  98
  99
 100 For processing both the @TeX{} and the PostScript output, you must
 101 have appropriate environment variables set.  Scripts to do this are
 102 included in @file{buildscripts/out/lilypond-profile} (for sh shells)
 103 and @file{buildscripts/out/lilypond-login} (for C-shells), and should
 104 normally be sourced as part of your login process. If these scripts
 105 are not run from the system wide login process, then you must run it
 106 yourself.
 107
 108 @cindex installing LilyPond
 109
 110 If you use sh, bash, or a similar shell, then add the following to
 111 your @file{.profile}
 112 @example
 113         . lilypond-profile
 114 @end example
 115
 116 If you use csh, tcsh or a similar shell, then add the following to
 117 your @file{~/.login}
 118 @example
 119         source lilypond-login
 120 @end example
 121
 122 These scripts set the following variables
 123 @table @code
 124 @item TEXMF
 125  To make sure that @TeX{} and lilypond find data files (among
 126 others @file{.tex}, @file{.mf} and @file{.tfm}),
 127 you have to set @code{TEXMF} to point to the lilypond data
 128 file tree. A typical setting would be
 129 @example
 130 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
 131 @end example
 132
 133
 134 @item GS_LIB
 135 For processing PostScript output (obtained with
 136 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
 137 point to the directory containing LilyPond PS files.
 138
 139 @item GS_FONTPATH
 140 For processing PostScript output (obtained with
 141 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
 142 point to the directory containing LilyPond PFA files.
 143
 144 When you print direct PS output, remember to send the PFA files to the
 145 printer as well.
 146 @end table
 147
 148
 149 @cindex ghostscript
 150 @cindex PostScript
 151 @cindex GS_FONTPATH
 152 @cindex GS_LIB
 153 @cindex TEXMF
 154 @cindex printing postscript
 155
 156 The LilyPond binary itself recognizes the following environment variables
 157 @table @code
 158 @item LILYPONDPREFIX
 159 This specifies a directory where locale messages and
 160 data files will be looked up by default. The directory should contain
 161 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
 162
 163 @item LANG
 164 This selects the language for the warning messages of LilyPond.
 165 @end table
 166
 167 @cindex LANG
 168 @cindex LILYPONDPREFIX
 169
 170
 171
 172 @cindex bugs
 173 @cindex reporting bugs
 174
 175 @node Reporting bugs
 176 @section Reporting bugs
 177
 178 Since there is no finder's fee which doubles every year, there is no
 179 need to wait for the prize money to grow. So send a bug report today!
 180
 181 LilyPond development moves quickly, so if you have a problem, it is
 182 wise to check if it has been fixed in a newer release.  If you think
 183 you found a bug, please send in a bugreport.  When you send us a
 184 bugreport, we have to diagnose the problem and if possible, duplicate
 185 it.  To make this possible, it is important that you include the
 186 following information in your report:
 187
 188 @itemize @bullet
 189
 190 @item A sample input which causes the error.  Please have mercy on the
 191 developers, send a @emph{small} sample file.
 192
 193 @item The version number of lilypond.
 194
 195 @item A description of the platform you use (i.e., operating system,
 196 system libraries, whether you downloaded a binary release)
 197
 198 @item If necessary, send a description of the bug itself.  If you
 199 include output a ly2dvi run, please use @code{--verbose} option of
 200 ly2dvi.
 201
 202 @end itemize
 203
 204 You can send the report to @email{bug-lilypond@@gnu.org}. This is a
 205 mailinglist, but you don't have to be subscribed to it to post.
 206
 207 @node Website
 208 @section Website
 209
 210 If you are reading this manual in print, it is possible that the
 211 website contains updates to the manual. You can find the lilypond
 212 website at @uref{http://www.lilypond.org/}.
 213
 214
 215 @node Titling LilyPond scores
 216 @section Titling LilyPond scores
 217
 218 Nicely titled output is created through a separate program:
 219 @file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
 220 nicely titled piece of sheet music, in DVI format or PostScript.
 221
 222 @subsection Invoking ly2dvi
 223
 224 @c ly2dvi needs at least one FILE, can't act as filter yet
 225 @example
 226         ly2dvi [@var{option}]@dots{} @var{file}@dots{}
 227 @end example
 228
 229 Ly2dvi supports the following options:
 230
 231 @table @code
 232 @item -k,--keep
 233     Keep the temporary directory including LilyPond and ly2dvi output
 234 files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
 235 @item -d,--dependencies
 236     Write makefile dependencies for every input file.
 237 @item -h,--help
 238     Print usage help.
 239 @item -I,--include=@var{dir}
 240     Add @var{dir} to LilyPond's include path.
 241 @item -m,--no-paper
 242     Produce MIDI output only.
 243 @item --no-lily
 244     Do not run LilyPond; useful for debugging ly2dvi.
 245 @item -o,--output=@var{file}
 246     Generate output to @var{file}.  The extension of @var{file} is ignored.
 247 @item -P,--postscript
 248     Also generate PostScript output, using dvips.
 249 @item --preview
 250     Also generate a picture of the first system of the score.
 251 @item -s,--set=@var{key}=@var{val}
 252     Add @var{key}= @var{val} to the settings, overriding those specified
 253 in the files. Possible keys: @code{language}, @code{latexheaders},
 254 @code{latexpackages}, @code{latexoptions}, @code{papersize},
 255 @code{pagenumber}, @code{linewidth}, @code{orientation},
 256 @code{textheight}.
 257 @item -v,--version
 258 Show version information
 259 @item -V,--verbose
 260 Be verbose
 261 @item -w,--warranty
 262 Show the warranty with which GNU LilyPond comes. (It comes with
 263 @strong{NO WARRANTY}!)
 264 @end table
 265
 266 @subsection Titling layout
 267
 268 Ly2dvi extracts the following header fields from the LY files to
 269 generate titling:
 270
 271 @table @code
 272 @item title
 273     The title of the music. Centered on top of the first page.
 274 @item subtitle
 275     Subtitle, centered below the title.
 276 @item poet
 277     Name of the poet, left flushed below the subtitle.
 278 @item composer
 279     Name of the composer, right flushed below the subtitle.
 280 @item meter
 281     Meter string, left flushed below the poet.
 282 @item opus
 283     Name of the opus, right flushed below the composer.
 284 @item arranger
 285     Name of the arranger, right flushed below the opus.
 286 @item instrument
 287     Name of the instrument, centered below the arranger
 288 @item piece
 289     Name of the piece, left flushed below the instrument
 290 @item head
 291     A text to print in the header of all pages. It is not called
 292 @code{header}, because @code{\header} is a reserved word in LilyPond.
 293 @item copyright
 294     A text to print in the footer of the first page. Default is to
 295     print the standard footer also on the first page.
 296 @item footer
 297     A text to print in the footer of all but the last page.
 298 @item tagline
 299     Line to print at the bottom of last page. The default text is ``Lily
 300 was here, @var{version-number}''.
 301 @end table
 302
 303
 304 @cindex header
 305 @cindex footer
 306 @cindex page layout
 307 @cindex titles
 308
 309
 310
 311 @subsection Additional parameters
 312
 313 Ly2dvi responds to several parameters specified in a @code{\paper}
 314 section of the LilyPond file. They can be overridden by supplying a
 315 @code{--set} command line option.
 316
 317 @table @code
 318 @item language
 319     Specify La@TeX{} language: the @code{babel} package will be
 320 included.  Default: unset.
 321
 322         Read from the @code{\header} block.
 323
 324 @item latexheaders
 325     Specify additional La@TeX{} headers file.
 326
 327         Normally read from the @code{\header} block. Default value: empty
 328
 329 @item latexpackages
 330     Specify additional La@TeX{} packages file. This works cumulative,
 331 so you can add multiple packages using multiple @code{-s=latexpackages} options.
 332        Normally read from the @code{\header} block. Default value:
 333 @code{geometry}.
 334
 335 @item latexoptions
 336     Specify additional options for the La@TeX{} @code{\documentclass}. You can put any valid value here. This was designed to allow ly2dvi to produce output for double-sided paper, with balanced margins and pagenumbers on alternating sides. To achieve this specify @code{twoside}
 337
 338 @item orientation
 339     Set orientation. Choices are @code{portrait} or @code{landscape}. Is
 340 read from the @code{\paper} block, if set.
 341
 342 @item textheight
 343     The vertical extension of the music on the page. It is normally
 344     calculated automatically, based on the paper size.
 345
 346 @item linewidth
 347         The music line width. It is normally read from the @code{\paper}
 348 block.
 349
 350 @item papersize
 351    The paper size (as a name, e.g. @code{a4}). It is normally read from
 352 the @code{\paper} block.
 353
 354 @item pagenumber
 355    If set to @code{no}, no page numbers will be printed.
 356
 357
 358
 359   @item fontenc
 360      The font encoding, should be set identical to the @code{font-encoding}
 361      property in the score.
 362 @end table
 363
 364 @subsection Environment variables
 365
 366 @table @code
 367 @item LANG
 368 selects the language for the warning messages of Ly2dvi and LilyPond.
 369 @end table
 370
 371