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 looks up the environment variables EDITOR and LYEDITOR to find out and launch the favorite editor to use. LYEDITOR will have priority over EDITOR, so we recommend using the former especially if you want to use one editor in the terminal and another editor for LilyPond point and click.

Every editor may have a different syntax to open a file in a specific line and column. For user’s convenience, LilyPond comes with ready commands for several editors, listed in ‘scm/editor.scm’. This means that you can simply write the editor binary name, e.g.:

export LYEDITOR=atom

and this will invoke

atom %(file)s:%(line)s:%(column)s

where %(file)s, %(line)s and %(column)s are replaced with the file, line and column respectively.

In order to use an editor not listed in ‘scm/editor.scm’, you should find its specific syntax and assign the full command to LYEDITOR. Here’s an example for Visual Studio Code editor:

export LYEDITOR="code --goto %(file)s:%(line)s:%(column)s"

Note: If you choose Emacs, an extra configuration is needed. You should add the line (server-start) to your ‘~/.emacs’ file, otherwise every click on an object in the PDF will open a new Emacs window.


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

Note: 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.


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:

Multiple events can be included:


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