Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@c \version "2.14.0"
@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.
+
+@menu
+* 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
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
+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.}
+@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
+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,
@end example
@noindent
-in a @file{@/.ly} file. Point and click may be explicitly enabled with
+in a @file{.ly} file. Point and click may be explicitly enabled with
@example
\pointAndClickOn
@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 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' @{
+ c2\f( f)
+@}
+@end example
+
+or
+
+@example
+#(ly:set-option 'point-and-click 'note-event)
+\relative c' @{
+ c2\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' @{
+ c2\f( f)
+@}
+@end example
+
+or
+
+@example
+#(ly:set-option 'point-and-click '(note-event dynamic-event))
+\relative c' @{
+ c2\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
@node Emacs mode
@unnumberedsubsec Emacs mode
-Emacs has a @file{lilypond@/-mode}, which provides keyword
+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
+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}.
+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
+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}
+@file{~/.emacs}
@c any reason we do not advise: (push "~/site-lisp" load-path)
@example
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:
+your @file{$HOME/.vimrc} to contain these three lines, in order:
@example
filetype off
@end example
@noindent
-If LilyPond is not installed in the @file{/@/usr/@/local/@/} directory,
+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}.
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
+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.
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}
+lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly}
file. It is invoked from the command-line.
@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.
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
+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
@{ 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