X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fconverters.itely;h=d8a3d8c2d669523c0aece9a3956c892eb7e25349;hb=fe646e97af1e6cb3a21bcf25282fa1239fc2b874;hp=78bb8570de7c221201804d440e907bf8f3801eca;hpb=b62bc49dc3e2f1c5fdb2c8e5fa0d2b003dc4912e;p=lilypond.git diff --git a/Documentation/user/converters.itely b/Documentation/user/converters.itely index 78bb8570de..d8a3d8c2d6 100644 --- a/Documentation/user/converters.itely +++ b/Documentation/user/converters.itely @@ -1,4 +1,11 @@ -@c -*- coding: latin-1; mode: texinfo; -*- +@c -*- coding: utf-8; mode: texinfo; -*- +@c This file is part of lilypond.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 @node Converting from other formats @chapter Converting from other formats @@ -9,121 +16,30 @@ 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. +These are separate programs from lilypond itself, and are run +on the command-line. By @q{command-line}, we mean the command +line in the operating system. Windows users +might be more familiar with the terms @q{DOS shell} or +@q{command shell}; OSX users might be more familiar with the +terms @q{terminal} or @q{console}. OSX users should also +consult @ref{Notes for the MacOS X app}. + +Describing how to use +this part of an operating system is outside the scope of this +manual; please consult other documentation on this topic if +you are unfamiliar with the command-line. + @menu -* Invoking convert-ly:: Older LilyPond versions. * Invoking midi2ly:: Importing MIDI. * Invoking etf2ly:: Importing Finale. -* Invoking abc2ly:: Importing ABC. -* Invoking mup2ly:: Importing MUP. -* Other formats:: +* Invoking musicxml2ly:: +* Invoking abc2ly:: Importing ABC. +* Generating LilyPond files:: @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 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 -Dec 22, 2004 - -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. -@end verbatim - @node Invoking midi2ly @section Invoking @command{midi2ly} @@ -158,6 +74,9 @@ 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 @command{midi2ly}. @@ -177,7 +96,7 @@ 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 -":1". +@samp{:1}. @item -o, --output=@var{file} Write output to @var{file}. @@ -227,6 +146,10 @@ It is invoked from the command-line as follows. etf2ly [@var{option}]@dots{} @var{etf-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{etf2ly}: @table @code @@ -244,6 +167,29 @@ version information The list of articulation scripts is incomplete. Empty measures confuse @command{etf2ly}. Sequences of grace notes are ended improperly. +@node Invoking musicxml2ly +@section Invoking @code{musicxml2ly} + +@uref{http://@/www.@/recordarde@/.com/xml@/.html,MusicXML} is an XML dialect +for representing music notation. + +@command{musicxml2ly} extracts the notes from part-wise MusicXML +files, and writes it to a .ly file. It is invoked from the command-line. + +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{musicxml2ly}: + +@table @code +@item -h,--help +print usage and option summary. +@item -o,--output=@var{file} +set output filename to @var{file}. (default: print to stdout) +@item -v,--version +print version information. +@end table @node Invoking abc2ly @section Invoking @code{abc2ly} @@ -253,7 +199,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 -@uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}. +@uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/abc2mtex/@/abc@/.txt}. @end quotation @command{abc2ly} translates from ABC to LilyPond. It is invoked as follows: @@ -280,7 +226,7 @@ source file. If you say: %%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, @@ -289,14 +235,14 @@ 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 -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. @@ -306,65 +252,37 @@ ABC synchronizes words and notes at the beginning of a line; @command{abc2ly} ignores the ABC beaming. -@node Invoking mup2ly -@section Invoking @command{mup2ly} - -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: -@cindex Music Publisher -@cindex Mup -@cindex Arkkra +@node Generating LilyPond files +@section Generating LilyPond files -@example -mup2ly [@var{option}]@dots{} @var{mup-file} -@end example +@cindex External programs, generating LilyPond files -The following options are supported by @command{mup2ly}: - -@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 -version information -@item -w,--warranty -print warranty and copyright. -@end table - - -@refbugs - -Only plain notes (pitches, durations), voices, and staves are -converted. - - -@node Other formats -@section Other formats - -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 @item -@uref{http://@/denemo@/.sourceforge@/.net/,Denemo}. +@uref{http://@/denemo@/.sourceforge@/.net/,Denemo}, a graphical score editor. @item -@uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports -@uref{http://@/www@/.musicxml@/.com/,MusicXML} +@uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime +monophonic MIDI to LilyPond converter. @item -@uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit} -which imports MusicXML +@uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an +Emacs major mode. @item -@uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden}, +@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 @end itemize +