X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Fexternal.itely;h=3b4ff955b9b8ecbce4f97aff73c04f09772971e2;hb=e7aa6c445f463844dbaa52d38ea4aac2882b5601;hp=1668953b1ffad9690aa3e7600abf05b55de61c89;hpb=d61cf3bbdb1c6670a127ba3baddf2f04d3e34fd3;p=lilypond.git diff --git a/Documentation/usage/external.itely b/Documentation/usage/external.itely index 1668953b1f..3b4ff955b9 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.16.0" @node External programs @chapter External programs @@ -26,40 +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 adds links to pdf documents for certain music -elements. +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 +* Configuring the system for point and click:: * Enabling point and click:: * Selective point-and-click:: @end menu -@node Enabling point and click -@unnumberedsubsec Enabling point and click +@node Configuring the system for point and click +@subsection Configuring the system -@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. - -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. -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 @@ -98,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 @@ -124,7 +231,7 @@ 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 @@ -257,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 @@ -354,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}] @@ -423,7 +531,7 @@ 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 @@ -436,7 +544,10 @@ Set the output verbosity to @var{loglevel}. Possible values are @code{NONE}, @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. @@ -444,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 @@ -486,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. @@ -559,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 @@ -593,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 @@ -604,12 +715,13 @@ 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 +LilyPond notation can be added to OpenOffice.org and LibreOffice with @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}. @@ -679,7 +791,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