Here we go: Create a new Writer document and click the OLy button.
At the very first launch you will get two message boxes telling you that some folders ("language" and "templates") have been created. Just click "OK" to close the message boxes. Next time they won't show up again.
Also don't worry if one message box says that LilyPond could not be executed. Again, just click "OK". We'll fix that in a moment.
Now you should see the OOoLilyPond Editor window.
First, let's open the configuration dialog by clicking the "Config" button at the bottom:
A new window will pop up:
Of course, you need to have LilyPond installed on your system. In the "LilyPond Executable" field, you need to specify the executable file for LilyPond. On startup, OLy has tried to guess its correct (default) location. If that didn't work, you already got an error message. In that case, you will have to correct it manually.
-
For a Windows system, you need to know the program folder (probably
C:\Program Files (x86)\LilyPondon 64-bit Windows orC:\Program Files\LilyPondon 32-bit Windows systems). In the subfolder\usr\binyou will find the executable filelilypond.exe. If you have installed LilyPond to a different location, enter it here. The "Select" button launches a dialogue that helps you to pick the right file. -
If you are working with Linux, relax and smile. Usually, you simply need to specify
lilypondas command, without any path settings. As far as I know, that also applies for the Mac OS family which is based on Unix as well.
On the left side, there are two frames titled "Insert Images". Depending on the Office version you are using (OpenOffice or LibreOffice), you should click the appropriate options.
For the moment, all remaining settings can be left at their default values. In case you've messed up anything, there's also a "Reset to Default" button.
At the right bottom, click "OK" to apply the settings and close the dialog.
(If this results in an error message "LilyPond cannot be executed", you should re-open the Config dialog by clicking the "Config" button again and make sure that "LilyPond Executable" provides the correct command.)
Now you are back in the main Editor window. It contains some sample code, so just click the "LilyPond" button at the bottom right.
In the background, LilyPond is now translating the code into a *.png graphic file which will be inserted into Writer. The code itself is invisibly saved inside the document.
After a few seconds, the editor window should disappear, and a newly created image should show up. (If you are running LilyPond for the very first time or if you have installed or removed some fonts, it can take significally longer because LilyPond has to rebuild a font cache. Just have a little patience, this only applies to the first time.)
If you want to modify an existing OLy object, click on it to select it in Writer. Then, hit the "OLy" button.
The Editor window will show the code as it has been entered before. Here you can modify it, e.g. change some pitches (there's also no need to keep the comments) and click the "LilyPond" button again. OLy will generate a new image and replace the old one.
To insert a new OLy object, just make sure that no existing object is selected when hitting the "OLy" button.
In the Editor window, you might have noticed that you were not presented an entire LilyPond file, but only an excerpt of it. This is because OLy always works with a template. It allows you to quickly enter short snippets while not having to care about any other settings for layout etc.The snippet you just created is based on the template Default.ly which looks (more or less) like this:
\transpose %{OOoLilyPondCustom1%}c c'%{OOoLilyPondEnd%} { %{OOoLilyPondCode%} \key e \major e8 fis gis e fis8 b,4. | e2\fermata \bar "|." %{OOoLilyPondEnd%} } \include "lilypond-book-preamble.ly" #(set-global-staff-size %{OOoLilyPondStaffSize%}20%{OOoLilyPondEnd%}) \paper { #(define dump-extents #t) ragged-right = ##t line-width = %{OOoLilyPondLineWidth%}17\cm%{OOoLilyPondEnd%} } \layout { indent = #0 \context { \Score \remove "Bar_number_engraver" } } % %{OOoLilyPondCustom1Label%}Transpose:%{OOoLilyPondEnd%}
In the Editor window, there are five text fields: the big "Code" area on top, and four additional small fields named "Line Width", "Staff Size", "Custom 1" and "Custom 2" by default. They contain the template parts that are enclosed by tags, i.e. preceeded by %{OOoLilyPondCode%}, %{OOoLilyPondLineWidth%}, %{OOoLilyPondStaffSize%}, %{OOoLilyPondCustom1%} and %{OOoLilyPondCustom2%} respectively, each terminated by %{OOoLilyPondEnd%}. (Those tags themselves are ignored by LilyPond because they are comments.)
The last line changes the appearance of the editor window. It tells OLy to replace the "Custom 2" caption by "Transpose:". The comment (percent) sign at the beginning is necessary to keep the line invisible for LilyPond. As of version 0.5.12, OLy can use this mechanism to replace the caption of the Line Width, Staff Size, Custom 1 and Custom 2 Fields. Older OLy versions will simply ignore that.
All remaining parts of the template stay "invisible" to the user and cannot be changed. Don't worry, you can modify existing templates and create your own.
A template must at least have a Code section, other sections are optional. There is a template Direct to LilyPond which only consists of a Code section and contains no "invisible" parts at all. You can use it to paste ordinary *.ly files into your document. But please keep in mind that the resulting graphic should be smaller than your paper size.
Most templates (the ones without [SVG] inside the file name) make use of \include "lilypond-book-preamble.ly which results in a cropped image. Any whitespace around the music is automatically removed.
Below the code view, there is a dropdown field that lets you choose which template to use. Of course, different templates have different default code in their Code sections.
When switching the template, the code field always will update to the corresponding default code as long as you haven't made any edits yet. However, this will not happen automatically if you already made any changes. To have your current code replaced anyway, click the "Default Code" checkbox.
The "Edit" button will open a new dialog where you can edit the current template. Optionally, you can save it under a new file name.
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. The basic difference between them is explained here: