-@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
Music can be entered also by importing it from other formats. This
chapter documents the tools included in the distribution to do so.
There are other tools that produce LilyPond input, for example GUI
-sequencers and XML converters. Refer to the
+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 convert-ly
-
-The syntax is regularly changed to simplify it or improve it in
-different ways. A side effect of this, is that LilyPond often is not
-compatible with older files. To remedy this, the program convert-ly
-can be used to deal with most of the syntax changes.
-
-It uses @code{\version} statements in the file to detect the old
-version number. For example, to upgrade all LilyPond files in the
-current directory and its subdirectories, enter the following on the
-command line.
-
-@example
- convert-ly -e `find . -name '*.ly' -print`
-@end example
-
-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 level to convert from. If this is not set, 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, 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
-
-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 convert-ly itself.
-
-@refbugs
-
-Not all language changes are handled. Only one output option can be specified.
@node Invoking midi2ly
-@section Invoking midi2ly
+@section Invoking @command{midi2ly}
@cindex MIDI
-Midi2ly translates a Type 1 MIDI file to a LilyPond source file.
+@command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
+file.
MIDI (Music Instrument Digital Interface) is a standard for digital
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 convertor for a
+useful when importing files from a program that has a converter for a
direct format.
-Midi2ly will convert 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
-then convert it to @file{.ly}. However, human players are not
+then convert it to @file{.ly}. However, human players are not
rhythmically exact enough to make a MIDI to LY conversion trivial.
-When invoked with quantizing (@code{-s} and @code{-d} options) midi2ly
-tries to compensate for these timing errors, but is not very good at
-this. It is therefore not recommended to use midi2ly for
-human-generated midi files.
+When invoked with quantizing (@code{-s} and @code{-d} options)
+@command{midi2ly} tries to compensate for these timing errors, but is not
+very good at this. It is therefore not recommended to use @command{midi2ly}
+for human-generated midi files.
It is invoked from the command-line as follows,
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 midi2ly.
+The following options are supported by @command{midi2ly}.
@table @code
@item -a, --absolute-pitches
- Print absolute pitches.
+Print absolute pitches.
+
@item -d, --duration-quant=@var{DUR}
- Quantize note durations on @var{DUR}.
+Quantize note durations on @var{DUR}.
+
@item -e, --explicit-durations
- Print explicit durations.
+Print explicit durations.
+
@item -h,--help
- Show summary of usage.
+Show summary of usage.
+
@item -k, --key=@var{acc}[:@var{minor}]
- Set default key. @var{acc} > 0 sets number of sharps; @var{acc} < 0
- sets number of flats. A minor key is indicated by ":1".
+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
+@code{:1}.
+
@item -o, --output=@var{file}
- Write output to @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
- Be verbose.
-@item -v, --version
- Print version number.
+Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
+
+@item -v, --verbose
+Be verbose.
+
+@item -V, --version
+Print version number.
+
@item -w, --warranty
- Show warranty and copyright.
+Show warranty and copyright.
+
@item -x, --text-lyrics
- Treat every text as a lyric.
+Treat every text as a lyric.
@end table
-@refbugs
+@knownissues
-Overlapping notes in an arpeggio will not be correctly rendered. The
+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 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. 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.
-It is invoked from the command-line as follows.
+@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,
@example
- etf2ly [@var{option}]@dots{} @var{etf-file}
+musicxml2ly [@var{option}]@dots{} @var{xml-file}
@end example
-The following options are supported by 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 -h,--help
-this help
-@item -o,--output=FILE
-set output filename to FILE
-@item -v,--version
-version information
-@end table
+@item -a, --absolute
+convert pitches in absolute mode.
+@item -h,--help
+print usage and option summary.
-@refbugs
+@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.
-The list of articulation scripts is incomplete. Empty measures
-confuse etf2ly. Sequences of grace notes are ended improperly.
+@item --lxml
+use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
+
+@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
-@section Invoking abc2ly
+@section Invoking @code{abc2ly}
@cindex ABC
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
-abc2ly translates from ABC to LilyPond. It is invoked as follows:
+
+@command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
@example
- abc2ly [@var{option}]@dots{} @var{abc-file}
+abc2ly [@var{option}]@dots{} @var{abc-file}
@end example
-The following options are supported by abc2ly:
+The following options are supported by @command{abc2ly}:
@table @code
-@item -h,--help
+@item -b,--beams=None
+preserve ABC's notion of beams
+@item -h,--help
this help
-@item -o,--output=@var{file}
+@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
source file. If you say:
@example
- %%LY voices \set autoBeaming = ##f
+%%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,
@example
- %%LY slyrics more words
+%%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.
-ABC synchronizes words and notes at the beginning of a line; abc2ly does
-not.
+ABC synchronizes words and notes at the beginning of a line;
+@command{abc2ly} does not.
-abc2ly ignores the ABC beaming.
+@command{abc2ly} ignores the ABC beaming.
-@node Invoking mup2ly
-@section Invoking mup2ly
+@node Invoking etf2ly
+@section Invoking @command{etf2ly}
-Mup (Music Publisher) is a shareware music notation program by Arkkra
-Enterprises. Mup2ly will convert part of a Mup file to LilyPond
-format. It is invoked as follows:
+@cindex ETF
+@cindex enigma
+@cindex Finale
+@cindex Coda Technology
-@cindex Music Publisher
-@cindex Mup
-@cindex Arkkra
+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.
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 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
+@item -h,--help
+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
-there are also external tools that generate LilyPond files.
+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
-@uref{http://@/denemo@/.sourceforge@/.net/,Denemo}.
-@itemize @bullet
-@item @uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports
-@uref{http://@/www@/.musicxml@/.com/,MusicXML}
+@itemize
@item
-@uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit}
-which imports MusicXML
-@item @uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden},
+@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://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an
+Emacs major mode.
+@item
+@uref{http://@/www@/.nongnu@/.org/@/xml2ly/,xml2ly}, which imports
+@uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
+@item
+@uref{http://@/noteedit@/.berlios@/.de,NoteEdit}
+which imports @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
+@item
+@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
+
projects / lilypond.git / blobdiff