OOoLilyPond: Part 2 – Optimizing

In my previous post I introduced OOoLilyPond (OLy), a relaunched LibreOffice extension to integrate LilyPond music fragments in text documents, drawings and presentations. It covered rather basic topics: downloading, installing and first steps, while today’s post will discuss the more advanced topics of customization for include files and vector graphics.

Include files

Despite being designed for “small” snippets that don’t exceed one page, OLy can be used for demanding tasks:

Using include files helps keeping your main LilyPond file clear and comprehensible. If you have definitions for functions or variables that you use in multiple LilyPond documents, it’s always a good option to have them in a separate include file. For example, openLilyLib entirely relies on include files.

When including a file that is not located in the same folder as the main .ly file (or in one of LilyPond’s default folders), its path must be specified. Apart from providing the absolute path in every include statement, there is a more elegant solution: LilyPond allows to specify a list of folders where it looks for include files. IDEs like Frescobaldi make use of that option.

In the OLy Config dialog, you can specify a string containing one or more of such paths. That string may contain one or multiple include statements as described in the LilyPond usage manual: -I"path"

For example, if I need to specify two paths C:\Users\Klaus\Documents\MyScores\ and D:\MyLibrary\, the resulting string reads:
-I"C:/Users/Klaus/Documents/MyScores/" -I"D:/MyLibrary/
Note that LilyPond expects the paths to be written with forward slashes, even in Windows. If you use backward slashes, OLy will replace them for you.

Graphic file formats

By default, OLy uses .png graphic files to be inserted into LibreOffice. They are easy to handle, but being a bitmap format, they don’t offer the best image quality:

OLy02 - png150

Bitmap images have a certain resolution given in dpi (dots per inch). The above picture is an excerpt of a 150dpi .png file that shows a simple {bes'4} at a staff size of 20 (LilyPond’s default value).
When magnified like this, the quality drawbacks are obvious.

In its config dialog, OLy lets you specify a resolution for .png files.
Increasing the image resolution will also increase its quality. By default, a value of 300dpi is used, which will make the same excerpt look like this:

OLy02 - png300

Modern printers have a resolution of at least 600dpi. Therefore, this would be the minimal value to get usable print results:

OLy02 - png600

But still you can see that it is a rastered image. The transitions from black to white look somewhat blurred.
Better quality can be achieved with vector file formats. They use polygons and curves to describe the outline of every object contained in the file. Therefore they provide perfectly sharp edges at any level of magnification:

OLy02 - svg

To keep up with that high quality, one would have to further increase png resolution, which, however, would make the file size explode. The tiny examples above had 2248 bytes (150dpi), 4395 bytes (300dpi) and 9076 bytes (600dpi) as their file sizes, whereas the .svg version had 3568 bytes: Only the worst of the above .png files was smaller.

LilyPond can produce various vector file formats: Apart from .pdf, certainly its most important format, also .ps, .eps and .svg are available. However, LibreOffice cannot handle all of them:
.pdf images can be imported into LibreOffice as of version 5.3, but embedded fonts are not (yet?) recognized, hence all musical glyphs would be missing.
.eps images can only be used in OpenOffice, with the further limitation that they are not visible on screen and in pdf output (at least, for Windows there’s a workaround). In LibreOffice, they cannot be used at all.
Neither LibreOffice nor OpenOffice can import .ps files.

Finally, there are .svg files which are easily mastered by LibreOffice (not by OpenOffice – another reason to switch to LO).
In OLy’s Config dialog, you will also find a “Format” dropdown box that you can set to “svg” instead of “png”. However, for using this format with OLy, two important things have to be considered:

1. No automatic cropping

Many templates in OLy make use of include "lilypond-book-preamble.ly". This will not work with the .svg backend. Therefore, for every template there is a “[SVG]” version that works without lilypond-book-preamble. That means, however, there’s no automatic cropping.
Those templates use the Line Width field for “paper” width, and a “paper” height must be specified as well:

OLy02-Editor-Window-01

After compiling, the resulting image will have exactly the intended dimensions:
OLy02-Uncropped-Snippet-01

To get rid of the unnecessary white margins, one could adjust the width and height values by trial-and-error and recompile several times. But I think it’s much easier to manually crop the image by selecting it and hitting the appropriate button (or right-clicking it and choosing the “Crop” command from the context menu):
OLy02-Cropping-01b

The green dots turn into red cropping marks that can be dragged to a new position:
OLy02-Cropping-02

When editing an existing OLy object, you won’t always have to repeat the cropping procedure. In the main OLy window, you can choose to keep the object’s actual size and crop settings:
OLy02-Keep-Crop-01

In the Config dialog, you can specify if you want this option to be turned on or off by default. There are independent settings for Writer and Impress/Draw.

2. Font replacement

If your musical snippet contains some text markup, probably it will happen to you that a .svg image will not be displayed with the original font. Instead, some replacement font will appear:
OLy02-Fonts-01
For the above picture, a simple {c1^"What does this look like?"} has been entered using the Default [SVG] template, first rendered as .png image, second as .svg.

Now what has happened here?

In most cases, LilyPond is used to create .pdf files. Any font that is used will be embedded in the .pdf document. That means, it is displayed correctly, no matter if the font is installed on the target system or not.
This is not the case when creating .svg files: Having them displayed as intended requires to have the fonts installed on the system.

The thing is, even on your computer, LilyPond can use its own fonts without them being installed, so probably they are not. You will find those font files in their respective folder
on Linux systems:
/usr/share/lilypond/2.18.2/fonts/otf/ (whereas 2.18.2 might have to be replaced by your actual version number),
on Windows systems:
inside your LilyPond program folder (typically C:\Program Files (x86)\LilyPond\ or C:\Program Files\LilyPond\) in the subfolder usr\share\lilypond\current\fonts\otf\.

Which font files are we looking for? That depends on your LilyPond version.

Version 2.18.2 and earlier
According to the 2.18 Notation Reference, the roman (serif) font defaults to “New Century Schoolbook”.
Well, to be exact, it’s the four files CenturySchL-Bold.otf, CenturySchL-BoldItal.otf, CenturySchL-Ital.otf and CenturySchL-Roma.otf which will show up as “Century Schoolbook L” font family.

Installing those four font files on your system might do the trick. On Linux (Ubuntu Studio 16.04) it worked well for me, but on Windows 7 only the bold and italic version were available to the system. If that applies to you as well, just continue reading. We’re not yet at the end…

In addition, the 2.18 Notation Reference tells that there are no default fonts for sans and typewriter, so different computers will produce different output. If you want to take precautions against that, also continue reading.

Version 2.19
In the 2.19 Notation Reference you can see that LilyPond now provides fonts for all three font families: roman, sans and typewriter now default to “TeXGyreSchola”, “TeXGyreHeros” and “TeXGyreCursor”.
The first thing to do is installing them. Therefore, in your otf folder shown above, locate twelve files matching texgyre*.otf and install them on your computer. They seem to work without problems, even on Windows. 😉

Users of Version 2.18 can download those font families from the web, e.g.:
www.fontsquirrel.com/fonts/tex-gyre-schola
www.fontsquirrel.com/fonts/tex-gyre-heros
www.fontsquirrel.com/fonts/tex-gyre-cursor

Unfortunately, the developers decided to make another change: .svg graphic files created by LilyPond 2.19 no more contain font names by default. Instead, they use aliases like “serif”, “sans-serif” and “monospace”. While there might be some reasons for that decision, we are therefore required to take another step (LilyPond 2.18 users who want to use the new fonts also should follow these instructions):

We now have to explicitely specify the font families. Therefore we need to go to the template folder (its location can be viewed in the OLy Config dialog) and manually edit the template files that have [SVG] in their name.
Inside the paper{...} section, there is a paragraph that has been prepared for that purpose:

% If LilyPond's default fonts are not installed and therefore "invisible" to other applications,
% you can define a replacement font here:

%{
#(define fonts
   (make-pango-font-tree
    "TeXGyreSchola"           ; adjust this font name according to your needs
    "TeXGyreHeros"            ; adjust this font name according to your needs
    "TeXGyreCursor"           ; adjust this font name according to your needs
    (/ staff-height pt 20)))
%}

The command itself is enclosed in block comment signs %{ and %}. Putting a simple blank space between % and { will turn the first into an ordinary comment, and the code between them will become visible for LilyPond:

% {
#(define fonts
   (make-pango-font-tree
    "TeXGyreSchola"           ; adjust this font name according to your needs
    "TeXGyreHeros"            ; adjust this font name according to your needs
    "TeXGyreCursor"           ; adjust this font name according to your needs
    (/ staff-height pt 20)))
%}

Now save the template and repeat the procedure with the other [SVG] templates.

If your templates date from OLy 0.5.0 to 0.5.3, the paragraph will rather look like this:

% If LilyPond's default fonts are not installed and therefore "invisible" to other applications,
% you can define a replacement font here:

% {
% for LilyPond 2.19.11 and older, it only works like this:
#(define fonts
   (make-pango-font-tree
    "Century Schoolbook"  ; adjust this font name according to your system
    "sans-serif"
    "monospace"
    (/ staff-height pt 20)))
%}

In that case, just replace it by the code given above.

Phew! Now you should be able to use that SVG feature without further issues.

Translation

One last thing I’d like to mention in this post is OLy’s support for different languages. The language of the user interface can be changed by selecting a language file in the Config dialog.

OLy02-Language01

At the moment, only English and German are available. OLy will offer you all files that it can find in the language folder (its location can be found below in the Config dialog). Those language files contain all the strings that OLy needs for dialogs and messages.

In case you think that your native language is missing here, and you feel like contributing some work, you can translate one of those files into your language. They contain some helpful comments (that don’t need to be translated), so you will easily find your way.
If you are interested in doing such a work, you can contact me via lilypond.1069038.n5.nabble.com/user/SendEmail.jtp?type=user&user=4585 or just leave a comment here on this site.

Leave a Reply

Your email address will not be published. Required fields are marked *