X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Fexternal.itely;h=554bde870a8cc7f54766555479f0ce21bf01dcc4;hb=0cdc6bf50fb78281d7a0e6a339514b87e8d9dec3;hp=3b4ff955b9b8ecbce4f97aff73c04f09772971e2;hpb=c39d188d28fdc84cef8cbaea7b8d6e2fb718c30f;p=lilypond.git diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely index 3b4ff955b9..554bde870a 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,6 +26,7 @@ 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 @@ -38,6 +39,7 @@ error in the sheet music. * Selective point-and-click:: @end menu + @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. - @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,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. + @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.} + @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 @@ -716,13 +729,17 @@ the clip systems feature, see @ruser{Extracting fragments of music}. @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 -@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 @@ -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. -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@{ @@ -771,11 +788,9 @@ lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \ @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 +800,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}.