Doc: Usage - Update section on articulate.ly

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

diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely
index 3b4ff955b9b8ecbce4f97aff73c04f09772971e2..554bde870a8cc7f54766555479f0ce21bf01dcc4 100644 (file)
--- a/Documentation/usage/external.itely
+++ b/Documentation/usage/external.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.16.0"
+@c \version "2.19.21"

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


@@ -26,6 +26,7 @@ LilyPond can interact with other programs in various ways.
 
 @node Point and click
 @section Point and click
 
 @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
 @cindex point and click
 
 Point and click lets you find notes in the input by clicking on them


@@ -38,6 +39,7 @@ error in the sheet music.
 * Selective point-and-click::
 @end menu
 
 * Selective point-and-click::
 @end menu
 

+

 @node Configuring the system for point and click
 @subsection Configuring the system
 
 @node Configuring the system for point and click
 @subsection Configuring the system
 


@@ -87,7 +89,6 @@ emacsclient --no-wait +%(line)s:%(column)s %(file)s
 for @code{LYEDITOR} is equivalent to the standard emacsclient
 invocation.
 
 for @code{LYEDITOR} is equivalent to the standard emacsclient
 invocation.
 

-

 @menu
 * Using Xpdf for point and click::
 * Using GNOME 2 for point and click::
 @menu
 * Using Xpdf for point and click::
 * Using GNOME 2 for point and click::


@@ -95,8 +96,10 @@ invocation.
 * Extra configuration for Evince::
 @end menu
 
 * Extra configuration for Evince::
 @end menu
 

+

 @node Using Xpdf for point and click
 @unnumberedsubsubsec Using Xpdf
 @node Using Xpdf for point and click
 @unnumberedsubsubsec Using Xpdf

+

 @cindex Xpdf
 
 For Xpdf on UNIX, the following should be present in
 @cindex Xpdf
 
 For Xpdf on UNIX, the following should be present in


@@ -114,38 +117,47 @@ 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
 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
 @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.
 
 @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
 @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
+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
 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
+@end smallexample
+
+After that invocation;

 
 

-After that invocation,

 @example
 gnome-open textedit:///etc/issue:1:0:0
 @end example
 @example
 gnome-open textedit:///etc/issue:1:0:0
 @end example

+

 @noindent
 should call @file{lilypond-invoke-editor} for opening files.
 
 @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}
 @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
+that is called @file{lilypond-invoke-editor.desktop} and has the
+contents;
+

 @example
 [Desktop Entry]
 Version=1.0
 @example
 [Desktop Entry]
 Version=1.0


@@ -165,15 +177,18 @@ xdg-desktop-menu install ./lilypond-invoke-editor.desktop
 xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit
 @end example
 
 xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit
 @end example
 

-After that invocation,
+After that invocation;
+

 @example
 gnome-open textedit:///etc/issue:1:0:0
 @end example
 @noindent
 should call @file{lilypond-invoke-editor} for opening files.
 
 @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
 @node Extra configuration for Evince
 @unnumberedsubsubsec Extra configuration for Evince

+

 @cindex Evince
 
 If @code{gnome-open} works, but Evince still refuses to open point
 @cindex Evince
 
 If @code{gnome-open} works, but Evince still refuses to open point


@@ -184,6 +199,7 @@ 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:
 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,
 @example
 # For Textedit links
 /usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper,


@@ -200,6 +216,7 @@ sudo apparmor_parser -r -T -W /etc/apparmor.d/usr.bin.evince
 Now Evince should be able to open point and click links.  It is
 likely that similar configurations will work for other viewers.
 
 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
 @node Enabling point and click
 @unnumberedsubsec Enabling point and click
 @cindex file size, output


@@ -233,6 +250,7 @@ lilypond -dno-point-and-click file.ly
 files to be distributed to avoid including path information about
 your computer in the PDF file, which can pose a security risk.}
 
 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
 
 @node Selective point-and-click
 @unnumberedsubsec Selective point-and-click
 


@@ -251,8 +269,8 @@ Hard-coded in the @file{.ly} file:
 
 @example
 \pointAndClickTypes #'note-event
 
 @example
 \pointAndClickTypes #'note-event

-\relative c' @{
-  c2\f( f)
+\relative @{
+  c'2\f( f)

 @}
 @end example
 
 @}
 @end example
 


@@ -260,8 +278,8 @@ or
 
 @example
 #(ly:set-option 'point-and-click 'note-event)
 
 @example
 #(ly:set-option 'point-and-click 'note-event)

-\relative c' @{
-  c2\f( f)
+\relative @{
+  c'2\f( f)

 @}
 @end example
 
 @}
 @end example
 


@@ -282,8 +300,8 @@ Hard-coded in the @file{.ly} file:
 
 @example
 \pointAndClickTypes #'(note-event dynamic-event)
 
 @example
 \pointAndClickTypes #'(note-event dynamic-event)

-\relative c' @{
-  c2\f( f)
+\relative @{
+  c'2\f( f)

 @}
 @end example
 
 @}
 @end example
 


@@ -291,8 +309,8 @@ or
 
 @example
 #(ly:set-option 'point-and-click '(note-event dynamic-event))
 
 @example
 #(ly:set-option 'point-and-click '(note-event dynamic-event))

-\relative c' @{
-  c2\f( f)
+\relative @{
+  c'2\f( f)

 @}
 @end example
 
 @}
 @end example
 


@@ -305,7 +323,6 @@ lilypond \
   example.ly
 @end smallexample
 
   example.ly
 @end smallexample
 

-

 @end itemize
 
 
 @end itemize
 
 


@@ -327,6 +344,7 @@ There is support for different text editors for LilyPond.
 * Other editors::
 @end menu
 
 * Other editors::
 @end menu
 

+

 @node Emacs mode
 @unnumberedsubsec Emacs mode
 
 @node Emacs mode
 @unnumberedsubsec Emacs mode
 


@@ -397,7 +415,6 @@ information.  If you have MacOS 10.3 or 10.4 and you have trouble
 running some of these scripts, e.g. @code{convert-ly}, see
 @rweb{MacOS X}.
 
 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
 @knownissues
 We unfortunately do not have the resources to maintain these
 programs; please consider them @qq{as-is}.  Patches are appreciated, but


@@ -412,14 +429,13 @@ bug reports will almost certainly not be resolved.
 @end menu
 
 
 @end menu
 
 

-

 @node Invoking midi2ly
 @subsection Invoking @command{midi2ly}
 
 @cindex MIDI
 
 @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
 
 MIDI (Music Instrument Digital Interface) is a standard for digital
 instruments: it specifies cabling, a serial protocol and a file


@@ -436,12 +452,12 @@ 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 (@option{-s} and @option{-d} options)
 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,
 
 It is invoked from the command-line as follows,

+

 @example
 midi2ly [@var{option}]@dots{} @var{midi-file}
 @end example
 @example
 midi2ly [@var{option}]@dots{} @var{midi-file}
 @end example


@@ -492,9 +508,7 @@ Show warranty and copyright.
 Treat every text as a lyric.
 @end table
 
 Treat every text as a lyric.
 @end table
 

-

 @knownissues
 @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.
 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.


@@ -510,10 +524,8 @@ 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}
 
 @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
 @example
 musicxml2ly [@var{option}]@dots{} @var{xml-file}
 @end example


@@ -538,11 +550,13 @@ print usage and option summary.
 use LANG for pitch names, e.g. 'deutsch' for note names in German.
 
 @item --loglevel=@var{loglevel}
 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
 
 @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 -m, --midi
 activate midi-block.


@@ -556,9 +570,9 @@ do not convert beaming information, use LilyPond's automatic
 beaming instead.
 
 @item -o, --output=@var{file}
 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.
+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
 convert pitches in relative mode (default).
 
 @item -r, --relative
 convert pitches in relative mode (default).


@@ -577,18 +591,20 @@ input file is a zip-compressed MusicXML file.
 @node Invoking abc2ly
 @subsection Invoking @code{abc2ly}
 
 @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
 
 
 @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
 
 
 @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}
 
 @example
 abc2ly [@var{option}]@dots{} @var{abc-file}


@@ -610,7 +626,7 @@ print version information.
 @end table
 
 There is a rudimentary facility for adding LilyPond code to the ABC
 @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
 
 @example
 %%LY voices \set autoBeaming = ##f


@@ -628,9 +644,7 @@ Similarly,
 will cause the text following the @q{slyrics} keyword to be inserted
 into the current line of lyrics.
 
 will cause the text following the @q{slyrics} keyword to be inserted
 into the current line of lyrics.
 

-

 @knownissues
 @knownissues

-

 The ABC standard is not very @q{standard}.  For extended features
 (e.g., polyphonic music) different conventions exist.
 
 The ABC standard is not very @q{standard}.  For extended features
 (e.g., polyphonic music) different conventions exist.
 


@@ -645,19 +659,20 @@ ABC synchronizes words and notes at the beginning of a line;
 @node Invoking etf2ly
 @subsection Invoking @command{etf2ly}
 
 @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
 @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}
 
 @example
 etf2ly [@var{option}]@dots{} @var{etf-file}


@@ -678,11 +693,10 @@ set output filename to @var{FILE}
 version information
 @end table
 
 version information
 @end table
 

-

 @knownissues
 @knownissues

-

 The list of articulation scripts is incomplete.  Empty measures
 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
 
 
 @node Other formats


@@ -695,7 +709,6 @@ but some external tools can also generate LilyPond files.  These
 are listed in @rweb{Easier editing}.
 
 
 are listed in @rweb{Easier editing}.
 
 

-

 @node LilyPond output in other programs
 @section LilyPond output in other programs
 
 @node LilyPond output in other programs
 @section LilyPond output in other programs
 


@@ -716,13 +729,17 @@ the clip systems feature, see @ruser{Extracting fragments of music}.
 
 
 @node Inserting LilyPond output into OpenOffice and LibreOffice
 
 
 @node Inserting LilyPond output into OpenOffice and LibreOffice

-@unnumberedsubsec 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 and LibreOffice with
 
 @cindex OpenOffice.org
 @cindex LibreOffice.org
 
 LilyPond notation can be added to OpenOffice.org and LibreOffice with

-@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
+@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
 
 
 @node Inserting LilyPond output into other programs


@@ -734,8 +751,8 @@ 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.
 
 that program.  Most programs will be able to insert LilyPond output in
 @file{PNG}, @file{EPS}, or @file{PDF} formats.
 

-To reduce the white space around your LilyPond score, use
-the following options
+To reduce the white space around your LilyPond score, use the following
+options;

 
 @example
 \paper@{
 
 @example
 \paper@{


@@ -771,11 +788,9 @@ lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
 @node Independent includes
 @section Independent @code{include}s
 
 @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::
 
 @menu
 * MIDI articulation::


@@ -785,27 +800,12 @@ and @code{\include} them manually.
 @node MIDI articulation
 @subsection 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}.