Guide, node Updating translation committishes..
@end ignore
-@c \version "2.14.0"
+@c \version "2.19.21"
@node External programs
@chapter External programs
@node Point and click
@section Point and click
-Point and click adds links to pdf documents for certain music
-elements.
+@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.
@menu
+* Configuring the system for point and click::
* Enabling point and click::
* Selective point-and-click::
@end menu
-@node Enabling point and click
-@unnumberedsubsec Enabling 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.
+@node Configuring the system for point and click
+@subsection Configuring the system
-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.
+When this functionality is active, LilyPond adds hyperlinks to PDF and
+SVG files. These hyperlinks are sent to a @q{URI helper} or a
+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}. On UNIX, this file is found either in
-@file{/etc/xpdfrc} or as @file{$HOME/.xpdfrc}.
-
-@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
for @code{LYEDITOR} is equivalent to the standard emacsclient
invocation.
+@menu
+* Using Xpdf for point and click::
+* Using GNOME 2 for point and click::
+* Using GNOME 3 for point and click::
+* Extra configuration for Evince::
+@end menu
+
+
+@node Using Xpdf for point and click
+@unnumberedsubsubsec Using Xpdf
+
+@cindex Xpdf
+
+For Xpdf on UNIX, the following should be present in
+@file{xpdfrc}. On UNIX, this file is found either in
+@file{/etc/xpdfrc} or as @file{$HOME/.xpdfrc}.
+
+@example
+urlCommand "lilypond-invoke-editor %s"
+@end example
+
+If you are using Ubuntu, it is likely that the version of Xpdf
+installed with your system crashes on every PDF file: this state
+has been persisting for several years and is due to library
+mismatches. Your best bet is to install a current @samp{xpdf}
+package and the corresponding @samp{libpoppler} package from
+Debian instead. Once you have tested that this works, you might
+want to use
+
+@example
+sudo apt-mark hold xpdf
+@end example
+
+@noindent
+in order to keep Ubuntu from overwriting it with the next
+@q{update} of its crashing package.
+
+
+@node Using GNOME 2 for point and click
+@unnumberedsubsubsec Using GNOME 2
+
+For using GNOME 2 (and PDF viewers integrated with it), the magic
+invocation for telling the system about the @samp{textedit:} URI
+is;
+
+@smallexample
+gconftool-2 -t string -s /desktop/gnome/url-handlers/textedit/command "lilypond-invoke-editor %s"
+gconftool-2 -s /desktop/gnome/url-handlers/textedit/needs_terminal false -t bool
+gconftool-2 -t bool -s /desktop/gnome/url-handlers/textedit/enabled true
+@end smallexample
+
+After that invocation;
+
+@example
+gnome-open textedit:///etc/issue:1:0:0
+@end example
+
+@noindent
+should call @file{lilypond-invoke-editor} for opening files.
+
+
+@node Using GNOME 3 for point and click
+@unnumberedsubsubsec Using GNOME 3
+
+In GNOME 3, URIs are handled by the @q{gvfs} layer rather than by
+@q{gconf}. Create a file in a local directory such as @file{/tmp}
+that is called @file{lilypond-invoke-editor.desktop} and has the
+contents;
+
+@example
+[Desktop Entry]
+Version=1.0
+Name=lilypond-invoke-editor
+GenericName=Textedit URI handler
+Comment=URI handler for textedit:
+Exec=lilypond-invoke-editor %u
+Terminal=false
+Type=Application
+MimeType=x-scheme-handler/textedit;
+Categories=Editor
+NoDisplay=true
+@end example
+and then execute the commands
+@example
+xdg-desktop-menu install ./lilypond-invoke-editor.desktop
+xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit
+@end example
+
+After that invocation;
+
+@example
+gnome-open textedit:///etc/issue:1:0:0
+@end example
+@noindent
+should call @file{lilypond-invoke-editor} for opening files.
+
+
+@node Extra configuration for Evince
+@unnumberedsubsubsec Extra configuration for Evince
+
+@cindex Evince
+
+If @code{gnome-open} works, but Evince still refuses to open point
+and click links due to denied permissions, you might need to
+change the Apparmor profile of Evince which controls the kind of
+actions Evince is allowed to perform.
+For Ubuntu, the process is to edit the file
+@file{/etc/apparmor.d/local/usr.bin.evince} and append the
+following lines:
+
+@example
+# For Textedit links
+/usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper,
+@end example
+@noindent
+
+After adding these lines, call
+
+@example
+sudo apparmor_parser -r -T -W /etc/apparmor.d/usr.bin.evince
+@end example
+
+@noindent
+Now Evince should be able to open point and click links. It is
+likely that similar configurations will work for other viewers.
+
+
+@node Enabling point and click
+@unnumberedsubsec Enabling point and click
@cindex file size, output
+Point and click functionality is enabled by default when creating
+PDF or SVG files.
+
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
+reducing the size of these (and PS) files, point and click may
+be switched off by issuing
@example
\pointAndClickOff
@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.}
+your computer in the PDF file, which can pose a security risk.}
+
@node Selective point-and-click
@unnumberedsubsec Selective point-and-click
@example
\pointAndClickTypes #'note-event
-\relative c' @{
- c2\f( f)
+\relative @{
+ c'2\f( f)
@}
@end example
@example
#(ly:set-option 'point-and-click 'note-event)
-\relative c' @{
- c2\f( f)
+\relative @{
+ c'2\f( f)
@}
@end example
@example
\pointAndClickTypes #'(note-event dynamic-event)
-\relative c' @{
- c2\f( f)
+\relative @{
+ c'2\f( f)
@}
@end example
@example
#(ly:set-option 'point-and-click '(note-event dynamic-event))
-\relative c' @{
- c2\f( f)
+\relative @{
+ c'2\f( f)
@}
@end example
example.ly
@end smallexample
-
@end itemize
* Other editors::
@end menu
+
@node Emacs mode
@unnumberedsubsec Emacs mode
filetype off
set runtimepath+=/usr/local/share/lilypond/current/vim/
filetype on
+syntax on
@end example
@noindent
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
@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.
+@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
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 (@option{-s} and @option{-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.
-
+@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
@item -e, --explicit-durations
Print explicit durations.
-@item -h,--help
+@item -h, --help
Show summary of usage.
@item -k, --key=@var{acc}[:@var{minor}]
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.
@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.
+file and is invoked from the command-line as follows;
-
-It is invoked from the command-line as follows,
@example
musicxml2ly [@var{option}]@dots{} @var{xml-file}
@end example
@item -a, --absolute
convert pitches in absolute mode.
-@item -h,--help
+@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 --loglevel=@var{loglevel}
-Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
-@code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}.
+Set the output verbosity to @var{loglevel}. Possible values are
+@code{NONE}, @code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and
+@code{DEBUG}.
@item --lxml
-use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
+use the lxml.etree Python package for XML-parsing; uses less memory and
+cpu time.
@item -m, --midi
activate midi-block.
-@item -nd --no-articulation-directions
+@item -nd, --no-articulation-directions
do not convert directions (@code{^}, @code{_} or @code{-}) for
articulations, dynamics, etc.
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 -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
+@item -r, --relative
convert pitches in relative mode (default).
-@item -v,--verbose
+@item -v, --verbose
be verbose.
@item --version
print version information.
-@item -z,--compressed
+@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.}
+@warning{This is not currently supported and may eventually be removed
+from future versions of LilyPond.}
@cindex ABC
-ABC is a fairly simple ASCII based format. It is described at the ABC site:
+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:
+@command{abc2ly} translates from ABC to LilyPond. It is invoked as
+follows:
@example
abc2ly [@var{option}]@dots{} @var{abc-file}
The following options are supported by @command{abc2ly}:
@table @code
-@item -b,--beams=None
+@item -b, --beams=None
preserve ABC's notion of beams
-@item -h,--help
+@item -h, --help
this help
-@item -o,--output=@var{file}
+@item -o, --output=@var{file}
set output filename to @var{file}.
-@item -s,--strict
+@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:
+source file. For example;
@example
%%LY voices \set autoBeaming = ##f
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.
@node Invoking etf2ly
@subsection Invoking @command{etf2ly}
-@warning{This program is not supported, and may be remove from
-future versions of LilyPond.}
+@warning{This is not currently supported and may eventually be removed
+from future versions of LilyPond.}
+@cindex Enigma Transport Format
@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.
+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.
+It is invoked from the command-line as follows;
@example
etf2ly [@var{option}]@dots{} @var{etf-file}
The following options are supported by @command{etf2ly}:
@table @code
-@item -h,--help
+@item -h, --help
this help
-@item -o,--output=@var{FILE}
+@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.
+confuse @command{etf2ly}. Sequences of grace notes are ended
+improperly.
@node Other formats
are listed in @rweb{Easier editing}.
-
@node LilyPond output in other programs
@section LilyPond output in other programs
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::
+* LuaTex::
+* OpenOffice and LibreOffice::
+* 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 LuaTex
+@subsection LuaTex
+@cindex LuaTex
+@cindex lyluatex
-@node Inserting LilyPond output into OpenOffice.org
-@unnumberedsubsec Inserting LilyPond output into OpenOffice.org
+As well as @code{lilypond-book} to integrate LilyPond output,
+there is an alternative program that can be used when using LuaTex
+called
+@uref{https://github.com/jperon/lyluatex/blob/master/README.en.md,lyluatex}.
+
+
+@node OpenOffice and LibreOffice
+@subsection OpenOffice and LibreOffic
@cindex OpenOffice.org
+@cindex LibreOffice.org
+@cindex OOoLilyPond
-LilyPond notation can be added to OpenOffice.org with
-@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
+LilyPond notation can be added to OpenOffice.org and LibreOffice with
+@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}, an
+OpenOffice.org extension that converts LilyPond files into images within
+OpenOffice.org documents. Although this is no longer being developed,
+it appears to still work with version 4.
-@node Inserting LilyPond output into other programs
-@unnumberedsubsec Inserting LilyPond output into other programs
+@node Other programs
+@subsection 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.
+Other programs that can handle @file{PNG}, @file{EPS}, or @file{PDF}
+formats should use @code{lilypond} instead of @code{lilypond-book}.
+Each LilyPond output file must be created and inserted separately.
+Consult the program's own documentation on how to insert files from
+other sources.
-To reduce the white space around your LilyPond score, use
-the following options
+To help reduce the white space around your LilyPond score, use the
+following options;
@example
\paper@{
scoreTitleMarkup = ##f
@}
-@{ c1 @}
+@var{@dots{} music @dots{}}
@end example
-To produce useful image files:
+@noindent
+To produce @file{EPS} images;
@example
-EPS
-
lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+@end example
-PNG
+@noindent
+To produce @file{PNG} images;
+@example
lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
+@end example
-A transparent PNG
+@noindent
+For transparent @file{PNG} images
-lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
- -dpixmap-format=pngalpha --png myfile.ly
-@end example
+@smallexample
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts -dpixmap-format=pngalpha --png myfile.ly
+@end smallexample
+
+@cindex fragments, music
+@cindex quoting, music fragments
+@cindex music fragments, quotin
+
+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 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.
-
+Some users have produced files that can be @code{\include}d with
+LilyPond to produce certain effects and those listed below are part of
+the LilyPond distribution. Also see @ruser{Working with input files}.
@menu
* MIDI articulation::
@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 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.
-
-
+@cindex MIDI
+@cindex Articulate project
+
+The @uref{http://www.nicta.com.au/articulate,Articulate} project is an
+attempt to enhance LilyPond's MIDI output and works by adjusting note
+lengths (that are not under slurs) according to the articulation
+markings attached to them. For example, a @q{staccato} halves the note
+value, @q{tenuto} gives a note its full duration and so on. See
+@ruser{Enhancing MIDI output}.
projects / lilypond.git / blobdiff