4.1.1 Configuring the system

When this functionality is active, LilyPond adds hyperlinks to PDF and SVG files. These hyperlinks are sent to a ‘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 ‘lilypond-invoke-editor’ script supplied with LilyPond.

The program ‘lilypond-invoke-editor’ is a small helper program. It will invoke an editor for the special textedit URIs, and run a web browser for others. It tests the environment variable EDITOR for the following patterns,

emacs

this will invoke

emacsclient --no-wait +line:column file

gvim

this will invoke

gvim --remote +:line:normcolumn file

nedit

this will invoke

  nc -noask +line file'

The environment variable LYEDITOR is used to override this. It contains the command line to start the editor, where %(file)s, %(column)s, %(line)s is replaced with the file, column and line respectively. The setting

emacsclient --no-wait +%(line)s:%(column)s %(file)s

for LYEDITOR is equivalent to the standard emacsclient invocation.

Using Xpdf

For Xpdf on UNIX, the following should be present in ‘xpdfrc’. On UNIX, this file is found either in ‘/etc/xpdfrc’ or as ‘$HOME/.xpdfrc’.

urlCommand     "lilypond-invoke-editor %s"

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 ‘xpdf’ package and the corresponding ‘libpoppler’ package from Debian instead. Once you have tested that this works, you might want to use

sudo apt-mark hold xpdf

in order to keep Ubuntu from overwriting it with the next ‘update’ of its crashing package.

Using GNOME 2

For using GNOME 2 (and PDF viewers integrated with it), the magic invocation for telling the system about the ‘textedit:’ URI is;

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

After that invocation;

gnome-open textedit:///etc/issue:1:0:0

should call ‘lilypond-invoke-editor’ for opening files.

Using GNOME 3

In GNOME 3, URIs are handled by the ‘gvfs’ layer rather than by ‘gconf’. Create a file in a local directory such as ‘/tmp’ that is called ‘lilypond-invoke-editor.desktop’ and has the contents;

[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

and then execute the commands

xdg-desktop-menu install ./lilypond-invoke-editor.desktop
xdg-mime default lilypond-invoke-editor.desktop x-scheme-handler/textedit

After that invocation;

gnome-open textedit:///etc/issue:1:0:0

should call ‘lilypond-invoke-editor’ for opening files.

Extra configuration for Evince

If 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 ‘/etc/apparmor.d/local/usr.bin.evince’ and append the following lines:

# For Textedit links
/usr/local/bin/lilypond-invoke-editor Cx -> sanitized_helper,

After adding these lines, call

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.

Enabling point and click

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 these (and PS) files, point and click may be switched off by issuing

\pointAndClickOff

in a ‘.ly’ file. Point and click may be explicitly enabled with

\pointAndClickOn

Alternately, you may disable point and click with a command-line option:

lilypond -dno-point-and-click file.ly

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:

• Hard-coded in the ‘.ly’ file:

  \pointAndClickTypes #'note-event
  \relative {
    c'2\f( f)
  }
  

  or

  #(ly:set-option 'point-and-click 'note-event)
  \relative {
    c'2\f( f)
  }
  

• Command-line:

  lilypond -dpoint-and-click=note-event   example.ly
  

Multiple events can be included:

• Hard-coded in the ‘.ly’ file:

  \pointAndClickTypes #'(note-event dynamic-event)
  \relative {
    c'2\f( f)
  }
  

  or

  #(ly:set-option 'point-and-click '(note-event dynamic-event))
  \relative {
    c'2\f( f)
  }
  

• Command-line:

  lilypond \ -e"(ly:set-option 'point-and-click '(note-event dynamic-event))" \ example.ly

Other languages: català, español, français, magyar, italiano.
About automatic language selection.

<< Back to Documentation Index

LilyPond — Usage v2.21.0 (development-branch).