[icon]

GNU LilyPond

Welcome to the home of the GNU Music Typesetter

Home
Development
WikiWikiWeb
GNU Project
Translations
LilyPond dot org

Documentation
Change Log
Small FAQ
Full FAQ
User manual
Regression Test
To do

Download Source
Stable
Development

Download Binary
RedHat i386
LinuxPPC
Debian Stable
Debian Unstable
Windows Stable
Windows Unstable

Music
Short examples
Longer examples
Mutopia Project
Other URLs

Mailing Lists
Discussion
Help
Bugs
Announcements

Table of Contents

Introduction

[ The tutorial part is at the moment commented out and moved to the end of this document ]

[TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]

lilypond-book is a script that helps integrating lilypond with LaTeX or TeXinfo. lilypond-book runs Lilypond on fragments of lilypond in your source file, and includes the results into a document that can be processed with LaTeX, makeinfo or texi2dvi. The result is a text document with formatted music integrated.

lilypond-book will do its best to try to align the music to the left and right margins. Currently all papersizes, one- and twocolumn mode and the geometry package is supported. The TeXinfo command pagesize is on the TODO list for Lilypond 1.4. But changing the linewidth in other ways will not give you a straight right margin.

This document assumes you have basic knowledge of GNU LilyPond and LaTeX or texinfo.

TeXinfo reference

Your markup the lilypond code like this:

@lilypond[options, go, here]
 YOUR LILYPOND CODE
@end lilypond

or

@lilypond[option, go, here]{ YOUR LILYPOND CODE }

lilypond-book knows the default margins, and a few papersizes. These commands should be in the beginning of the document:

  • @afourpaper
  • @afourlatex
  • @afourwide
  • @smallbook
@pagesizes are not yet supported.

Examples

Two simple examples. First a complete block:

@lilypond[26pt]
c' d' e' f' g'2 g'
@end lilypond

produces this music:

Then the short version:

@lilypond[11pt]{<c' e' g'>}

and its music:

@example and @code

I'm not sure if this will go into the final documentation, this is here mostly to remember me on why things are the way they are.

lilypond-book will do nothing with special with @code and @example environments. The 'code' and 'example' commands should work just as normal. People looking at document that should be processed by lilypond-book, should notice nothing special, except from some block like this:

@lilypond
BLABLA
@end lilypond

or this:

@lilypond{ BLABLA }

Anything other is a bug in lilypond-book.

So to get this in the printed manual:

@lilypond[26pt]
\relative c'{c d e f g2 g}
@end lilypond

you have to write this:

@example
@@lilypond[26pt]
\relative c'@{c d e f g2 g@}
@@end lilypond
@end example

Simply explained, every '{', '}' and '@' has to be written as '@{', '@}' and '@@'. This is how it works in plain texinfo too.

LaTeX reference

Your markup the lilypond code like this:

\begin[option, go, here]{lilypond}
 YOUR LILYPOND CODE
\end{lilypond}

or

\lilypond{ YOUR LILYPOND CODE }

Lilypond-book know about the \onecolumn and \twocolumn commands, the geometry package and all the standard paper sizes.

The music will be surrounded by \preLilypondExample and \postLilypondExample. The variables are defined to nothing by default, and the user can redefine them to whatever he wants. [UGH: THIS DOES NOT HAPPEN WHEN YOU USE THE SHORT FORM, \LILYPOND{ ... }, CHECK OUT WHY]

Examples

\begin[26pt]{lilypond}
c' d' e' f' g'2 g'2
\end{lilypond}

produces this music:

Then the short version:

\lilypond[11pt]{<c' e' g'>}

and its music:

\begin{verbatim} and \verb|\verb|

There work just as expected. Look at mb-latex.tex for details.

Options

eps
the music is created as eps graphics that can be inserted in the middle of a text line, not only as a separate paragraph. (LaTeX only)
verbatim
CONTENTS is copied into the source enclosed in a verbatim block, followed by any text given with the intertext option, then the actual music is displayed. This option does not work with the short version of the lilypond blocks:

@lilypond{ CONTENTS } and \lilypond{ CONTENTS }

intertext="text inside apostrophs"
Used in conjunction with verbatim option.
filename=FILENAME
Save the lilypond code to FILENAME instead of using a hash value of CONTENTS.
11pt, 13pt, 16pt, 20pt, 26pt
set the fontsize to use for the music
singleline
linewidth = -1.
multiline
linewidth = textwidth
fragment
nonfragment
Override lilypond-book autodetection of what type of code is in the lilypond block, voice contents or complete code.

Invocation

When you run lilypond-book it will generate lots of small files that Lilypond will process. So to avoid all the garbage in your source directory, you should either change to a temporary directory, or use the --outdir commandline options:

cd out && lilypond-book ../yourfile.tex

lilypond-book --outdir=out yourfile.tex

For latex input, the file to give to latex has ext .latex. TeXinfo input will be written to a file with ext .texi. So be careful, don't give the source file that ext, or the file will be overwritten.

If you use --outdir, you should also cd to that directory before running LaTeX or makeinfo.

[UGH: IS THIS THE BEST WAY TO DO IT? MAYBE ADD A COMMENT LINE TO THE GENERATED FILE, SO LILYPOND-BOOK CAN TEST IF THE FILE IT IS TO OVERWRITE IS GENERATED.]

About the input

If the file contains the "block"

        \begin{lilypond}
        CONTENTS
        \end{lilypond}

then LilyPond is run on CONTENTS. lilypond-book puts the result back, surrounded by \preLilypondExample and \postLilypondExample commands. \preLilypondExample and posLilypondExample is defined to nothing by default, and the user can redefine them to whatever he wants.

Command line options


-f, --format=
Specify the document type to process, latex or texi. lilypond-book usually figure out this automatically.
--default-music-fontsize=??pt
Set the fontsize to use for lilypond if no fontsize is given as option.
--force-music-fontsize=??pt
Force all lilypond to use this fontsize, overriding options given to \begin{lilypond}
-I DIR, --include=DIR
include path
-M, --dependencies
Write dependencies to out-www/filename.dep
--dep-prefix=PREF
prepend PREF before each -M dependency
-n, --no-lily
don't run lilypond
--no-pictures
don't generate pictures
--read-lys
don't write ly files. This way you can do
        lilypond-book file.tely
        convert-ly
        lilypond-book --read-lys
        

--outname=FILE
The name of LaTeX file to output. If this option is not given, the output name derived from the input name.
--outdir=
where to place generated files
--version
print version information
--help
Print a short help message

lilypond-book is written in python 1.5, so you have to install python.

Bugs

The LaTeX \includeonly{...} command is ignored.

Ignores almost all LaTeX commands that changes margins and linewidths.

Authors

Han-Wen Nienhuys, http://www.cs.uu.nl/people/hanwen Tom Cato Amundsen
Go back to index of LilyPond.

Please send GNU LilyPond questions and comments to gnu-music-discuss@gnu.org.

Please send comments on these web pages to (address unknown)

Copyright (c) 1997, 1998, 1999, 2000 Han-Wen Nienhuys and Jan Nieuwenhuizen.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.


This page was built from LilyPond-1.3.129 by

<(address unknown)>, Mon Feb 26 13:34:06 2001 CET.