Doc: External.itely - Add lyluatex

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

diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely
index eba0be3f1b69e3b61cadc3f35410ead7f498fa17..673a742cb02d1031bc4e816b650e4519519dfa74 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.14.0"
+@c \version "2.19.21"

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


@@ -27,39 +27,31 @@ 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
 

-Point and click adds links to pdf documents for certain music
-elements.
+@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.

 
 @menu
 
 @menu

+* Configuring the system for point and click::

 * Enabling point and click::
 * Selective point-and-click::
 @end 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
-in the PDF viewer.  This makes it easier to find input that causes
-some error in the sheet music.
+@node Configuring the system for point and click
+@subsection Configuring the system

 
 

-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.
+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.
 
 
 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}.  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
 program.  It will invoke an editor for the special @code{textedit}
 URIs, and run a web browser for others.  It tests the environment
 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


@@ -97,12 +89,144 @@ 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::
+* 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;
+
+@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
+@end smallexample
+
+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
 
 @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
 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
 
 @example
 \pointAndClickOff


@@ -124,7 +248,8 @@ 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
 
 @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
 
 @node Selective point-and-click
 @unnumberedsubsec Selective point-and-click


@@ -144,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
 


@@ -153,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
 


@@ -175,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
 


@@ -184,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
 


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

-

 @end itemize
 
 
 @end itemize
 
 


@@ -220,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
 


@@ -257,6 +382,7 @@ your @file{$HOME/.vimrc} to contain these three lines, in order:
 filetype off
 set runtimepath+=/usr/local/share/lilypond/current/vim/
 filetype on
 filetype off
 set runtimepath+=/usr/local/share/lilypond/current/vim/
 filetype on

+syntax on

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -289,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


@@ -304,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


@@ -328,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


@@ -354,7 +478,7 @@ Quantize note durations on @var{DUR}.
 @item -e, --explicit-durations
 Print explicit durations.
 
 @item -e, --explicit-durations
 Print explicit durations.
 

-@item -h,--help
+@item -h, --help

 Show summary of usage.
 
 @item -k, --key=@var{acc}[:@var{minor}]
 Show summary of usage.
 
 @item -k, --key=@var{acc}[:@var{minor}]


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


@@ -402,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


@@ -423,23 +543,25 @@ The following options are supported by @command{musicxml2ly}:
 @item -a, --absolute
 convert pitches in absolute mode.
 
 @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}
 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}.
+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.
 

-@item -nd --no-articulation-directions
+@item -nd, --no-articulation-directions

 do not convert directions (@code{^}, @code{_} or @code{-}) for
 articulations, dynamics, etc.
 
 do not convert directions (@code{^}, @code{_} or @code{-}) for
 articulations, dynamics, etc.
 


@@ -447,21 +569,21 @@ articulations, dynamics, etc.
 do not convert beaming information, use LilyPond's automatic
 beaming instead.
 
 do not convert beaming information, use LilyPond's automatic
 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.
+@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).
 
 convert pitches in relative mode (default).
 

-@item -v,--verbose
+@item -v, --verbose

 be verbose.
 
 @item --version
 print version information.
 
 be verbose.
 
 @item --version
 print version information.
 

-@item -z,--compressed
+@item -z, --compressed

 input file is a zip-compressed MusicXML file.
 @end table
 
 input file is a zip-compressed MusicXML file.
 @end table
 


@@ -469,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}


@@ -489,20 +613,20 @@ abc2ly [@var{option}]@dots{} @var{abc-file}
 The following options are supported by @command{abc2ly}:
 
 @table @code
 The following options are supported by @command{abc2ly}:
 
 @table @code

-@item -b,--beams=None
+@item -b, --beams=None

 preserve ABC's notion of beams
 preserve ABC's notion of beams

-@item -h,--help
+@item -h, --help

 this help
 this help

-@item -o,--output=@var{file}
+@item -o, --output=@var{file}

 set output filename to @var{file}.
 set output filename to @var{file}.

-@item -s,--strict
+@item -s, --strict

 be strict about success
 @item --version
 print version information.
 @end table
 
 There is a rudimentary facility for adding LilyPond code to the ABC
 be strict about success
 @item --version
 print version information.
 @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


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


@@ -537,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}


@@ -562,19 +685,18 @@ more information about this.
 The following options are supported by @command{etf2ly}:
 
 @table @code
 The following options are supported by @command{etf2ly}:
 
 @table @code

-@item -h,--help
+@item -h, --help

 this help
 this help

-@item -o,--output=@var{FILE}
+@item -o, --output=@var{FILE}

 set output filename to @var{FILE}
 @item --version
 version information
 @end table
 
 set output filename to @var{FILE}
 @item --version
 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


@@ -587,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
 


@@ -595,38 +716,49 @@ This section shows methods to integrate text and music, different than
 the automated method with @command{lilypond-book}.
 
 @menu
 the automated method with @command{lilypond-book}.
 
 @menu

-* Many quotes from a large score::
-* Inserting LilyPond output into OpenOffice.org::
-* Inserting LilyPond output into other programs::
+* LuaTex::
+* OpenOffice and LibreOffice::
+* Other programs::

 @end menu
 
 @end menu
 

-@node Many quotes from a large score
-@unnumberedsubsec Many quotes from a large score

 
 

-If you need to quote many fragments from a large score, you can also use
-the clip systems feature, see @ruser{Extracting fragments of music}.
+@node LuaTex
+@subsection LuaTex

 
 

+@cindex LuaTex
+@cindex lyluatex

 
 

-@node Inserting LilyPond output into OpenOffice.org
-@unnumberedsubsec Inserting LilyPond output into OpenOffice.org
+As well as @code{lilypond-book} to integrate LilyPond output,
+there is an alternative program that can be used when using LuaTex
+called
+@uref{https://github.com/jperon/lyluatex/blob/master/README.en.md,lyluatex}.
+
+
+@node OpenOffice and LibreOffice
+@subsection OpenOffice and LibreOffic

 
 @cindex OpenOffice.org
 
 @cindex OpenOffice.org

+@cindex LibreOffice.org
+@cindex OOoLilyPond

 
 

-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
-@unnumberedsubsec Inserting LilyPond output into other programs
+@node Other programs
+@subsection Other programs

 
 

-To insert LilyPond output in other programs, use @code{lilypond}
-instead of @code{lilypond-book}.  Each example must be created
-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.
+Other programs that can handle @file{PNG}, @file{EPS}, or @file{PDF}
+formats should use @code{lilypond} instead of @code{lilypond-book}.
+Each LilyPond output file must be created and inserted separately.
+Consult the program's own documentation on how to insert files from
+other sources.

 
 

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

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


@@ -638,35 +770,44 @@ the following options
   scoreTitleMarkup = ##f
 @}
 
   scoreTitleMarkup = ##f
 @}
 

-@{ c1 @}
+@var{@dots{} music @dots{}}

 @end example
 
 @end example
 

-To produce useful image files:
+@noindent
+To produce @file{EPS} images;

 
 @example
 
 @example

-EPS
-

 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly

+@end example

 
 

-PNG
+@noindent
+To produce @file{PNG} images;

 
 

+@example

 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

+@end example

 
 

-A transparent PNG
+@noindent
+For transparent @file{PNG} images

 
 

-lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \
-  -dpixmap-format=pngalpha --png myfile.ly
-@end example
+@smallexample
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts -dpixmap-format=pngalpha --png myfile.ly
+@end smallexample
+
+@cindex fragments, music
+@cindex quoting, music fragments
+@cindex music fragments, quotin
+
+If you need to quote many fragments from a large score, you can also use
+the clip systems feature, see @ruser{Extracting fragments of music}.

 
 
 @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::


@@ -676,27 +817,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}.