X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Fexternal.itely;fp=Documentation%2Fusage%2Fexternal.itely;h=01e637bdc9726ccdc5fbe64caf6191a5b4060aeb;hb=e90f0536f9be39ada0bef0aeb0d275dec3b2fb5b;hp=0000000000000000000000000000000000000000;hpb=a8c9e8a7ca320ab0df5fd32e717fd62cd7635ce6;p=lilypond.git diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely new file mode 100644 index 0000000000..01e637bdc9 --- /dev/null +++ b/Documentation/usage/external.itely @@ -0,0 +1,599 @@ +@c -*- coding: utf-8; mode: texinfo; -*- + +@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. For details, see the Contributors' + Guide, node Updating translation committishes.. +@end ignore + +@c \version "2.14.0" + +@node External programs +@chapter External programs + +LilyPond can interact with other programs in various ways. + +@menu +* Point and click:: +* Text editor support:: +* Converting from other formats:: +* LilyPond output in other programs:: +* Independent includes:: +@end menu + + +@node Point and click +@section Point and click + +@cindex point and click + +Point and click lets you find notes in the input by clicking on them +in the PDF viewer. This makes it easier to find input that causes +some error in the sheet music. + +When this functionality is active, LilyPond adds hyperlinks to the PDF +file. These hyperlinks are sent to the web-browser, which opens a +text-editor with the cursor in the right place. + +To make this chain work, you should configure your PDF viewer to +follow hyperlinks using the @file{lilypond-invoke-editor} script +supplied with LilyPond. + +For Xpdf on UNIX, the following should be present in +@file{xpdfrc}@footnote{On UNIX, this file is found either in +@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.} + +@example +urlCommand "lilypond-invoke-editor %s" +@end example + +The program @file{lilypond-invoke-editor} is a small helper +program. It will invoke an editor for the special @code{textedit} +URIs, and run a web browser for others. It tests the environment +variable @code{EDITOR} for the following patterns, + +@table @code +@item emacs + this will invoke +@example +emacsclient --no-wait +@var{line}:@var{column} @var{file} +@end example +@item gvim + this will invoke +@example +gvim --remote +:@var{line}:norm@var{column} @var{file} +@end example + +@item nedit +this will invoke +@example + nc -noask +@var{line} @var{file}' +@end example +@end table + +The environment variable @code{LYEDITOR} is used to override this. It +contains the command line to start the editor, where @code{%(file)s}, +@code{%(column)s}, @code{%(line)s} is replaced with the file, column +and line respectively. The setting + +@example +emacsclient --no-wait +%(line)s:%(column)s %(file)s +@end example + +@noindent +for @code{LYEDITOR} is equivalent to the standard emacsclient +invocation. + + +@cindex file size, output + +The point and click links enlarge the output files significantly. For +reducing the size of PDF and PS files, point and click may be switched +off by issuing + +@example +\pointAndClickOff +@end example + +@noindent +in a @file{.ly} file. Point and click may be explicitly enabled with + +@example +\pointAndClickOn +@end example + +Alternately, you may disable point and click with a command-line +option: + +@example +lilypond -dno-point-and-click file.ly +@end example + +@warning{You should always turn off point and click in any LilyPond +files to be distributed to avoid including path information about +your computer in the .pdf file, which can pose a security risk.} +@node Text editor support +@section Text editor support + +@cindex editors +@cindex vim +@cindex emacs +@cindex modes, editor +@cindex syntax coloring +@cindex coloring, syntax + +There is support for different text editors for LilyPond. + +@menu +* Emacs mode:: +* Vim mode:: +* Other editors:: +@end menu + +@node Emacs mode +@unnumberedsubsec Emacs mode + +Emacs has a @file{lilypond-mode}, which provides keyword +autocompletion, indentation, LilyPond specific parenthesis matching +and syntax coloring, handy compile short-cuts and reading LilyPond +manuals using Info. If @file{lilypond-mode} is not installed on your +platform, see below. + +An Emacs mode for entering music and running LilyPond is contained in +the source archive in the @file{elisp} directory. Do @command{make +install} to install it to @var{elispdir}. The file @file{lilypond-init.el} +should be placed to @var{load-path}@file{/site-start.d/} or appended +to your @file{~/.emacs} or @file{~/.emacs.el}. + +As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to +your @var{load-path} by appending the following line (as modified) to your +@file{~/.emacs} + +@c any reason we do not advise: (push "~/site-lisp" load-path) +@example +(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path)) +@end example + + +@node Vim mode +@unnumberedsubsec Vim mode + +For @uref{http://@/www@/.vim@/.org,Vim}, a filetype plugin, indent +mode, and syntax-highlighting mode are available to use with +LilyPond. To enable all of these features, create (or modify) +your @file{$HOME/.vimrc} to contain these three lines, in order: + +@example +filetype off +set runtimepath+=/usr/local/share/lilypond/current/vim/ +filetype on +@end example + +@noindent +If LilyPond is not installed in the @file{/usr/local/} directory, +change the path appropriately. This topic is discussed in +@rlearning{Other sources of information}. + + +@node Other editors +@unnumberedsubsec Other editors + +Other editors (both text and graphical) support LilyPond, but +their special configuration files are not distributed with +LilyPond. Consult their documentation for more information. Such +editors are listed in @rweb{Easier editing}. + + +@node Converting from other formats +@section 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 +@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 +@rweb{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 midi2ly:: Importing MIDI. +* Invoking musicxml2ly:: Importing MusicXML. +* Invoking abc2ly:: Importing ABC. +* Invoking etf2ly:: Importing Finale. +* Other formats:: +@end menu + + + +@node Invoking midi2ly +@subsection Invoking @command{midi2ly} + +@cindex MIDI + +@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 a converter for a +direct format. + +@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 +rhythmically exact enough to make a MIDI to LY conversion trivial. +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, +@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}. + +@table @code +@item -a, --absolute-pitches +Print absolute pitches. + +@item -d, --duration-quant=@var{DUR} +Quantize note durations on @var{DUR}. + +@item -e, --explicit-durations +Print explicit durations. + +@item -h,--help +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 +@code{:1}. + +@item -o, --output=@var{file} +Write output to @var{file}. + +@item -s, --start-quant=@var{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. + +@item -w, --warranty +Show warranty and copyright. + +@item -x, --text-lyrics +Treat every text as a lyric. +@end table + + +@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 musicxml2ly +@subsection Invoking @code{musicxml2ly} + +@cindex MusicXML + +@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 @file{.ly} +file. It is invoked from the command-line. + + +It is invoked from the command-line as follows, +@example +musicxml2ly [@var{option}]@dots{} @var{xml-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. + +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 +print usage and option summary. + +@item -l, --language=LANG +use LANG for pitch names, e.g. 'deutsch' for note names in German. + +@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 +@subsection Invoking @code{abc2ly} + +@warning{This program is not supported, and may be remove from +future versions of LilyPond.} + +@cindex ABC + +ABC is a fairly simple ASCII based format. It is described at the ABC site: + +@quotation +@uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}. +@end quotation + +@command{abc2ly} translates from ABC to LilyPond. It is invoked as follows: + +@example +abc2ly [@var{option}]@dots{} @var{abc-file} +@end example + +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 -s,--strict +be strict about success +@item --version +print version information. +@end table + +There is a rudimentary facility for adding LilyPond code to the ABC +source file. If you say: + +@example +%%LY voices \set autoBeaming = ##f +@end example + +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 +@end example + +will cause the text following the @q{slyrics} keyword to be inserted +into the current line of lyrics. + + +@knownissues + +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; +@command{abc2ly} does not. + +@command{abc2ly} ignores the ABC beaming. + + +@node Invoking etf2ly +@subsection Invoking @command{etf2ly} + +@warning{This program is not supported, and may be remove from +future versions of LilyPond.} + +@cindex ETF +@cindex enigma +@cindex Finale +@cindex Coda Technology + +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 +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 +@item -h,--help +this help +@item -o,--output=@var{FILE} +set output filename to @var{FILE} +@item --version +version information +@end table + + +@knownissues + +The list of articulation scripts is incomplete. Empty measures +confuse @command{etf2ly}. Sequences of grace notes are ended improperly. + + +@node Other formats +@subsection Other formats + +@cindex External programs, generating LilyPond files + +LilyPond itself does not come with support for any other formats, +but some external tools can also generate LilyPond files. These +are listed in @rweb{Easier editing}. + + + +@node LilyPond output in other programs +@section LilyPond output in other programs + +This section shows methods to integrate text and music, different than +the automated method with @command{lilypond-book}. + +@menu +* Many quotes from a large score:: +* Inserting LilyPond output into OpenOffice.org:: +* Inserting LilyPond output into other programs:: +@end menu + +@node Many quotes from a large score +@unnumberedsubsec Many quotes from a large score + +If you need to quote many fragments from a large score, you can also use +the clip systems feature, see @ruser{Extracting fragments of music}. + + +@node Inserting LilyPond output into OpenOffice.org +@unnumberedsubsec Inserting LilyPond output into OpenOffice.org + +@cindex OpenOffice.org + +LilyPond notation can be added to OpenOffice.org with +@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}. + + +@node Inserting LilyPond output into other programs +@unnumberedsubsec Inserting LilyPond output into other programs + +To insert LilyPond output in other programs, use @code{lilypond} +instead of @code{lilypond-book}. Each example must be created +individually and added to the document; consult the documentation for +that program. Most programs will be able to insert LilyPond output in +@file{PNG}, @file{EPS}, or @file{PDF} formats. + +To reduce the white space around your LilyPond score, use +the following options + +@example +\paper@{ + indent=0\mm + line-width=120\mm + oddFooterMarkup=##f + oddHeaderMarkup=##f + bookTitleMarkup = ##f + scoreTitleMarkup = ##f +@} + +@{ c1 @} +@end example + +To produce a useful @file{EPS} file, use + +@example +lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly + +@file{PNG}: +lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly +@end example + + +@node Independent includes +@section Independent @code{include}s + +Some people have written large (and useful!) code that can be +shared between projects. This code might eventually make its way +into LilyPond itself, but until that happens, you must download +and @code{\include} them manually. + + +@menu +* MIDI articulation:: +@end menu + + +@node MIDI articulation +@subsection MIDI articulation + +LilyPond can be used to produce MIDI output, for +@qq{proof-hearing} what has been written. However, only dynamics, +explicit tempo markings, and the notes and durations themselves +are produced in the output. + +The @emph{articulate} project is one attempt to get more of the +information in the score into he MIDI. It works by shortening +notes not under slurs, to @q{articulate} the notes. The amount of +shortening depends on any articulation markings attached to a +note: staccato halves the note value, tenuto gives a note its full +duration, and so on. The script also realises trills and turns, +and could be extended to expand other ornaments such as mordents. + +@example +@uref{http://@/www@/.nicta@/.com@/.au/@/people/@/chubbp/@/articulate} +@end example + +@knownissues + +Its main limitation is that it can only affect things it knows +about: anything that is merely textual markup (instead of a note +property) is still ignored. + +