Merge branch 'master' into nested-bookparts

[lilypond.git] / Documentation / user / converters.itely

diff --git a/Documentation/user/converters.itely b/Documentation/user/converters.itely
index f2e852e0c6c9947036dedc7b690eeeb2ebfd18e4..b779ef42859eef00bab8407d4ebde6ae14e809cc 100644 (file)
--- a/Documentation/user/converters.itely
+++ b/Documentation/user/converters.itely
@@ -1,4 +1,13 @@
-@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.11.51"

 
 @node Converting from other formats
 @chapter Converting from other formats
 
 @node Converting from other formats
 @chapter Converting from other formats


@@ -9,14 +18,21 @@ There are other tools that produce LilyPond input, for example GUI
 sequencers and XML converters.  Refer to the
 @uref{http://@/lilypond@/.org,website} for more details.
 
 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.

 
 
 
 

+@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 midi2ly::            Importing MIDI.
 @menu
 * Invoking midi2ly::            Importing MIDI.

+* Invoking musicxml2ly::        Importing MusicXML.
+* Invoking abc2ly::             Importing ABC.      

 * Invoking etf2ly::             Importing Finale.
 * Invoking etf2ly::             Importing Finale.

-* Invoking abc2ly::             Importing ABC.          
-* Invoking mup2ly::             Importing MUP. 
-* Generating LilyPond files::   
+* Generating LilyPond files::   GUIs, transcribers, and algorithmic composition programs.

 @end menu
 
 
 @end menu
 
 


@@ -33,11 +49,11 @@ 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
 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.
 
 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
 for pitches, durations are only written when necessary.
 
 It is possible to record a MIDI file using a digital keyboard, and


@@ -54,6 +70,9 @@ It is invoked from the command-line as follows,
 midi2ly [@var{option}]@dots{} @var{midi-file}
 @end example
 
 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}.
 
 
 The following options are supported by @command{midi2ly}.
 


@@ -73,21 +92,21 @@ Show summary of usage.
 @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
 @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}
 
 @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 -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.
 
 Be verbose.
 

-@item -v, --version
+@item -V, --version

 Print version number.
 
 @item -w, --warranty
 Print version number.
 
 @item -w, --warranty


@@ -98,47 +117,79 @@ Treat every text as a lyric.
 @end table
 
 
 @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.
 
 
 
 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
 @example

-etf2ly [@var{option}]@dots{} @var{etf-file}
+musicxml2ly [@var{option}]@dots{} @var{xml-file}

 @end example
 
 @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
 
 @table @code

+@item -a, --absolute
+convert pitches in absolute mode.
+

 @item -h,--help
 @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
 
 
 @node Invoking abc2ly


@@ -149,7 +200,7 @@ confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
 ABC is a fairly simple ASCII based format.  It is described at the ABC site:
 
 @quotation
 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:
 @end quotation
 
 @command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:


@@ -161,11 +212,15 @@ abc2ly [@var{option}]@dots{} @var{abc-file}
 The following options are supported by @command{abc2ly}:
 
 @table @code
 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 -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
 
 print version information.
 @end table
 


@@ -176,7 +231,7 @@ source file.  If you say:
 %%LY voices \set autoBeaming = ##f
 @end example
 
 %%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,
 into the current voice of the LilyPond output file.
 
 Similarly,


@@ -185,14 +240,14 @@ Similarly,
 %%LY slyrics more words
 @end example
 
 %%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.
 
 
 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.
 
 
 Multiple tunes in one file cannot be converted.
 


@@ -202,45 +257,44 @@ ABC synchronizes words and notes at the beginning of a line;
 @command{abc2ly} ignores the ABC beaming.
 
 
 @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
 
 @example

-mup2ly [@var{option}]@dots{} @var{mup-file}
+etf2ly [@var{option}]@dots{} @var{etf-file}

 @end example
 
 @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
 
 @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
 @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
 version information

-@item -w,--warranty
-print warranty and copyright. 

 @end table
 
 
 @end table
 
 

-@refbugs
+@knownissues

 
 

-Only plain notes (pitches, durations), voices, and staves are
-converted.
+The list of articulation scripts is incomplete.  Empty measures
+confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.

 
 
 @node Generating LilyPond files
 
 
 @node Generating LilyPond files


@@ -253,21 +307,33 @@ there are some external tools that also generate LilyPond files.
 
 These tools include
 
 
 These tools include
 

-@itemize @bullet
+@itemize

 @item
 @uref{http://@/denemo@/.sourceforge@/.net/,Denemo}, a graphical score editor.
 @item
 @item
 @uref{http://@/denemo@/.sourceforge@/.net/,Denemo}, a graphical score editor.
 @item

-@uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime monophonic MIDI to LilyPond converter.
+@uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime
+monophonic MIDI to LilyPond converter.

 @item
 @item

-@uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an Emacs major mode.
+@uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an
+Emacs major mode.

 @item
 @item

-@uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, which imports
+@uref{http://@/www@/.nongnu@/.org/@/xml2ly/,xml2ly}, which imports

 @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 @item
 @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 @item

-@uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit}
+@uref{http://@/noteedit@/.berlios@/.de,NoteEdit}

 which imports @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
 @item
 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
 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
 
 @end itemize