news: RC 2.15.39 withdrawn

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

diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely
index b6b4ae5c636aae556575636ac6e2fc8bfd1b10be..1668953b1ffad9690aa3e7600abf05b55de61c89 100644 (file)
--- a/Documentation/usage/external.itely
+++ b/Documentation/usage/external.itely
@@ -4,16 +4,16 @@
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
     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.
+    version that you are working on.  For details, see the Contributors'
+    Guide, node Updating translation committishes..

 @end ignore
 
 @end ignore
 

-@c \version "2.12.0"
+@c \version "2.14.0"

 
 @node External programs
 @chapter External programs
 
 
 @node External programs
 @chapter External programs
 

-FIXME: blah blah
-
+LilyPond can interact with other programs in various ways.

 
 @menu
 * Point and click::
 
 @menu
 * Point and click::


@@ -27,6 +27,17 @@ FIXME: blah blah
 @node Point and click
 @section Point and click
 
 @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
 @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
 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"
 
 @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.}
 @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 Text editor support
 @section Text editor support
 


@@ -160,39 +248,21 @@ your @var{load-path} by appending the following line (as modified) to your
 @node Vim mode
 @unnumberedsubsec Vim mode
 
 @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}
+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:

 
 @example
 
 @example

-set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
+filetype off
+set runtimepath+=/usr/local/share/lilypond/current/vim/
+filetype on

 @end example
 
 @noindent
 @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
+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}.

 
 
 @node Other editors
 
 
 @node Other editors


@@ -201,7 +271,7 @@ set runtimepath+=/usr/share/vim/vim72/
 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
 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}.
+editors are listed in @rweb{Easier editing}.

 
 
 @node Converting from other formats
 
 
 @node Converting from other formats


@@ -257,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.
 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.
 @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.


@@ -331,7 +401,7 @@ to a single duration and add phrase markings or pedal indicators.
 for representing music notation.
 
 @command{musicxml2ly} extracts the notes, articulations, score structure,
 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.
 
 
 file.  It is invoked from the command-line.
 
 


@@ -357,8 +427,11 @@ convert pitches in absolute mode.
 print usage and option summary.
 
 @item -l, --language=LANG
 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.
+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 --lxml
 use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.


@@ -508,7 +581,7 @@ confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.
 
 LilyPond itself does not come with support for any other formats,
 but some external tools can also generate LilyPond files.  These
 
 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}.
+are listed in @rweb{Easier editing}.

 
 
 
 
 
 


@@ -565,20 +638,32 @@ the following options
 @{ c1 @}
 @end example
 
 @{ c1 @}
 @end example
 

-To produce a useful @file{EPS} file, use
+To produce useful image files:

 
 @example
 
 @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
 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
 
 
 @node Independent includes
 @section Independent @code{include}s
 
 @end example
 
 
 @node Independent includes
 @section Independent @code{include}s
 

-FIXME: blah blah
+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.
+

 
 @menu
 * MIDI articulation::
 
 @menu
 * MIDI articulation::


@@ -588,6 +673,27 @@ FIXME: blah blah
 @node MIDI articulation
 @subsection MIDI articulation
 
 @node MIDI articulation
 @subsection MIDI articulation
 

-stub for info about Dr. Peter Chubb's @file{articulate.ly}
+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 he 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.