X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finvoking.itely;h=9cfb8b18d972a8bb9af09a9d6ac8b8e96aa0b51f;hb=2831bf0efa83d07954e8c1f130402d95f161941b;hp=39cb70009f0dcc299b7f987f7df52be7b5a6b0f4;hpb=79002eea1f8f660223ea2b4351dc6069cdd8077c;p=lilypond.git diff --git a/Documentation/user/invoking.itely b/Documentation/user/invoking.itely index 39cb70009f..9cfb8b18d9 100644 --- a/Documentation/user/invoking.itely +++ b/Documentation/user/invoking.itely @@ -1,4 +1,4 @@ -@c -*- coding: latin-1; mode: texinfo; -*- +@c -*- coding: utf-8; mode: texinfo; -*- @node Running LilyPond @chapter Running LilyPond @@ -6,11 +6,12 @@ This chapter details the technicalities of running LilyPond. @menu -* Invoking lilypond:: -* Error messages:: -* Updating files with convert-ly:: -* Reporting bugs:: -* Editor support:: +* Invoking lilypond:: +* Notes for the MacOS X app:: +* Error messages:: +* Updating files with convert-ly:: +* Reporting bugs:: +* Editor support:: @end menu @node Invoking lilypond @@ -51,9 +52,24 @@ The following options are supported: @item -e,--evaluate=@var{expr} Evaluate the Scheme @var{expr} before parsing any @file{.ly} files. Multiple @code{-e} options may be given, they will be evaluated -sequentially. The function @code{ly:set-option} allows access to -some internal variables. Use @code{-e '(ly:option-usage)'} for more -information. +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 + +@noindent +at the top of the @code{.ly} file. @item -f,--format=@var{format} which formats should be written. Choices are @code{svg}, @code{ps}, @@ -85,8 +101,14 @@ all pages (systems) including fonts. This mode is used by default by lilypond-book. @item svg - for SVG (Scalable Vector Graphics) + for SVG (Scalable Vector Graphics). This dumps every page as a separate +@file{SVG} file, with embedded fonts. @cindex SVG (Scalable Vector Graphics) + 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/}. @item scm for a dump of the raw, internal Scheme-based drawing commands. @cindex Scheme dump @@ -95,23 +117,30 @@ This mode is used by default by lilypond-book. @cindex output format, setting @item -d,--define-default=@var{var}=@var{val} -This defines an internal variable @var{var} as the Scheme value -@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}, eg. +@example +-dno-point-and-click +@end example -Supported values include: -@table @code -@item resolution -set PNG resolution -@item preview-include-book-title -include book-titles in preview -@end table +@noindent +is the same as +@example +-dpoint-and-click='#f' +@end example -These settings are returned when calling -@code{(ly:get-option 'command-line-settings)} from Scheme. +@cindex point and click + +Setting the @code{help} option will print a summary of the options +available, and exit. @item -h,--help Show a summary of usage. +@item -H,--header=FIELD +Dump a header field to file BASENAME.FIELD + @item --include, -I=@var{directory} Add @var{directory} to the search path for input files. @cindex file searching @@ -130,10 +159,14 @@ Generate PostScript. @item --dvi Generate DVI files. In this case, the @TeX{} backend should be -specified, i.e., @code{-f tex}. +specified, i.e., @code{-b tex}. @item --png -Generate pictures of each page, in PNG format. This implies @code{--ps}. +Generate pictures of each page, in PNG format. This implies +@code{--ps}. The resolution in DPI of the image may be set with +@example +-dresolution=110 +@end example @item --pdf Generate PDF. This implies @code{--ps}. @@ -189,7 +222,7 @@ being compiled. For a softer but secure alternative you can use the @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir} -Run LilyPond in a jail. +Run LilyPond in a chroot jail. The @code{--jail} option provides a more flexible alternative to @code{--safe} when LilyPond formatting is available through a web @@ -262,57 +295,6 @@ Show the warranty with which GNU LilyPond comes. (It comes with @section Environment variables -@ignore -For processing both the @TeX{} and the PostScript output, the -appropriate environment variables must be set. The following scripts -do this: - -@itemize @bullet -@item @file{buildscripts/@/out/@/lilypond@/-profile} -(for SH shells) -@item @file{buildscripts/@/out/@/lilypond@/-login} (for C-shells) -@end itemize - -They should normally be sourced as part of the login process. If these -scripts are not run from the system wide login process, then you must -run them yourself. - -@cindex installing LilyPond - -If you use sh, bash, or a similar shell, then add the following to -your @file{.profile}: -@example -. @var{/the/path/to/}lilypond-profile -@end example - -If you use csh, tcsh or a similar shell, then add the following to -your @file{~/.login}: -@example -source @var{/the/path/to/}lilypond-login -@end example - -Of course, in both cases, you should substitute the proper location of -either script. - -These scripts set the following variables: -@table @code -@item TEXMF -To make sure that @TeX{} and lilypond find data files (among -others @file{.tex}, @file{.mf}, and @file{.tfm}), -you have to set @code{TEXMF} to point to the lilypond data -file tree. A typical setting would be -@example -@{/usr/share/lilypond/2.4.0,@{!!/usr/share/texmf@}@} -@end example - -@end table - -@cindex PostScript -@cindex TEXMF -@cindex printing postscript - -@end ignore - @cindex LANG @cindex LILYPONDPREFIX @@ -326,9 +308,40 @@ subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc. @item LANG This selects the language for the warning messages. + +@item LILYPOND_GC_YIELD +With this variable the memory footprint and performance can be +adjusted. It is a percentage tunes memory management behavior. With +higher values, the program uses more memory, with smaller values, it +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 + +The scripts (such as lilypond-book, convert-ly, abc2ly, etc.) are also +included inside MacOS X .app. They can be run from the command line by +invoking them directly, e.g. + +@example +@var{path/to}/LilyPond.app/Contents/Resources/bin/convert-ly +@end example + +Alternatively, you may add this directory to your path. Modify (or create) +a file called @code{.profile} in your home directory such that it contains + +@example +export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin +@end example + +@noindent +This file should end with a blank line. + +Note that @var{path/to} will generally be @code{/Applications/}. + + @node Error messages @section Error messages @@ -408,15 +421,19 @@ above the indicated position. @node Updating files with convert-ly @section Updating with @command{convert-ly} +@cindex Updating a LilyPond file +@cindex @code{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 often is no longer compatible with older input files. To remedy this, the program @command{convert-ly} can be used to deal with most of the 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 +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}.} @example convert-ly -e myfile.ly @@ -425,6 +442,10 @@ convert-ly -e myfile.ly If there are no changes to myfile.ly and file called myfile.ly.NEW is created, then myfile.ly is already updated. +@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. + To upgrade LilyPond fragments in texinfo files, use @example @@ -456,9 +477,6 @@ Do an inline edit of the input file. Overrides @code{--output}. Set the version to convert from. If this is not set, @command{convert-ly} will guess this, on the basis of @code{\version} strings in the file. -@item -o,--output=@var{file} -Set the output file to write. - @item -n,--no-version Normally, @command{convert-ly} adds a @code{\version} indicator to the output. Specifying this option suppresses this. @@ -474,9 +492,6 @@ available version. Print usage help. @end table -@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. @refbugs @@ -489,18 +504,18 @@ specified. @ignore Copy and paste from CVS, last updated -Feb 14, 2005 +Aug 18, 2005 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain @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 {< >}. Mats' comment on working around this: @@ -508,16 +523,38 @@ Thus this is just a wishlist, placed here for reference. on it, I first replaced all occurencies of '{<' to some dummy like '{#' and similarly I replaced '>}' with '&}'. After the conversion, I could then change back from '{ #' to '{ <' and from '& }' to '> }'. - Doesn't convert all text markup correctly. Only very simple cases are fixed. + Doesn't convert all text markup correctly. In the old markup syntax, + it was possible to group a number of markup commands together within parentheses, e.g. + -#'((bold italic) "string") + This will incorrectly be converted into + -\markup{{\bold italic} "string"} + instead of the correct + -\markup{\bold \italic "string"} 2.0->2.2: Doesn't handle \partcombine Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas. +2.0->2.4: + \magnify isn't changed to \fontsize. + - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2) + remove-tag isn't changed. + - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . . + first-page-number isn't changed. + - first-page-number no => printfirst-page-number = ##f + Line breaks in header strings aren't converted. + - \\\\ as line break in \header strings => \markup \center-align < + "First Line" "Second Line" > + Crescendo and decrescendo terminators aren't converted. + - \rced => \! + - \rc => \! 2.2->2.4: \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted. 2.4.2->2.5.9 \markup{ \center-align <{ ... }> } should be converted to: \markup{ \center-align {\line { ... }} } but now, \line is missing. +2.4->2.6 + Special LaTeX characters such as $~$ in text are not converted to UTF8. + @end verbatim @@ -530,9 +567,24 @@ Thus this is just a wishlist, placed here for reference. If you have input that results in a crash or an erroneous output, then that is a bug. We try to respond to bug-reports promptly, and fix them as soon as possible. Help us by sending a defective input file, so we can -reproduce the problem. Make it small, so we can easily debug the -problem. Don't forget to tell which version of LilyPond you use! Send -the report to @email{bug-lilypond@@gnu.org}. +reproduce the problem. Send the report via: + +@example +@uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs} +@end example + +A few tips: +@itemize @bullet + +@item Try to produce a very small input file which demonstrates the problem; +one or two bars is often sufficient to reproduce a bug. The smaller the +input file is, the easier it is for us to debug the problem. + +@item Don't forget to tell which version of LilyPond you use! + +@item If possible, use @code{ragged-right} in your example. This makes sure +that the bug can be reproduced in all paper sizes. +@end itemize @ignore @c the bug database is not up to date enough. @@ -546,20 +598,21 @@ been reported and a fix or workaround is already known. Here is an example of a good bug report: -@example +@verbatim It seems that placement of accidentals is broken. In the following example, the accidental touches the note head. -Using Mac OSX 10.3.5, fink package lilypond-unstable +Using Mac OSX 10.3.7, fink package lilypond-devel -\version "2.5.18" -\relative c''@{ +\version "2.7.32" +\layout { ragged-right = ##t } +\relative c'' { a4 b cis d -@} -@end example +} +@end verbatim @lilypond[quote] -\version "2.5.18" +\layout { ragged-right = ##t } \relative c''{ \override Accidental #'extra-offset = #'(1.0 . 0) a4 b cis d @@ -586,7 +639,7 @@ 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/out-www/INSTALL.html,installation instructions}. +@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}. @end ifhtml @ifnothtml installation instructions. @@ -597,7 +650,7 @@ installation instructions. 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/out-www/INSTALL.html,installation instructions}. +@uref{source/Documentation/topdocs/INSTALL.html,installation instructions}. @end ifhtml @ifnothtml installation instructions. @@ -617,3 +670,4 @@ 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}. +