X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Fexternal.itely;h=c3cb2e5fe45a549dea43e12b9c00abfa68796d6c;hb=7d0360675a878609af94d723957eb2def24c7049;hp=95f7e86481f51c58c25f98f4c5fc6ecdabcb1edf;hpb=be33069c51a83bcb8579ec37e2527527a316a4a6;p=lilypond.git diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely index 95f7e86481..c3cb2e5fe4 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.13.36" +@c \version "2.19.21" @node External programs @chapter External programs @@ -26,29 +26,30 @@ 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:: +* Enabling point and click:: +* Selective point-and-click:: +@end menu -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. +@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 @@ -87,11 +88,128 @@ 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 +@example +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 + +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 +231,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 @@ -169,6 +364,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 @@ -239,7 +435,7 @@ 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) +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. @@ -266,7 +462,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}] @@ -313,7 +509,7 @@ to a single duration and add phrase markings or pedal indicators. for representing music notation. @command{musicxml2ly} extracts the notes, articulations, score structure, -lyrics, etc. from part-wise MusicXML files, and writes them to a .ly +lyrics, etc. from part-wise MusicXML files, and writes them to a @file{.ly} file. It is invoked from the command-line. @@ -335,16 +531,23 @@ 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. -@item --nd --no-articulation-directions +@item -m, --midi +activate midi-block. + +@item -nd, --no-articulation-directions do not convert directions (@code{^}, @code{_} or @code{-}) for articulations, dynamics, etc. @@ -352,21 +555,21 @@ articulations, dynamics, etc. do not convert beaming information, use LilyPond's automatic beaming instead. -@item -o,--output=@var{file} +@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 @@ -394,13 +597,13 @@ 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. @@ -467,9 +670,9 @@ 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 @@ -501,7 +704,7 @@ the automated method with @command{lilypond-book}. @menu * Many quotes from a large score:: -* Inserting LilyPond output into OpenOffice.org:: +* Inserting LilyPond output into OpenOffice and LibreOffice:: * Inserting LilyPond output into other programs:: @end menu @@ -512,13 +715,17 @@ 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 Inserting LilyPond output into OpenOffice.org -@unnumberedsubsec Inserting LilyPond output into OpenOffice.org +@node 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 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 @@ -546,13 +753,21 @@ the following options @{ c1 @} @end example -To produce a useful @file{EPS} file, use +To produce useful image files: @example -lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly +EPS + +lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly + +PNG -@file{PNG}: lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly + +A transparent PNG + +lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts \ + -dpixmap-format=pngalpha --png myfile.ly @end example @@ -579,7 +794,7 @@ 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 +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