Advanced features
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.
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 *.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 and Custom 2 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.
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.
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 fileOOoLilyPond.*you get multiple filesOOoLilyPond-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.lyonly produces separateepsandpdffiles.)
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.