Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@c \version "2.19.21"
@node External programs
@chapter External programs
@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.
+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
-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.
+@node Configuring the system for point and click
+@subsection Configuring the system
+
+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}@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
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
+@example
+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 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 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
+
+For some interactive applications, it may be desirable to only
+include certain point-and-click items. For example, if somebody
+wanted to create an application which played audio or video
+starting from a particular note, it would be awkward if clicking
+on the note produced the point-and-click location for an
+accidental or slur which occurred over that note.
+
+This may be controlled by indicating which events to include:
+
+@itemize
+@item
+Hard-coded in the @file{.ly} file:
+
+@example
+\pointAndClickTypes #'note-event
+\relative @{
+ c'2\f( f)
+@}
+@end example
+
+or
+
+@example
+#(ly:set-option 'point-and-click 'note-event)
+\relative @{
+ c'2\f( f)
+@}
+@end example
+
+@item
+Command-line:
+
+@example
+lilypond -dpoint-and-click=note-event example.ly
+@end example
+
+@end itemize
+
+Multiple events can be included:
+
+@itemize
+@item
+Hard-coded in the @file{.ly} file:
+
+@example
+\pointAndClickTypes #'(note-event dynamic-event)
+\relative @{
+ c'2\f( f)
+@}
+@end example
+
+or
+
+@example
+#(ly:set-option 'point-and-click '(note-event dynamic-event))
+\relative @{
+ c'2\f( f)
+@}
+@end example
+
+@item
+Command-line:
+
+@smallexample
+lilypond \
+ -e"(ly:set-option 'point-and-click '(note-event dynamic-event))" \
+ example.ly
+@end smallexample
+
+
+@end itemize
+
+
@node Text editor support
@section Text editor support
filetype off
set runtimepath+=/usr/local/share/lilypond/current/vim/
filetype on
+syntax on
@end example
@noindent
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)
+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.
@item -e, --explicit-durations
Print explicit durations.
-@item -h,--help
+@item -h, --help
Show summary of usage.
@item -k, --key=@var{acc}[:@var{minor}]
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
+lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly}
file. It is invoked from the command-line.
@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}.
+
@item --lxml
use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
-@item --nd --no-articulation-directions
+@item -m, --midi
+activate midi-block.
+
+@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}
+@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
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.
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
@menu
* Many quotes from a large score::
-* Inserting LilyPond output into OpenOffice.org::
+* Inserting LilyPond output into OpenOffice and LibreOffice::
* Inserting LilyPond output into other programs::
@end menu
the clip systems feature, see @ruser{Extracting fragments of music}.
-@node Inserting LilyPond output into OpenOffice.org
-@unnumberedsubsec Inserting LilyPond output into OpenOffice.org
+@node Inserting LilyPond output into OpenOffice and LibreOffice
+@unnumberedsubsec Inserting LilyPond output into OpenOffice and LibreOffice
@cindex OpenOffice.org
+@cindex LibreOffice.org
-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
@{ c1 @}
@end example
-To produce a useful @file{EPS} file, use
+To produce useful image files:
@example
-lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+EPS
+
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+
+PNG
-@file{PNG}:
lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
+
+A transparent PNG
+
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
+ -dpixmap-format=pngalpha --png myfile.ly
@end example
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
+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
projects / lilypond.git / blobdiff