Advanced features

Advanced features

ANNOUNCEMENT
OOoLilyPond has moved to a new repository:
https://github.com/OOoLilyPond
All past/present/future development can be found at the new location. The page you are viewing right here contains all development up to V. 1.0.1, but it will no longer be maintained.

OLy has some more features that go beyond the basic use you have learned in the tutorial.

Using an external editor

Probably you are used to a particular text editor when working on LilyPond files. Of course you can use it for OLy templates as well.
The path to the template files can be found (and changed) in the configuration dialog.

Here you can also specify where your text editor's executable file is located. You can use any text editor like Mousepad, Notepad etc., but if you don't yet know Frescobaldi, you really should give it a try.

If your snippets use Include files, it can be helpful to turn on the "Temporary file in document folder" option.

Back in the main OLy window, another button might be useful: "Open as temp. file in Ext. Editor". It saves the entire snippet into a temporary *.ly file - not only the contents of the "Code" field, but including the other fields and the "invisible" parts between them. This file is opened in the external editor you've specified before. If you use an IDE like Frescobaldi, you can instantly preview your changes.

As soon as editing is finished, save your changes (without changing the file name). You can now close your external editor.

Back in OLy, hit the "Import from temp. file" button to load the updated file back into OLy. In the text fields you will recognize the changes you have applied. Hit the "LilyPond" button to insert the graphic into your document.

A word of caution: Only changes to the Code, Line Width, Staff Size, Custom 1, Custom 2, Custom 3 and Custom 4 fields are recognized. Changes to the "invisible" parts of the template are ignored! If you intend to modify those sections as well, you need to create a new template.

A very last word of caution: If you use a template that is modified or created by yourself, and you share your Office document with other collaborators, you have to share your template as well. As an alternative, you can also include your template in the document.
Also, don't forget to share any include files used by your snippet.

Other graphic file formats

By default, OLy is pre-configured to produce PNG images, but there are more options for file formats. In general, vector formats offer better image quality (you can find an explanation here: File formats - bitmap vs. vector)

This wiki has a dedicated page for all graphic file formats that can be used with OLy. Here you can find a detailed comparison with the advantages and disadvantages of each format, as well as a description of additional preparations that might be required.
See File formats.

If you don't mind installing a small piece of additional software, I would recommend to choose the PDF to SVG format.

Insert as separate images (system-by-system)

If the snippet contains multiple lines, OLy can insert each of them as a separate image (like the system-by-system insertion mode does in lyLuaTEX). Between these images, OLy then starts new paragraphs.

However, there are some requirements:

• This feature only is available in Writer documents. (It requires a macro iterating through all embedded images which is not possible in Draw or Impress.)
• The snippet must include lilypond-book-preamble.ly.
  The preamble not only removes white borders but also produces separate image files.
  Instead of one file OOoLilyPond.* you get multiple files OOoLilyPond-1.*, OOoLilyPond-2.* etc.
  OLy inserts them and starts new paragraphs between them.
• For this to work, the "Anchor" setting must be "as character".
• The "Insert images" method should be set to "Direct (LibreOffice)".
  Inserting "via Clipboard" combined with inserting paragraphs sometimes leads to wrong positioning of objects.
• File format must be "pdf to svg" (recommended, additional software required for Windows) or "eps" (not usable in LibreOffice). (lilypond-book-preamble.ly only produces separate eps and pdf files.)

A checkbox in the OLy Editor window lets you choose whether you want your snippet to be inserted as separate images.
In the Config dialogue, you can specify a default setting which will be applied to new snippets.
(Oly will not change this setting for existing snippets by itself. However, you can also change it during batch processing.)

The contents of the Editor fields (code, staff size, line width etc.) are stored in each of the images belonging to the snippet, so you won't lose anything if some of the images are erased.

When splitting a score into separate images, LilyPond cannot adjust spacing between them.
For better looking results, it can be helpful to use a paragraph style in LibreOffice that adds a small amount of space below the paragraph.

• To edit such a multi-image snippet, just select one of its images and launch OLy, perform your changes and click the LilyPond button as usual.
• After compiling, OLy will search for all images belonging to the snippet (except for the one you selected) and erase them (as well as the line breaks between them).
• Then the currently selected image (i.e. the last remaining one) is replaced by the newly created images (with new line breaks in between).

In case you only need a subset of the images belonging to your snippet, you can simply erase the ones you don't want to keep. But once your snippet gets re-compiled, all of the images will be back again.

There is a better way to achieve this: Use the "from" and "to" fields to specify a first and a last image number, and OLy will only insert the images belonging to the specified range.

To quickly find out the image number of an existing image, just select it and launch OLy. If it belongs to a multi-image snippet, you can read its file name in the title bar of the Editor window.
If, for example, the file name "OOoLilyPond-2.svg" is displayed, this is the 2nd image of your snippet.

How can OLy recognize which images belong to the same snippet? Multi-image objects have a timestamp (date and time) indicating when the Ly file was compiled. Images with the same timestamp are assumed to belong to the same object.

Attention, there is a trap:
If you copy an image from a multi-image object, it still has the same timestamp as the "original". When you edit and compile it, only the "original" image that you copied will remain, the other images that belong to the original object will disappear.
Don't worry: The "copy" you just compiled has got a new timestamp. You can now re-compile the remaining image from the "original" object to get the missing images back. Now both objects are complete again.

To avoid this problem, you can uncheck the "insert as separate images" checkbox and re-compile your snippet before copying it. Afterwards, you can re-open and re-compile both snippets ("original" and "copy") using the "insert as separate images" option again.

Alternatively, if you want to create a new snippet based on an existing one, you can copy its code from the OLy editor window into the clipboard. Now create a new OLy object and insert the code from the clipboard.

Batch processing (only in Writer)

Besides the "OLy" button, there is a new "Batch" button.
It opens a new dialogue that lets you specify search-and-replace expressions.

This "Batch" function will not care about which objects are selected in Writer.
Once you hit the "Start" button, it will iterate through all OLy objects in the document.

• OLy reads the object and checks if it matches your search criteria (to have all objects processed, choose "no condition").
  You can specify in what field (Code, Line Width, Staff Size, ...) you want to search for a certain expression.
  Hint: In the Code field, it's also possible to search for comments, e.g.
  % first movement or % use smaller staff size etc.
• If your criteria are fulfilled, you will be asked if the object is to be processed
  (apart from "yes" or "no", you can also abort batch processing or choose to continue without further query).

• The changes you requested are now applied to the content of the search field.
  (You can also choose "No change". This can be useful if you only want objects to be re-compiled, e.g. after editing a template or an include file.)
• Finally, LilyPond is called to create a new image which will replace the existing one. (Just like when clicking the "LilyPond" button in the OLy editor window)

During batch compilation, "anchor" and "wrap" settings will not be changed.

If you activate the "Create backup" option, OLy will save a copy of your text document first.
This option only is available if the document has already been saved and thus already has a file name.

You will find this backup in the same folder with a timestamp added to the file name.
For example, if your document is named Test.odt and a backup is created on March 7th 2020 at 15:55:02, the latter will be named
Test_2020-03-07_15-55-02.odt.

You can choose to "Keep size & crop settings".

For "Insert as separate images" and "include template in object", apart from yes or no you can choose to keep the object's current settings.

The following settings will be applied as specified in the OLy config dialogue:

• default template (Writer)
• default line width and staff size
• insert images: Via clipboard (OpenOffice) / Direct (LibreOffice)
• Include statement(s)
• template path
• format for image files
• (for png format: resolution (dpi) and settings for transparent background)

Regarding multi-image objects (using the "insert as separate images" option), only one of the corresponding images (the one with the lowest image number) is selected and recompiled.
During this process, all other images belonging to the same object will be erased and the compilation process will produce new images (see above).

The Batch button is only available in Writer documents.
(Batch processing requires access to all graphic objects in the document. Unfortunately, in LibreOffice and OpenOffice only Writer documents have that feature, but it's not available in Draw or Impress.)