@menu
* Invoking lilypond::
* Error messages::
+* Updating files with convert-ly::
* Reporting bugs::
* Editor support::
-* Invoking lilypond-latex::
@end menu
@node Invoking lilypond
some internal variables. Use @code{-e '(ly:option-usage)'} for more
information.
-
@item -f,--format=@var{format}
-A comma separated list of back-end output formats to use. Choices are
+which formats should be written. Choices are @code{svg}, @code{ps},
+@code{pdf}, @code{png}, @code{tex}, @code{dvi}.
+
+@item -b,--backend=@var{format}
+the output format to use for the back-end. Choices are
@table @code
@item tex
-for @TeX{} output, to be processed with La@TeX{}
+for @TeX{} output, to be processed with La@TeX{}. If present, the file
+@file{file.textmetrics} is read to determine text extents.
+@item texstr
+dump text strings to @file{.texstr} file, which can be run through
+(La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
+extents of strings of text.
@item ps
- for PostScript
+ for PostScript.
@cindex PostScript output
+
+ Postscript files include TTF, Type1 and OTF fonts. No subsetting of
+ these fonts is done. When using oriental character sets, this can
+ lead to huge files.
+
+@item eps
+ for encapsulated PostScript. This dumps every page (system) as a separate
+@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.
+
@item svg
- for SVG (Scalable Vector Graphics.)
+ for SVG (Scalable Vector Graphics)
@cindex SVG (Scalable Vector Graphics)
@item scm
for a dump of the raw, internal Scheme-based drawing commands.
@cindex Scheme dump
-@end itemize
+@end table
@cindex output format, setting
Set init file to @var{file} (default: @file{init.ly}).
@item -o,--output=@var{FILE}
-Set the default output file to @var{FILE}.
+Set the default output file to @var{FILE}. The appropriate
+suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
+for tex, etc).
@item --ps
Generate PostScript.
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
+@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
above the indicated position.
+@node Updating files with convert-ly
+@section Updating with @command{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
+
+@example
+covert-ly -e myfile.ly
+@end example
+
+If there are no changes to myfile.ly and file called myfile.ly.NEW
+is created, then myfile.ly is already updated.
+
+To upgrade LilyPond fragments in texinfo files, use
+
+@example
+convert-ly --from=... --to=... --no-version *.itely
+@end example
+
+In general, the program is invoked as follows:
+
+@example
+convert-ly [@var{option}]@dots{} @var{file}@dots{}
+@end example
+
+
+The following options can be given:
+
+@table @code
+@item -e,--edit
+Do an inline edit of the input file. Overrides @code{--output}.
+
+@item -f,--from=@var{from-patchlevel}
+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.
+
+@item -s, --show-rules
+Show all known conversions and exit.
+
+@item --to=@var{to-patchlevel}
+Set the goal version of the conversion. It defaults to the latest
+available version.
+
+@item -h, --help
+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
+
+Not all language changes are handled. Only one output option can be
+specified.
+
+
+@c We might want to make this a completely new section, along with more
+@c info about how to upgrade old input files. -gp
+
+@ignore
+Copy and paste from CVS, last updated
+Feb 14, 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.
+
+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:
+ To be able to run convert-ly
+ 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.
+2.0->2.2:
+ Doesn't handle \partcombine
+ Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
+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.
+@end verbatim
+
+
@node Reporting bugs
@section Reporting bugs
of a symbol in the graphical output. See @ref{Point and click}.
-
-
-@node Invoking lilypond-latex
-@section Invoking lilypond-latex
-
-Before LilyPond 2.4, the @code{lilypond} program only generated music
-notation. Titles and page layout was done in a separate wrapper
-program. For compatibility with older files, this wrapper program has
-been retained as @code{lilypond-latex}. It uses the LilyPond program
-and La@TeX{} to create a nicely titled piece of sheet music. Use of
-this program is only necessary if the input file contains special
-La@TeX{} options or formatting codes in markup texts.
-
-The @code{lilypond-latex} wrapper is invoked from the command-line as
-follows
-@example
-@code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{}
-@end example
-
-To have @code{lilypond-latex} read from stdin, use a dash (@code{-}) for
-@var{file}. The program supports the following options.
-
-@cindex stdin, reading
-
-@table @code
-@item -k,--keep
-Keep the temporary directory with all output files. The temporary
-directory is created in the current directory as @code{@code{lilypond}.dir}.
-
-@item -h,--help
-Print usage help.
-
-@item -I,--include=@var{dir}
-Add @var{dir} to LilyPond's include path.
-
-@item -o,--output=@var{file}
-Generate output to @var{file}. The extension of @var{file} is ignored.
-
-@item --png
-Also generate pictures of each page, in PNG format.
-
-@item --preview
-Also generate a picture of the first system of the score.
-
-@cindex preview
-@cindex picture
-@cindex bitmap
-@cindex pixmap
-@cindex thumbnail
-@cindex screen shot
-
-@item -s,--set=@var{key}=@var{val}
-Add @var{key}= @var{val} to the settings, overriding those specified
-in the files. Possible keys: @code{language}, @code{latexheaders},
-@code{latexpackages}, @code{latexoptions}, @code{papersize},
-@code{linewidth}, @code{orientation},
-@code{textheight}.
-
-@item -v,--version
-Show version information.
-
-@item -V,--verbose
-Be verbose. This prints out commands as they are executed, and more
-information about the formatting process is printed.
-
-@item --debug
-Print even more information. This is useful when generating bug reports.
-
-@item -w,--warranty
-Show the warranty with which GNU LilyPond comes. (It comes with
-@strong{NO WARRANTY}!)
-@end table
-
-
-@subsection Additional parameters
-
-The @code{lilypond} program responds to several parameters specified
-in a @code{\layout} section of the input file. They can be overridden
-by supplying a @code{--set} command line option.
-
-@table @code
-@item language
-Specify La@TeX{} language: the @code{babel} package will be
-included. Default: unset.
-
-Read from the @code{\header} block.
-
-@item latexheaders
-Specify additional La@TeX{} header files.
-Normally read from the @code{\header} block. Default value: empty.
-
-@item latexpackages
-Specify additional La@TeX{} package files. This works cumulative,
-so you can add multiple packages using multiple @code{-s=latexpackages} options.
-Normally read from the @code{\header} block. Default value:
-@code{geometry}.
-
-@item latexoptions
-Specify additional options for the La@TeX{}
-@code{\documentclass}. You can put any valid value here. This was
-designed to allow @code{lilypond} to produce output for double-sided
-paper, with balanced margins and page numbers on alternating sides. To
-achieve this specify @code{twoside}.
-
-@item orientation
-Set orientation. Choices are @code{portrait} or @code{landscape}. Is
-read from the @code{\layout} block, if set.
-
-@item textheight
-The vertical extension of the music on the page. It is normally
-calculated automatically, based on the paper size.
-
-@item linewidth
-The music line width. It is normally read from the @code{\layout}
-block.
-
-@item papersize
-The paper size (as a name, e.g., @code{a4}). It is normally read from
-the @code{\layout} block.
-
-@item fontenc
-The font encoding, should be set identical to the @code{font-encoding}
-property in the score.
-@end table
projects / lilypond.git / blobdiff