X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Fexternal.itely;h=659abd27ba934d002216b614cc92573bddb07db9;hb=8cce5dd067a8a2bab508f5abebc3955db8837bbf;hp=7c386ae733f802bb898d9944a068a5fbc2385fa0;hpb=82bc9ad690e201aaa55694f8b92261ae7338f56a;p=lilypond.git diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely index 7c386ae733..659abd27ba 100644 --- a/Documentation/usage/external.itely +++ b/Documentation/usage/external.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.16.0" +@c \version "2.19.21" @node External programs @chapter External programs @@ -26,11 +26,12 @@ LilyPond can interact with other programs in various ways. @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 -in the PDF viewer. This makes it easier to find input that causes -some error in the sheet music. +in the PDF viewer. This makes it easier to find input that causes some +error in the sheet music. @menu * Configuring the system for point and click:: @@ -38,13 +39,14 @@ some error in the sheet music. * Selective point-and-click:: @end menu + @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 a @q{URI helper} or a -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 @@ -87,7 +89,6 @@ emacsclient --no-wait +%(line)s:%(column)s %(file)s for @code{LYEDITOR} is equivalent to the standard emacsclient invocation. - @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 + @node Using Xpdf for point and click @unnumberedsubsubsec Using Xpdf + @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 + @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 -@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 -@end example +@end smallexample + +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. + @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 @@ -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 -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. + @node Extra configuration for Evince @unnumberedsubsubsec Extra configuration for Evince + @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: + @example # For Textedit links /usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper, @@ -200,16 +216,17 @@ 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. + @node Enabling point and click @unnumberedsubsec Enabling point and click @cindex file size, output Point and click functionality is enabled by default when creating -PDF files. +PDF or SVG files. 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 @@ -231,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 -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 @@ -251,8 +269,8 @@ Hard-coded in the @file{.ly} file: @example \pointAndClickTypes #'note-event -\relative c' @{ - c2\f( f) +\relative @{ + c'2\f( f) @} @end example @@ -260,8 +278,8 @@ or @example #(ly:set-option 'point-and-click 'note-event) -\relative c' @{ - c2\f( f) +\relative @{ + c'2\f( f) @} @end example @@ -282,8 +300,8 @@ Hard-coded in the @file{.ly} file: @example \pointAndClickTypes #'(note-event dynamic-event) -\relative c' @{ - c2\f( f) +\relative @{ + c'2\f( f) @} @end example @@ -291,8 +309,8 @@ or @example #(ly:set-option 'point-and-click '(note-event dynamic-event)) -\relative c' @{ - c2\f( f) +\relative @{ + c'2\f( f) @} @end example @@ -305,7 +323,6 @@ lilypond \ example.ly @end smallexample - @end itemize @@ -327,6 +344,7 @@ There is support for different text editors for LilyPond. * Other editors:: @end menu + @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}. - @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 - @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 @@ -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) -@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, + @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 - @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. @@ -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} -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 @@ -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} -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 -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. @@ -556,9 +570,9 @@ 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. +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). @@ -577,18 +591,20 @@ input file is a zip-compressed MusicXML file. @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 -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 -@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} @@ -610,7 +626,7 @@ 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 @@ -628,9 +644,7 @@ Similarly, will cause the text following the @q{slyrics} keyword to be inserted into the current line of lyrics. - @knownissues - 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} -@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 -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} @@ -678,11 +693,10 @@ set output filename to @var{FILE} version information @end table - @knownissues - 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 @@ -695,7 +709,6 @@ but some external tools can also generate LilyPond files. These are listed in @rweb{Easier editing}. - @node LilyPond output in other programs @section LilyPond output in other programs @@ -703,39 +716,49 @@ This section shows methods to integrate text and music, different than the automated method with @command{lilypond-book}. @menu -* Many quotes from a large score:: -* Inserting LilyPond output into OpenOffice and LibreOffice:: -* Inserting LilyPond output into other programs:: +* LuaTex:: +* OpenOffice and LibreOffice:: +* Other programs:: @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 +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 Inserting LilyPond output into OpenOffice and LibreOffice -@unnumberedsubsec Inserting LilyPond output into OpenOffice and LibreOffice + +@node OpenOffice and LibreOffice +@subsection OpenOffice and LibreOffice @cindex OpenOffice.org @cindex LibreOffice.org +@cindex OOoLilyPond 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 -@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@{ @@ -747,35 +770,44 @@ the following options scoreTitleMarkup = ##f @} -@{ c1 @} +@var{@dots{} music @dots{}} @end example -To produce useful image files: +@noindent +To produce @file{EPS} images; @example -EPS - 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 +@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, quoting + +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 -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:: @@ -785,27 +817,12 @@ and @code{\include} them manually. @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}.