Doc: new chapter "External programs" in Usage.

[lilypond.git] / Documentation / usage / external.itely

@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.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"

@node External programs
@chapter External programs

FIXME: blah blah


@menu
* Point and click::
* Text editor support::
* Converting from other formats::
* LilyPond output in other programs::
@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 @file{vimrc} is supplied,
along with syntax coloring tools.  A Vim mode for entering music and
running LilyPond is contained in the source archive in @code{$VIM}
directory.

The LilyPond file type is detected if the file
@file{~/.vim/filetype.vim} has the following content

@example
if exists("did_load_filetypes")
  finish
endif
augroup filetypedetect
  au! BufNewFile,BufRead *.ly,*.ily           setf lilypond
augroup END
@end example

Please include this path by appending the following line to your
@file{~/.vimrc}

@example
set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
@end example

@noindent
where $@{LILYPOND_VERSION@} is your LilyPond version.  If LilyPond was not
installed in @file{/usr/local/}, then change this path accordingly.
The path may differ significantly. In Fedora the path leads to the
current version of Vim instead of Lilypond:

@example
set runtimepath+=/usr/share/vim/vim72/
@end example


@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{Alternate editors}.


@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 .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 a different language file 'LANG.ly' and corresponding pitch names,
e.g. 'deutsch' for deutsch.ly and German note names.

@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{Alternate editors}.



@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