-@c -*- coding: latin-1; mode: texinfo; -*-
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond-program.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
+@c \version "2.12.0"
@node Converting from other formats
@chapter Converting from other formats
sequencers and XML converters. Refer to the
@uref{http://@/lilypond@/.org,website} for more details.
+These are separate programs from @command{lilypond} itself, and are
+run on the command line; see @ref{Command-line usage} for more
+information. If you have MacOS 10.3 or 10.4 and you have trouble
+running some of these scripts, e.g. @code{convert-ly}, see @ref{Setup
+for MacOS X}.
+
+@knownissues
+We unfortunately do not have the resources to maintain these
+programs; please consider them @qq{as-is}. Patches are appreciated, but
+bug reports will almost certainly not be resolved.
@menu
-* Invoking convert-ly:: Older LilyPond versions.
* Invoking midi2ly:: Importing MIDI.
+* Invoking musicxml2ly:: Importing MusicXML.
+* Invoking abc2ly:: Importing ABC.
* Invoking etf2ly:: Importing Finale.
-* Invoking abc2ly:: Importing ABC.
-* Invoking mup2ly:: Importing MUP.
-* Other formats::
+* Generating LilyPond files:: GUIs, transcribers, and algorithmic composition programs.
@end menu
-@node Invoking convert-ly
-@section Invoking @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 if a 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.
@node Invoking midi2ly
@section Invoking @command{midi2ly}
instruments: it specifies cabling, a serial protocol and a file
format. The MIDI file format is a de facto standard format for
exporting music from other programs, so this capability may come in
-useful when importing files from a program that has a convertor for a
+useful when importing files from a program that has a converter for a
direct format.
-@command{midi2ly} converts tracks into @internalsref{Staff} and
-channels into @internalsref{Voice} contexts. Relative mode is used
+@command{midi2ly} converts tracks into @rinternals{Staff} and
+channels into @rinternals{Voice} contexts. Relative mode is used
for pitches, durations are only written when necessary.
It is possible to record a MIDI file using a digital keyboard, and
midi2ly [@var{option}]@dots{} @var{midi-file}
@end example
+Note that by @q{command-line}, we mean the command line of the
+operating system. See @ref{Converting from other formats}, for
+more information about this.
The following options are supported by @command{midi2ly}.
@item -k, --key=@var{acc}[:@var{minor}]
Set default key. @math{@var{acc} > 0} sets number of sharps;
@math{@var{acc} < 0} sets number of flats. A minor key is indicated by
-":1".
+@code{:1}.
@item -o, --output=@var{file}
Write output to @var{file}.
@item -s, --start-quant=@var{DUR}
-Quantize note starts on DUR.
+Quantize note starts on @var{DUR}.
@item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
-@item -V, --verbose
+@item -v, --verbose
Be verbose.
-@item -v, --version
+@item -V, --version
Print version number.
@item -w, --warranty
@end table
-@refbugs
+@knownissues
Overlapping notes in an arpeggio will not be correctly rendered. The
first note will be read and the others will be ignored. Set them all
to a single duration and add phrase markings or pedal indicators.
-@node Invoking etf2ly
-@section Invoking @command{etf2ly}
+@node Invoking musicxml2ly
+@section Invoking @code{musicxml2ly}
-@cindex ETF
-@cindex enigma
-@cindex Finale
-@cindex Coda Technology
+@cindex MusicXML
-ETF (Enigma Transport Format) is a format used by Coda Music
-Technology's Finale product. @command{etf2ly} will convert part of an ETF
-file to a ready-to-use LilyPond file.
+@uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
+for representing music notation.
+
+@command{musicxml2ly} extracts the notes, articulations, score structure,
+lyrics, etc. from part-wise MusicXML files, and writes them to a .ly
+file. It is invoked from the command-line.
-It is invoked from the command-line as follows.
+It is invoked from the command-line as follows,
@example
-etf2ly [@var{option}]@dots{} @var{etf-file}
+musicxml2ly [@var{option}]@dots{} @var{xml-file}
@end example
-The following options are supported by @command{etf2ly}:
+Note that by @q{command-line}, we mean the command line of the
+operating system. See @ref{Converting from other formats}, for
+more information about this.
+
+If the given filename is @file{-}, @command{musicxml2ly} reads input
+from the command line.
+
+The following options are supported by @command{musicxml2ly}:
@table @code
+@item -a, --absolute
+convert pitches in absolute mode.
+
@item -h,--help
-this help
-@item -o,--output=FILE
-set output filename to FILE
-@item -v,--version
-version information
-@end table
+print usage and option summary.
+@item -l, --language=LANG
+use a different language file 'LANG.ly' and corresponding pitch names,
+e.g. 'deutsch' for deutsch.ly and German note names.
-@refbugs
+@item --lxml
+use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
-The list of articulation scripts is incomplete. Empty measures
-confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
+@item --nd --no-articulation-directions
+do not convert directions (@code{^}, @code{_} or @code{-}) for
+articulations, dynamics, etc.
+
+@item --no-beaming
+do not convert beaming information, use LilyPond's automatic
+beaming instead.
+
+@item -o,--output=@var{file}
+set output filename to @var{file}. If @var{file} is @file{-}, the output
+will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
+be used.
+
+@item -r,--relative
+convert pitches in relative mode (default).
+
+@item -v,--verbose
+be verbose.
+
+@item --version
+print version information.
+
+@item -z,--compressed
+input file is a zip-compressed MusicXML file.
+@end table
@node Invoking abc2ly
ABC is a fairly simple ASCII based format. It is described at the ABC site:
@quotation
-@uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}.
+@uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
@end quotation
@command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
The following options are supported by @command{abc2ly}:
@table @code
+@item -b,--beams=None
+preserve ABC's notion of beams
@item -h,--help
this help
@item -o,--output=@var{file}
set output filename to @var{file}.
-@item -v,--version
+@item -s,--strict
+be strict about success
+@item --version
print version information.
@end table
%%LY voices \set autoBeaming = ##f
@end example
-This will cause the text following the keyword ``voices'' to be inserted
+This will cause the text following the keyword @q{voices} to be inserted
into the current voice of the LilyPond output file.
Similarly,
%%LY slyrics more words
@end example
-will cause the text following the ``slyrics'' keyword to be inserted
+will cause the text following the @q{slyrics} keyword to be inserted
into the current line of lyrics.
-@refbugs
+@knownissues
-The ABC standard is not very ``standard''. For extended features
-(e.g., polyphonic music) different conventions exist.
+The ABC standard is not very @q{standard}. For extended features
+(e.g., polyphonic music) different conventions exist.
Multiple tunes in one file cannot be converted.
@command{abc2ly} ignores the ABC beaming.
-@node Invoking mup2ly
-@section Invoking @command{mup2ly}
+@node Invoking etf2ly
+@section Invoking @command{etf2ly}
+
+@cindex ETF
+@cindex enigma
+@cindex Finale
+@cindex Coda Technology
-Mup (Music Publisher) is a shareware music notation program by Arkkra
-Enterprises. @command{mup2ly} will convert part of a Mup file to LilyPond
-format. It is invoked from the command-line as follows:
+ETF (Enigma Transport Format) is a format used by Coda Music
+Technology's Finale product. @command{etf2ly} will convert part of an ETF
+file to a ready-to-use LilyPond file.
-@cindex Music Publisher
-@cindex Mup
-@cindex Arkkra
+It is invoked from the command-line as follows.
@example
-mup2ly [@var{option}]@dots{} @var{mup-file}
+etf2ly [@var{option}]@dots{} @var{etf-file}
@end example
-The following options are supported by @command{mup2ly}:
+Note that by @q{command-line}, we mean the command line of the
+operating system. See @ref{Converting from other formats}, for
+more information about this.
+
+The following options are supported by @command{etf2ly}:
@table @code
-@item -d,--debug
-show what constructs are not converted, but skipped.
-@item -D, --define=@var{name}[=@code{exp}]
-define macro @var{name} with opt expansion @code{exp}
-@item -E,--pre-process
-only run the pre-processor
@item -h,--help
-print help
-@item -o,--output=@var{file}
-write output to @var{file}
-@item -v,--version
+this help
+@item -o,--output=@var{FILE}
+set output filename to @var{FILE}
+@item --version
version information
-@item -w,--warranty
-print warranty and copyright.
@end table
-@refbugs
+@knownissues
+
+The list of articulation scripts is incomplete. Empty measures
+confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
-Only plain notes (pitches, durations), voices, and staves are
-converted.
+@node Generating LilyPond files
+@section Generating LilyPond files
-@node Other formats
-@section Other formats
+@cindex External programs, generating LilyPond files
-LilyPond itself does not come with support for other formats, but
+LilyPond itself does not come with support for any other formats, but
there are some external tools that also generate LilyPond files.
These tools include
-@itemize @bullet
+@itemize
+@item
+@uref{http://@/www@/.denemo@/.org/,Denemo}, a graphical score editor.
+@item
+@uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime
+monophonic MIDI to LilyPond converter.
@item
-@uref{http://@/denemo@/.sourceforge@/.net/,Denemo}.
+@uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an
+Emacs major mode.
@item
-@uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports
-@uref{http://@/www@/.musicxml@/.com/,MusicXML}
+@uref{http://@/www@/.nongnu@/.org/@/xml2ly/,xml2ly}, which imports
+@uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
@item
-@uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit}
-which imports MusicXML
+@uref{http://@/noteedit@/.berlios@/.de,NoteEdit}
+which imports @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
@item
-@uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden},
+@uref{http://@/www@/.rosegardenmusic@/.com,Rosegarden},
which imports MIDI
+@item
+@uref{http://@/common-lisp@/.net/project/fomus/,FOMUS},
+a LISP library to generate music notation
+@item
+@uref{http://vsr.informatik.tu-chemnitz.de/staff/jan/nted/nted.xhtml},
+has experimental export for LilyPond.
+@item
+@uref{http://www.tuxguitar.com.ar/}, can export to LilyPond.
+@item
+@uref{http://musescore.org} can also export to LilyPond.
@end itemize
+