README (c) Copyright 2005 Bernard Hurley License: GNU General Public License Version 2 or later Make sure you have read and understood this file before proceeding! --------------- Section 0 --------------- INTRODUCTION ============ There are two files, both bash shell scripts (TO DO: Pythonise these scripts). They are: lyx-book.sh - Put this in PATH somewhere. latex-to-lily.sh - Put this somewhere convienient - it does not need to be in the PATH, although it doesn't ralyy matter if it is Make sure both files are executable You will almost certainly need to edit "lyx-book.sh" to suit your system (see below). But I would advise you not to touch "latex-to-lily.sh" if you value your sanity. Please note that this is all experimental at the moment. It works on my system with LyX 1.3.6 --------------- Section 1 --------------- WHAT TO EXPECT IN LYX ===================== When everything is set up correctly, then to edit a lyx file with embedded lilypond code, invoke lyx-book.sh (see below for details). There should be thre things added to your LyX menu system. These are: 1] View => Lilypond Book This should display the final file in your postscript viewer. 2] View => Update => Lilypond Book Use this if you wish to update the view 3] File => Export => Lilypond Book This actually produces the final .ps file for you. In the unlikely event that you actually want the file that is fed through lilypond- book use File => Export => Latex, because as far as LyX is concerned it is a LaTeX file. --------------- Section 1 --------------- HOW TO EDIT LYX FILES FOR USE WITH LILYPOND BOOK ================================================ First you will need to use that package "graphicx". What I do is to do "Layout => Document.. => Preamble" and add: \usepackage{graphicx} to the preamble. Yes, there are other ways of doing it, I'm just saying what I do! Note however it has to be done for every LyX document you wish to process in this way. The lilypond can be added into ERT sections with for instance: \lilypondfile[indent=1.2\cm]{prelude-d.ly} You can also add lilypond environments to ERT such as: \lilypond[quote,fragment,staffsize=11]{} or: \begin[quote,fragment,staffsize=26]{lilypond} c' d' e' f' g'2 g'2 \end{lilypond} It is not advisable to actually edit large chunks of lilypond code within ERT as it is not designed for this. So you will probably use a lot of \lilypondfile directives. Note that if you set up your project file correctly it is possible to use relative paths in the directive. Alternatively you can make sure the file is in your PROJECTPATH (see project files below) So you will probably still be using emacs or whatever to edit you lilypond files. It is a good idea to make sure they are error free before including them in you LyX document as otherwise you can crash LyX. The present version does not have the facility to call your editor from LyX - I'm working on that! --------------- Section 2 --------------- SETTING UP LYX ============== There are two steps. Step 1] Setting up the file format Under "Edit => Preferences.. => File formats => New" make a new file format with the following information: Format: Lilypond-Book GUI Name: Lilypond Book Shortcut: k Extension: ps Viewer: /usr/share/lyx/scripts/lyxview.sh Notes: "Format" is somewhat arbitrary but you have to be consistent and it should not contain spaces. "GUI Name" is the name that will appear on the menu system. "Shortcut" is optional - if you never use short cuts you can leave this field blank. I have used "k" because "B" is already taken on my system. "Extension" MUST BE "ps". This is because what you are actually seeing when you do View => Lilypond is a Postscript file (with extension ps) "Viewer" is "/usr/share/lyx/scripts/lyxview.sh" on my system but might be slightly different on yours. Actually it is the same viewer as used for viewing Postscript files so you can look at that to see what should go here. On my system this calls ggv. You can, of course, use a different viewer, but I havn't tested it. Step 2] Setting up the Converter Under "Edit => Preferences.. => Converters" make an new converter called "LaTeX -> Lilypond Book". If you have set up the file type correctly you should be able to choose "Lilypond Book" from the drop down. Set the fields as follows: Converter: /path/to/latex-to-lily.sh $$i $$FName $$Basename Extra flag: ---- Leave this field empty! ----- ---------------- Section 3 ---------------- SETTING UP THE SCRIPT lyx-book.sh ================================= The files. First make sure the shell script lyx-book.sh is in your path. You can re-name it lyx-lilypond-book.sh, if you wish to show the conection with lilypond. You will need to do some editing to make the script to make it fit your system. (TO DO: make a config file so that lyx-book.sh does not need editing). Things to edit 1] Section 1 of lyx-book.sh ------------------------ If you have only one version of lily or you know the correct version is in the PATH, then you can comment out this section. Otherwise make the obvious adjustments! 2] Section 2 of lyx-book.sh ------------------------ Set LYX to the correct version. I have it set to "lyx-qt", but you might use "lyx" or "lyx-xforms". 3] Sections 3, 4, 5 and 6 of lyx-book.sh ------------------------------------- You should not need to edit anything here. 4] Section 7 of lyx-book.sh ------------------------ This section is here to allow me to use the lilypond fonts outside the lilypond snippets. If you will never need to do this, just comment it all out. If you think you will need to use these fonts. Then the important variable to set is DATADIR. The rationale for the way I have set it up is that I have a script that will automatically query the lily CVS and install the new version if it exists. (incidentally always keeping the old version even if it has the same version number). Since I don't want to have to edit this file every time I install a new version, I calculate DATADIR from the file VERSION in the lilypond sources. 5] Section 8 of lyx-book.sh ------------------------ You should not need to edit anything here. ---------------- Section 4 ---------------- INVOKING lyx-book.sh ==================== lyx-book.sh can be invoked as: (a) lyx-book.sh /absolute/path/to/lyxfle.lyx [dvips-params] (b) lyx-book.sh lyxfile.lyx [dvips-params] (c) lyx-book.sh projectfile.lprj [dvips-params] If you use (a) (b) then all the lilypond files you use MUST be in the same directory as lyxfile.lyx. If you use (b) you MUST be in the same directory as lyxfile.lyx when you invoke it. Therefore (c) is probably the best way of invoking it, but this means you must also write a project file. [dvips-params] are extra parameters to send to dvips. For instance, if your score is landscape it is NOT enough to set it to landscape in LyX, you MIST ALSO send the patameters "-t landscape" to dvips. It is also possible to do this in a project file (another reason for using them) ---------------- Section 4 ---------------- PROJECT FILES ============= A typical project file might look like: ------------- Bartok.lprj ------------- PROJECTDIR=/home/consultant/Bartok PROJECTPATH=${PROJECTDIR}:/my/library/of/themes LYXFILE=${PROJECTDIR}/Bartok.lyx DVIEXTRAPARAMS="-t landscape" --------------------------------------- Note that the file MUST have extension "lprj" In this projectfile: PROJECTDIR is only defined so that other variables can be set up. The only required variable is: LYXFILE, which tells LyX which file to load. PROJECTPATH lists the directories where lily files can be found. You can use either ":" or ";" as a separator It is not required and lyx-book.sh tries to guess it if it is not provided. Other variables you can define are LATEXCOUNT - This MUST be numerical and defines the number of times LaTeX will be called. It defaults to 2, which is normally. However if you LyX file contains things like bibliographies and lots of cross references, you might need a larger value. LILYEXTRAPARAMS - This allows you to add extra parameters to the call to lilypond-book. I can't see much use for it but have added it for completeness. LYXPARAMS - parameter to send to lyx ---------------- Section 5 ---------------- ISSUES ====== 1] This system works for LyX 1.3.4 and Lilypond 2.7.18 on my system. It is not guarenteed to work in any other situation. 2] It is not possible to process two LyX files that have different values for PROJECTPATH at the same time. Attempting to do so can cause a crash. To open more than with the same value of PROJECTPATH, load one using lyx-book.sh and open the others from the front end. If they have different values LATEXCOUNT or DVIEXTRAPARAMS, the system should not crash, but the results will not be what you expect. 3] You cannot print a LyX file with embedded lilypond from the front end. You must first view it (e.g. with gvv) and print from the viewer. I hope to be able to resolve [2] and [3] when I update for LyX 1.4.x