--- /dev/null
+@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.
+
+
projects / lilypond.git / blobdiff