Imported Upstream version 2.16.0

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

diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely
index 01e637bdc9726ccdc5fbe64caf6191a5b4060aeb..2eda9533745a46e4d91daa4132d2d9d7c305f222 100644 (file)
--- a/Documentation/usage/external.itely
+++ b/Documentation/usage/external.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.14.0"
+@c \version "2.16.0"
 
 @node External programs
 @chapter External programs
@@ -27,6 +27,17 @@ LilyPond can interact with other programs in various ways.
 @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
@@ -42,8 +53,8 @@ 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"
@@ -114,6 +125,83 @@ lilypond -dno-point-and-click file.ly
 @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
 
@@ -239,7 +327,7 @@ 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)
+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.
@@ -341,10 +429,17 @@ 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.
 
@@ -546,13 +641,21 @@ the following options
 @{ 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
 
 
@@ -579,7 +682,7 @@ 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
+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