X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Fexternal.itely;h=673a742cb02d1031bc4e816b650e4519519dfa74;hb=b451acd8959a79b3b522b59ca2e03005bb3fe9cc;hp=249e467a47eb7b1ac17c5cadf4c4799b05d7a5b9;hpb=eed7b5f33c8e40860924c414b0feae8e0393f39d;p=lilypond.git diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely index 249e467a47..673a742cb0 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.14.0" +@c \version "2.19.21" @node External programs @chapter External programs @@ -30,25 +30,28 @@ LilyPond can interact with other programs in various ways. @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. -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. +@menu +* Configuring the system for point and click:: +* Enabling point and click:: +* 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 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. -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.} - -@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 @@ -86,12 +89,144 @@ 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:: +* 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 +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 -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 @@ -113,7 +248,84 @@ 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 + +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'2\f( f) +@} +@end example + +or + +@example +#(ly:set-option 'point-and-click 'note-event) +\relative @{ + c'2\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'2\f( f) +@} +@end example + +or + +@example +#(ly:set-option 'point-and-click '(note-event dynamic-event)) +\relative @{ + c'2\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 @@ -132,6 +344,7 @@ There is support for different text editors for LilyPond. * Other editors:: @end menu + @node Emacs mode @unnumberedsubsec Emacs mode @@ -169,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 +syntax on @end example @noindent @@ -201,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 @@ -216,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 @@ -239,13 +451,13 @@ 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) -@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. - +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. It is invoked from the command-line as follows, + @example midi2ly [@var{option}]@dots{} @var{midi-file} @end example @@ -266,7 +478,7 @@ Quantize note durations on @var{DUR}. @item -e, --explicit-durations Print explicit durations. -@item -h,--help +@item -h, --help Show summary of usage. @item -k, --key=@var{acc}[:@var{minor}] @@ -296,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. @@ -314,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 @@ -335,16 +543,25 @@ The following options are supported by @command{musicxml2ly}: @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} +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. -@item --nd --no-articulation-directions +@item -nd, --no-articulation-directions do not convert directions (@code{^}, @code{_} or @code{-}) for articulations, dynamics, etc. @@ -352,21 +569,21 @@ articulations, dynamics, etc. 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). -@item -v,--verbose +@item -v, --verbose be verbose. @item --version print version information. -@item -z,--compressed +@item -z, --compressed input file is a zip-compressed MusicXML file. @end table @@ -374,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} @@ -394,20 +613,20 @@ abc2ly [@var{option}]@dots{} @var{abc-file} The following options are supported by @command{abc2ly}: @table @code -@item -b,--beams=None +@item -b, --beams=None preserve ABC's notion of beams -@item -h,--help +@item -h, --help this help -@item -o,--output=@var{file} +@item -o, --output=@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 -source file. If you say: +source file. For example; @example %%LY voices \set autoBeaming = ##f @@ -425,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. @@ -442,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} @@ -467,19 +685,18 @@ more information about this. The following options are supported by @command{etf2ly}: @table @code -@item -h,--help +@item -h, --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 - @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 @@ -492,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 @@ -500,38 +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.org:: -* 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.org -@unnumberedsubsec Inserting LilyPond output into OpenOffice.org +@node OpenOffice and LibreOffice +@subsection OpenOffice and LibreOffic @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@{ @@ -543,36 +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 - -A transparent PNG @end example +@noindent +For transparent @file{PNG} images + @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 -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:: @@ -582,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 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. - - +@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}.