NAME = documentation
LANGS = $(shell $(PYTHON) $(top-src-dir)/python/langdefs.py)
-MANUALS_SUBDIRS = application automated-engraving contributor essay general learning notation
+MANUALS_SUBDIRS = usage automated-engraving contributor essay general learning notation
SUBDIRS = $(MANUALS_SUBDIRS) snippets logo pictures misc po css topdocs $(LANGS)
STEPMAKE_TEMPLATES = documentation texinfo tex omf
LOCALSTEPMAKE_TEMPLATES = lilypond ly
OUT_HTML_FILES += $(HTML_PAGE_NAMES:%=$(outdir)/%.html)
MAIN_INFO_DOC = lilypond-notation
-INFO_DOCS = lilypond-application lilypond-changes lilypond-contributor lilypond-internals \
+INFO_DOCS = lilypond-usage lilypond-changes lilypond-contributor lilypond-internals \
lilypond-essay lilypond-learning lilypond-notation music-glossary \
lilypond-general
ifeq ($(out),www)
+++ /dev/null
-\input texinfo @c -*- coding: utf-8; mode: texinfo; -*-
-@ignore
- Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-
- When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
-@end ignore
-
-@setfilename lilypond-application.info
-@settitle LilyPond Application usage
-@documentencoding UTF-8
-@documentlanguage en
-@afourpaper
-
-@macro manualIntro
-This file explains how to execute the programs distributed with
-LilyPond version @version{}. In addition, it suggests some
-@qq{best practices} for efficient usage.
-@end macro
-
-@macro copyrightDeclare
-Copyright @copyright{}
-1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
-by the authors.
-@end macro
-
-@set FDL
-@include macros.itexi
-
-
-@c don't remove this comment.
-@ignore
-@omfcreator Han-Wen Nienhuys, Jan Nieuwenhuizen and Graham Percival
-@omfdescription Application Usage of the LilyPond music engraving system
-@omftype program usage
-@omfcategory Applications|Publishing
-@omflanguage English
-@end ignore
-
-
-@lilyTitlePage{Usage}
-
-
-@c TOC -- non-tex
-@ifnottex
-
-@c maybe add a "Tasks" or "Specific tasks" or something like
-@c that, after Suggestions -gp
-@menu
-* Running lilypond:: Operation.
-* Updating files with convert-ly:: Updating input files.
-* lilypond-book:: Integrating text and music.
-* Converting from other formats:: Converting to lilypond source format.
-* Suggestions for writing files:: Best practices and effective bug-fixing.
-
-Appendices
-
-* GNU Free Documentation License:: License of this document.
-* LilyPond index::
-@end menu
-
-@docMain
-@end ifnottex
-
-
-@contents
-
-
-@include application/running.itely
-@include application/updating.itely
-@include application/lilypond-book.itely
-@include application/converters.itely
-@include application/suggestions.itely
-
-@include fdl.itexi
-
-@node LilyPond index
-@appendix LilyPond index
-
-@printindex cp
-
-@bye
+++ /dev/null
-depth = ../..
-
-LOCALSTEPMAKE_TEMPLATES = ly
-
-LATEX_FILES =$(call src-wildcard,*.latex)
-EXTRA_DIST_FILES = $(LATEX_FILES)
-
-include $(depth)/make/stepmake.make
-
-
+++ /dev/null
-@c -*- coding: utf-8; mode: texinfo; -*-
-
-@ignore
- Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-
- When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
-@end ignore
-
-@c \version "2.12.0"
-
-@node Converting from other formats
-@chapter Converting from other formats
-
-Music can be entered also by importing it from other formats. This
-chapter documents the tools included in the distribution to do so.
-There are other tools that produce LilyPond input, for example GUI
-sequencers and XML converters. Refer to the
-@uref{http://@/lilypond@/.org,website} for more details.
-
-These are separate programs from @command{lilypond} itself, and are
-run on the command line; see @ref{Command-line usage} for more
-information. If you have MacOS 10.3 or 10.4 and you have trouble
-running some of these scripts, e.g. @code{convert-ly}, see
-@rgeneral{MacOS X}.
-
-
-@knownissues
-We unfortunately do not have the resources to maintain these
-programs; please consider them @qq{as-is}. Patches are appreciated, but
-bug reports will almost certainly not be resolved.
-
-@menu
-* Invoking midi2ly:: Importing MIDI.
-* Invoking musicxml2ly:: Importing MusicXML.
-* Invoking abc2ly:: Importing ABC.
-* Invoking etf2ly:: Importing Finale.
-* Other formats::
-@end menu
-
-
-
-@node Invoking midi2ly
-@section Invoking @command{midi2ly}
-
-@cindex MIDI
-
-@command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
-file.
-
-MIDI (Music Instrument Digital Interface) is a standard for digital
-instruments: it specifies cabling, a serial protocol and a file
-format. The MIDI file format is a de facto standard format for
-exporting music from other programs, so this capability may come in
-useful when importing files from a program that has a converter for a
-direct format.
-
-@command{midi2ly} converts tracks into @rinternals{Staff} and
-channels into @rinternals{Voice} contexts. Relative mode is used
-for pitches, durations are only written when necessary.
-
-It is possible to record a MIDI file using a digital keyboard, and
-then convert it to @file{.ly}. However, human players are not
-rhythmically exact enough to make a MIDI to LY conversion trivial.
-When invoked with quantizing (@code{-s} and @code{-d} options)
-@command{midi2ly} tries to compensate for these timing errors, but is not
-very good at this. It is therefore not recommended to use @command{midi2ly}
-for human-generated midi files.
-
-
-It is invoked from the command-line as follows,
-@example
-midi2ly [@var{option}]@dots{} @var{midi-file}
-@end example
-
-Note that by @q{command-line}, we mean the command line of the
-operating system. See @ref{Converting from other formats}, for
-more information about this.
-
-The following options are supported by @command{midi2ly}.
-
-@table @code
-@item -a, --absolute-pitches
-Print absolute pitches.
-
-@item -d, --duration-quant=@var{DUR}
-Quantize note durations on @var{DUR}.
-
-@item -e, --explicit-durations
-Print explicit durations.
-
-@item -h,--help
-Show summary of usage.
-
-@item -k, --key=@var{acc}[:@var{minor}]
-Set default key. @math{@var{acc} > 0} sets number of sharps;
-@math{@var{acc} < 0} sets number of flats. A minor key is indicated by
-@code{:1}.
-
-@item -o, --output=@var{file}
-Write output to @var{file}.
-
-@item -s, --start-quant=@var{DUR}
-Quantize note starts on @var{DUR}.
-
-@item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
-Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
-
-@item -v, --verbose
-Be verbose.
-
-@item -V, --version
-Print version number.
-
-@item -w, --warranty
-Show warranty and copyright.
-
-@item -x, --text-lyrics
-Treat every text as a lyric.
-@end table
-
-
-@knownissues
-
-Overlapping notes in an arpeggio will not be correctly rendered. The
-first note will be read and the others will be ignored. Set them all
-to a single duration and add phrase markings or pedal indicators.
-
-
-@node Invoking musicxml2ly
-@section Invoking @code{musicxml2ly}
-
-@cindex MusicXML
-
-@uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
-for representing music notation.
-
-@command{musicxml2ly} extracts the notes, articulations, score structure,
-lyrics, etc. from part-wise MusicXML files, and writes them to a .ly
-file. It is invoked from the command-line.
-
-
-It is invoked from the command-line as follows,
-@example
-musicxml2ly [@var{option}]@dots{} @var{xml-file}
-@end example
-
-Note that by @q{command-line}, we mean the command line of the
-operating system. See @ref{Converting from other formats}, for
-more information about this.
-
-If the given filename is @file{-}, @command{musicxml2ly} reads input
-from the command line.
-
-The following options are supported by @command{musicxml2ly}:
-
-@table @code
-@item -a, --absolute
-convert pitches in absolute mode.
-
-@item -h,--help
-print usage and option summary.
-
-@item -l, --language=LANG
-use a different language file 'LANG.ly' and corresponding pitch names,
-e.g. 'deutsch' for deutsch.ly and German note names.
-
-@item --lxml
-use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
-
-@item --nd --no-articulation-directions
-do not convert directions (@code{^}, @code{_} or @code{-}) for
-articulations, dynamics, etc.
-
-@item --no-beaming
-do not convert beaming information, use LilyPond's automatic
-beaming instead.
-
-@item -o,--output=@var{file}
-set output filename to @var{file}. If @var{file} is @file{-}, the output
-will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
-be used.
-
-@item -r,--relative
-convert pitches in relative mode (default).
-
-@item -v,--verbose
-be verbose.
-
-@item --version
-print version information.
-
-@item -z,--compressed
-input file is a zip-compressed MusicXML file.
-@end table
-
-
-@node Invoking abc2ly
-@section Invoking @code{abc2ly}
-
-@warning{This program is not supported, and may be remove from
-future versions of LilyPond.}
-
-@cindex ABC
-
-ABC is a fairly simple ASCII based format. It is described at the ABC site:
-
-@quotation
-@uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
-@end quotation
-
-@command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
-
-@example
-abc2ly [@var{option}]@dots{} @var{abc-file}
-@end example
-
-The following options are supported by @command{abc2ly}:
-
-@table @code
-@item -b,--beams=None
-preserve ABC's notion of beams
-@item -h,--help
-this help
-@item -o,--output=@var{file}
-set output filename to @var{file}.
-@item -s,--strict
-be strict about success
-@item --version
-print version information.
-@end table
-
-There is a rudimentary facility for adding LilyPond code to the ABC
-source file. If you say:
-
-@example
-%%LY voices \set autoBeaming = ##f
-@end example
-
-This will cause the text following the keyword @q{voices} to be inserted
-into the current voice of the LilyPond output file.
-
-Similarly,
-
-@example
-%%LY slyrics more words
-@end example
-
-will cause the text following the @q{slyrics} keyword to be inserted
-into the current line of lyrics.
-
-
-@knownissues
-
-The ABC standard is not very @q{standard}. For extended features
-(e.g., polyphonic music) different conventions exist.
-
-Multiple tunes in one file cannot be converted.
-
-ABC synchronizes words and notes at the beginning of a line;
-@command{abc2ly} does not.
-
-@command{abc2ly} ignores the ABC beaming.
-
-
-@node Invoking etf2ly
-@section Invoking @command{etf2ly}
-
-@warning{This program is not supported, and may be remove from
-future versions of LilyPond.}
-
-@cindex ETF
-@cindex enigma
-@cindex Finale
-@cindex Coda Technology
-
-ETF (Enigma Transport Format) is a format used by Coda Music
-Technology's Finale product. @command{etf2ly} will convert part of an ETF
-file to a ready-to-use LilyPond file.
-
-It is invoked from the command-line as follows.
-
-@example
-etf2ly [@var{option}]@dots{} @var{etf-file}
-@end example
-
-Note that by @q{command-line}, we mean the command line of the
-operating system. See @ref{Converting from other formats}, for
-more information about this.
-
-The following options are supported by @command{etf2ly}:
-
-@table @code
-@item -h,--help
-this help
-@item -o,--output=@var{FILE}
-set output filename to @var{FILE}
-@item --version
-version information
-@end table
-
-
-@knownissues
-
-The list of articulation scripts is incomplete. Empty measures
-confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
-
-
-@node Other formats
-@section Other formats
-
-@cindex External programs, generating LilyPond files
-
-LilyPond itself does not come with support for any other formats,
-but some external tools can also generate LilyPond files. These
-are listed in @rgeneral{Alternate editors}.
-
+++ /dev/null
-\documentclass[a4paper]{article}
-
-%\def\preLilyPondExample{}}
-%\def\postLilyPondExample{}
-
-
-\begin{document}
-
-\begin{lilypond}
-\relative { c' d e f g a b c }
-\end{lilypond}
-
-
-\begin[fragment]{lilypond}
-c d e
-\end{lilypond}
-
-
-% show interaction of margins lilypond+verses
-
-% outdated
-% generate standard lilypond titles
-\input titledefs.tex
-\def\preLilyPondExample{\def\mustmakelilypondtitle{}}
-
-\begin{lilypond}
-\header {
- title = "Title"
- subtitle = "Subtitle"
- subsubtitle = "Subsubtitle"
- opus = "Opus 1"
- piece = "Piece"
- composer = "Composer"
- enteredby = "JCN"
- instrument = "instrument"
-}
-\layout { linewidth = -1. }
-\relative c'' { a b c d }
-\end{lilypond}
-
-\begin{enumerate}
-\item Vers one. aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa
-\item Vers two. bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb
-\end{enumerate}
-
-\end{document}
+++ /dev/null
-\documentclass[a4paper, 12pt]{article}
-% keep \documentclass on 1st line for lilypond-book auto-detection
-
-%
-% This is way too long and hairy --
-%
-%
-
-
-
-
-%\def\preLilyPondExample{}
-%\def\postLilyPondExample{}
-%\usepackage{graphics}
-%\usepackage{landscape}
-
-\begin{document}
-%uncomment this to try twocolumn mode
-%\twocolumn
-
-
-\section{LilyPond-book + LaTeX}
-
-This is an examplefile for mixing LilyPond and Latex. It is also
-used to test lilypond-book. View the source to see how it is done.
-
-A simple scale:
-
-\begin{lilypond}
-\score{
- \relative c'{c d e f g a b c}
-}
-\end{lilypond}
-
-LilyPond-book search for the \verb|\score| command when it decides
-if the code is only a fragment. Thus, in the following code, you have
-to use \verb|fragment| option, because the comment confuses lilypond-book.
-
-\begin[fragment]{lilypond}
-c d e % \score
-\end{lilypond}
-
-There is also a shorthand version \verb|\lilypond[fragment]{c' e' g'}|:
-
-\lilypond[fragment]{c' e' g'}
-
-that is the same as writing
-\begin{verbatim}
-\begin[fragment]{lilypond}
-c' e' g'
-\end{lilypond}
-\end{verbatim}
-
-This C major
-%%\begin[staffsize=11\pt,fragment]{lilypond}
-\begin[11pt,fragment]{lilypond}
-\context Voice <<c' e' g'>>
-\end{lilypond}
-and C minor
-\lilypond[fragment,11pt]{\context Voice <<c' es' g'>>} chords are floating inside the text.
-
-\subsection{verb and verbatim}
-
-As you see, the begin/end verbatim command inside
-does not confuse lilypond-book:
-
-\verb|\begin[fragment]{lilypond}c d e\end{lilypond}|
-
-Neither does a verbatim inside verb:
-
-\verb|\begin{verbatim}\begin[fragment]{lilypond}c d e\end{lilypond}\end{verbatim}|
-
-or verb inside verbatim:
-
-\begin{verbatim}
-\verb|\begin[fragment]{lilypond}c d e\end{lilypond}|
-\end{verbatim}
-
-But this is just to stress \verb|lilypond-book|. What you need is:
-
-\verb|\lilypond[fragment]{c' d' e'}|
-
-and
-
-\begin{verbatim}
-\begin{lilypond}
-c d e
-\end{lilypond}
-\end{verbatim}
-
-\subsection{The 'verbatim' and 'intertext' option}
-This shows the verbatim option:
-\begin[fragment,verbatim, intertext="gives this music:"]{lilypond}
-c' d' e'
-\end{lilypond}
-
-\subsection{LaTeX comments}
-This is a line with lilypond code
-after the comment char % \lilypond{\context Voice <<c' e' g'>>}
-% \lilypond{\context Voice <<c' e' g'>>}
-
-If you do not see any music from the heading 'LaTeX comments' and until
-this line, then lilypond-book is handling latex comments pretty well :-)
-
-\subsection{To float or not to float}
-This music
-\begin[fragment]{lilypond}
-c' e'
-\end{lilypond}
-should be floating inside the text by using the \verb|eps| options.
-
-This music
-
-\begin[fragment]{lilypond}
-c' e'
-\end{lilypond}
-
-has also the \verb|eps| options, but is not floating because there
-are an emptry line before and after the lilypond block. That is
-correct behaviour because it follows La\TeX{} convention that an
-empty line signals a new paragraph. The \verb|eps| option
-is not necessary when you want the music in a paragraph on its own.
-
-\subsection{More examples}
-
-Itemize environment:
-\begin{itemize}
-\item
-\lilypond[11pt,fragment]{ c'} do
-\item
-\lilypond[11pt,fragment]{d'} re
-\item
-\lilypond[11pt,fragment]{e'} mi
-\item
-\lilypond[11pt,fragment]{f'} fa
-\item
-\lilypond[11pt,fragment]{g'} sol
-\end{itemize}
-
-Tables\footnote{ and footnote:
-\lilypond[11pt,fragment]{c' e' g'} }:
-\marginpar{ Yes, even as marginpar
-\lilypond[11pt,fragment]{c' d' e'} }
-
-\begin{tabular}{|l|l|r|}
-\hline
-\em Notes & \em Name \\
-\hline
-\lilypond[11pt,fragment,filename="cdur"]{\context Voice <<c' e' g'>>} & major \\
-\lilypond[11pt,fragment]{\context Voice <<c' es' g'>>} & minor \\
-\lilypond[11pt,fragment]{\context Voice <<c' es' ges'>>} & diminished \\
-\lilypond[11pt,fragment]{\context Voice <<c' e' gis'>>} & augmented \\
-\hline
-\end{tabular}
-
-\pagebreak
-
-Testing of spacing. The next music is surrounded by an empty line.
-text text text text text text text text text text text text
-text text text text text text text text text text text text
-
-\begin{lilypond}
-\score{ \relative c'{ c d e f g a b c} }
-\end{lilypond}
-
-text text text text text text text text text text text text
-text text text text text text text text text text text text
-text text text text text text text text text text text text
-
-Next has no empty lines.
-text text text text text text text text text text text text
-text text text text text text text text text text text text
-text text text text text text text text text text text text
-\begin{lilypond}
-\score{ \relative c'{ c d e f g a b c} }
-\end{lilypond}
-text text text text text text text text text text text text
-text text text text text text text text text text text text
-
-%% need to use an -I ../../../input/test to find the file
-%% \lilypondfile{tie.ly}
-
-\end{document}
+++ /dev/null
-@c -*- coding: utf-8; mode: texinfo; -*-
-
-@ignore
- Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-
- When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
-@end ignore
-
-@c \version "2.12.0"
-
-@c Note: keep this node named so that `info lilypond-book' brings you here.
-@node lilypond-book
-@chapter Running @command{lilypond-book}
-
-If you want to add pictures of music to a document, you can simply do it
-the way you would do with other types of pictures. The pictures are
-created separately, yielding PostScript output or PNG images, and those
-are included into a @LaTeX{} or HTML document.
-
-@command{lilypond-book} provides a way to automate this process: This
-program extracts snippets of music from your document, runs
-@command{lilypond} on them, and outputs the document with pictures
-substituted for the music. The line width and font size definitions for
-the music are adjusted to match the layout of your document.
-
-This is a separate program from @command{lilypond} itself, and is run
-on the command line; for more information, see @ref{Command-line
-usage}. If you have MacOS 10.3 or 10.4 and you have trouble running
-@code{lilypond-book}, see @rgeneral{MacOS X}.
-
-This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
-documents.
-
-@cindex texinfo
-@cindex latex
-@cindex texinfo
-@cindex texi
-@cindex html
-@cindex docbook
-@cindex documents, adding music to
-@cindex HTML, music in
-@cindex Texinfo, music in
-@cindex DocBook, music in
-@cindex @LaTeX{}, music in
-
-@menu
-* An example of a musicological document::
-* Integrating music and text::
-* Music fragment options::
-* Invoking lilypond-book::
-* Filename extensions::
-* lilypond-book templates::
-* Alternate methods of mixing text and music::
-@end menu
-
-
-@node An example of a musicological document
-@section An example of a musicological document
-
-@cindex musicology
-Some texts contain music examples. These texts are musicological
-treatises, songbooks, or manuals like this. Such texts can be made by
-hand, simply by importing a PostScript figure into the word processor.
-However, there is an automated procedure to reduce the amount of work
-involved in HTML, @LaTeX{}, Texinfo and DocBook documents.
-
-A script called @code{lilypond-book} will extract the music fragments,
-format them, and put back the resulting notation. Here we show a small
-example for use with @LaTeX{}. The example also contains explanatory
-text, so we will not comment on it further.
-
-@subheading Input
-
-@quotation
-@verbatim
-\documentclass[a4paper]{article}
-
-\begin{document}
-
-Documents for \verb+lilypond-book+ may freely mix music and text.
-For example,
-
-\begin{lilypond}
-\relative c' {
- c2 g'2 \times 2/3 { f8 e d } c'2 g4
-}
-\end{lilypond}
-
-Options are put in brackets.
-
-\begin[fragment,quote,staffsize=26,verbatim]{lilypond}
- c'4 f16
-\end{lilypond}
-
-Larger examples can be put into a separate file, and introduced with
-\verb+\lilypondfile+.
-
-\lilypondfile[quote,noindent]{screech-boink.ly}
-
-(If needed, replace screech-boink.ly by any .ly file you put in the same
-directory as this file.)
-
-\end{document}
-@end verbatim
-@end quotation
-
-@subheading Processing
-
-Save the code above to a file called @file{lilybook.lytex}, then in a
-terminal run
-
-@c keep space after @version{} so TeX doesn't choke
-@example
-lilypond-book --output=out --pdf lilybook.lytex
-@emph{lilypond-book (GNU LilyPond) @version{} }
-@emph{Reading lilybook.lytex...}
-@emph{..lots of stuff deleted..}
-@emph{Compiling lilybook.tex...}
-cd out
-pdflatex lilybook
-@emph{..lots of stuff deleted..}
-xpdf lilybook
-@emph{(replace @command{xpdf} by your favorite PDF viewer)}
-@end example
-
-Running @command{lilypond-book} and @command{latex} creates a lot of
-temporary files, which would clutter up the working directory. To
-remedy this, use the @code{--output=@var{dir}} option. It will create
-the files in a separate subdirectory @file{dir}.
-
-Finally the result of the @LaTeX{} example shown above.@footnote{This
-tutorial is processed with Texinfo, so the example gives slightly
-different results in layout.} This finishes the tutorial section.
-
-@page
-
-@subheading Output
-
-Documents for @command{lilypond-book} may freely mix music and text.
-For example,
-
-@lilypond
-\relative c' {
- c2 g'2 \times 2/3 { f8 e d } c'2 g4
-}
-@end lilypond
-
-Options are put in brackets.
-
-@lilypond[fragment,quote,staffsize=26,verbatim]
-c'4 f16
-@end lilypond
-
-Larger examples can be put into a separate file, and introduced with
-@code{\lilypondfile}.
-
-@lilypondfile[quote,noindent]{screech-boink.ly}
-
-
-@page
-
-@node Integrating music and text
-@section Integrating music and text
-
-Here we explain how to integrate LilyPond with various output formats.
-
-@menu
-* LaTeX::
-* Texinfo::
-* HTML::
-* DocBook::
-@end menu
-
-@node LaTeX
-@subsection @LaTeX{}
-
-@LaTeX{} is the de-facto standard for publishing layouts in the exact
-sciences. It is built on top of the @TeX{} typesetting engine,
-providing the best typography available anywhere.
-
-See
-@uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
-@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
-to use @LaTeX{}.
-
-Music is entered using
-
-@example
-\begin[options,go,here]@{lilypond@}
- YOUR LILYPOND CODE
-\end@{lilypond@}
-@end example
-
-@noindent
-or
-
-@example
-\lilypondfile[options,go,here]@{@var{filename}@}
-@end example
-
-@noindent
-or
-
-@example
-\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@end example
-
-Additionally, @code{\lilypondversion} displays the current version
-of lilypond.
-Running @command{lilypond-book} yields a file that can be further
-processed with @LaTeX{}.
-
-We show some examples here. The @code{lilypond} environment
-
-@example
-\begin[quote,fragment,staffsize=26]@{lilypond@}
- c' d' e' f' g'2 g'2
-\end@{lilypond@}
-@end example
-
-@noindent
-produces
-
-@lilypond[quote,fragment,staffsize=26]
-c' d' e' f' g'2 g'2
-@end lilypond
-
-The short version
-
-@example
-\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
-@end example
-
-@noindent
-produces
-
-@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
-
-@noindent
-Currently, you cannot include @code{@{} or @code{@}} within
-@code{\lilypond@{@}}, so this command is only useful with the
-@code{fragment} option.
-
-The default line width of the music will be adjusted by examining the
-commands in the document preamble, the part of the document before
-@code{\begin@{document@}}. The @command{lilypond-book} command sends
-these to @LaTeX{} to find out how wide the text is. The line width for
-the music fragments is then adjusted to the text width. Note that this
-heuristic algorithm can fail easily; in such cases it is necessary to
-use the @code{line-width} music fragment option.
-
-@cindex titling and lilypond-book
-@cindex \header in @LaTeX{} documents
-
-Each snippet will call the following macros if they have been defined by
-the user:
-
-@itemize @bullet
-@item @code{\preLilyPondExample} called before the music,
-
-@item @code{\postLilyPondExample} called after the music,
-
-@item @code{\betweenLilyPondSystem[1]} is called between systems if
-@code{lilypond-book} has split the snippet into several PostScript
-files. It must be defined as taking one parameter and will be
-passed the number of files already included in this snippet.
-The default is to simply insert a @code{\linebreak}.
-@end itemize
-
-@ignore
-Broken stuff. :(
-
-@cindex Latex, feta symbols
-@cindex fetachar
-
-To include feta symbols (such as flat, segno, etc) in a LaTeX
-document, use @code{\input@{titledefs@}}
-
-@example
-\documentclass[a4paper]@{article@}
-
-\input@{titledefs@}
-
-\begin@{document@}
-
-\fetachar\fetasharp
-
-\end@{document@}
-@end example
-
-The font symbol names are defined in the file feta20.tex; to find
-the location of this file, use the command
-
-@example
-kpsewhich feta20.tex
-@end example
-
-@end ignore
-
-@snippets
-
-Sometimes it is useful to display music elements (such as ties and slurs)
-as if they continued after the end of the fragment. This can be done by
-breaking the staff and suppressing inclusion of the rest of the LilyPond
-output.
-
-In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
-inclusion of other systems is terminated once the required number of
-systems are included. Since @code{\betweenLilyPondSystem} is first
-called @emph{after} the first system, including only the first system
-is trivial.
-
-@example
-\def\betweenLilyPondSystem#1@{\endinput@}
-
-\begin[fragment]@{lilypond@}
- c'1\( e'( c'~ \break c' d) e f\)
-\end@{lilypond@}
-@end example
-
-If a greater number of systems is requested, a @TeX{} conditional must
-be used before the @code{\endinput}. In this example, replace @q{2} by
-the number of systems you want in the output.
-
-@example
-\def\betweenLilyPondSystem#1@{
- \ifnum##1<2\else\expandafter\endinput\fi
-@}
-@end example
-
-@noindent
-(Since @code{\endinput} immediately stops the processing of the current
-input file we need @code{\expandafter} to delay the call of @code{\endinput}
-after executing @code{\fi} so that the @code{\if}-@code{\fi} clause is
-balanced.)
-
-Remember that the definition of @code{\betweenLilyPondSystem} is
-effective until @TeX{} quits the current group (such as the @LaTeX{}
-environment) or is overridden by another definition (which is, in
-most cases, for the rest of the document). To reset your
-definition, write
-
-@example
-\let\betweenLilyPondSystem\undefined
-@end example
-
-@noindent
-in your @LaTeX{} source.
-
-This may be simplified by defining a @TeX{} macro
-
-@example
-\def\onlyFirstNSystems#1@{
- \def\betweenLilyPondSystem##1@{%
- \ifnum##1<#1\else\expandafter\endinput\fi@}
-@}
-@end example
-
-@noindent
-and then saying only how many systems you want before each fragment,
-
-@example
-\onlyFirstNSystems@{3@}
-\begin@{lilypond@}...\end@{lilypond@}
-\onlyFirstNSystems@{1@}
-\begin@{lilypond@}...\end@{lilypond@}
-@end example
-
-
-@seealso
-There are specific @command{lilypond-book} command line options and
-other details to know when processing @LaTeX{} documents, see
-@ref{Invoking lilypond-book}.
-
-
-@node Texinfo
-@subsection Texinfo
-
-Texinfo is the standard format for documentation of the GNU project. An
-example of a Texinfo document is this manual. The HTML, PDF, and Info
-versions of the manual are made from the Texinfo document.
-
-In the input file, music is specified with
-
-@example
-@@lilypond[options,go,here]
- YOUR LILYPOND CODE
-@@end lilypond
-@end example
-
-@noindent
-or
-
-@example
-@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@end example
-
-@noindent
-or
-
-@example
-@@lilypondfile[options,go,here]@{@var{filename}@}
-@end example
-
-Additionally, @code{@@lilypondversion} displays the current version
-of lilypond.
-
-When @command{lilypond-book} is run on it, this results in a Texinfo
-file (with extension @file{.texi}) containing @code{@@image} tags for
-HTML, Info and printed output. @command{lilypond-book} generates images
-of the music in EPS and PDF formats for use in the printed output, and
-in PNG format for use in HTML and Info output.
-
-We show two simple examples here. A @code{lilypond} environment
-
-@example
-@@lilypond[fragment]
-c' d' e' f' g'2 g'
-@@end lilypond
-@end example
-
-@noindent
-produces
-
-@lilypond[fragment]
-c' d' e' f' g'2 g'
-@end lilypond
-
-The short version
-
-@example
-@@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
-@end example
-
-@noindent
-produces
-
-@lilypond[fragment,staffsize=11]{<c' e' g'>}
-
-Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
-in-line image. It always gets a paragraph of its own.
-
-
-@node HTML
-@subsection HTML
-
-Music is entered using
-
-@example
-<lilypond fragment relative=2>
-\key c \minor c4 es g2
-</lilypond>
-@end example
-@noindent
-@command{lilypond-book} then produces an HTML file with appropriate image
-tags for the music fragments:
-
-@lilypond[fragment,relative=2]
-\key c \minor c4 es g2
-@end lilypond
-
-For inline pictures, use @code{<lilypond ... />}, where the options
-are separated by a colon from the music, for example
-
-@example
-Some music in <lilypond relative=2: a b c/> a line of text.
-@end example
-
-
-To include separate files, say
-
-@example
-<lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
-@end example
-
-Additionally, @code{<lilypondversion/>} displays the current version
-of lilypond.
-
-
-@cindex titling in HTML
-@cindex preview image
-@cindex thumbnail
-
-@node DocBook
-@subsection DocBook
-
-For inserting LilyPond snippets it is good to keep the conformity of our
-DocBook document, thus allowing us to use DocBook editors, validation
-etc. So we don't use custom tags, only specify a convention based on the
-standard DocBook elements.
-
-@subheading Common conventions
-
-For inserting all type of snippets we use the @code{mediaobject} and
-@code{inlinemediaobject} element, so our snippets can be formatted
-inline or not inline. The snippet formatting options are always
-provided in the @code{role} property of the innermost element (see in
-next sections). Tags are chosen to allow DocBook editors format the
-content gracefully. The DocBook files to be processed with
-@command{lilypond-book} should have the extension @file{.lyxml}.
-
-@subheading Including a LilyPond file
-
-This is the most simple case. We must use the @file{.ly} extension for
-the included file, and insert it as a standard @code{imageobject}, with
-the following structure:
-
-@example
-<mediaobject>
- <imageobject>
- <imagedata fileref="music1.ly" role="printfilename" />
- </imageobject>
-</mediaobject>
-@end example
-
-Note that you can use @code{mediaobject} or @code{inlinemediaobject}
-as the outermost element as you wish.
-
-@subheading Including LilyPond code
-
-Including LilyPond code is possible by using a @code{programlisting},
-where the language is set to @code{lilypond} with the following
-structure:
-
-@example
-<inlinemediaobject>
- <textobject>
- <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
-\context Staff \with @{
- \remove Time_signature_engraver
- \remove Clef_engraver@}
- @{ c4( fis) @}
- </programlisting>
- </textobject>
-</inlinemediaobject>
-@end example
-
-As you can see, the outermost element is a @code{mediaobject} or
-@code{inlinemediaobject}, and there is a @code{textobject} containing
-the @code{programlisting} inside.
-
-@subheading Processing the DocBook document
-
-Running @command{lilypond-book} on our @file{.lyxml} file will create a
-valid DocBook document to be further processed with @file{.xml}
-extension. If you use
-@uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
-PDF file from this document automatically. For HTML (HTML Help,
-JavaHelp etc.) generation you can use the official DocBook XSL
-stylesheets, however, it is possible that you have to make some
-customization for it.
-
-
-@node Music fragment options
-@section Music fragment options
-
-In the following, a @q{LilyPond command} refers to any command described
-in the previous sections which is handled by @command{lilypond-book} to
-produce a music snippet. For simplicity, LilyPond commands are only
-shown in @LaTeX{} syntax.
-
-Note that the option string is parsed from left to right; if an option
-occurs multiple times, the last one is taken.
-
-The following options are available for LilyPond commands:
-
-@table @code
-@item staffsize=@var{ht}
-Set staff size to @var{ht}, which is measured in points.
-
-@item ragged-right
-Produce ragged-right lines with natural spacing, i.e.,
-@code{ragged-right = ##t} is added to the LilyPond snippet. This is the
-default for the @code{\lilypond@{@}} command if no @code{line-width}
-option is present. It is also the default for the @code{lilypond}
-environment if the @code{fragment} option is set, and no line width is
-explicitly specified.
-
-@item noragged-right
-For single-line snippets, allow the staff length to be stretched to
-equal that of the line width, i.e., @code{ragged-right = ##f} is
-added to the LilyPond snippet.
-
-@item line-width
-@itemx line-width=@var{size}\@var{unit}
-Set line width to @var{size}, using @var{unit} as units. @var{unit} is
-one of the following strings: @code{cm}, @code{mm}, @code{in}, or
-@code{pt}. This option affects LilyPond output (this is, the staff
-length of the music snippet), not the text layout.
-
-If used without an argument, set line width to a default value (as
-computed with a heuristic algorithm).
-
-If no @code{line-width} option is given, @command{lilypond-book} tries to
-guess a default for @code{lilypond} environments which don't use the
-@code{ragged-right} option.
-
-@item notime
-Do not print the time signature, and turns off the timing (time signature,
-bar lines) in the score.
-
-@item fragment
-Make @command{lilypond-book} add some boilerplate code so that you can
-simply enter, say,
-
-@example
-c'4
-@end example
-
-@noindent
-without @code{\layout}, @code{\score}, etc.
-
-@item nofragment
-Do not add additional code to complete LilyPond code in music snippets.
-Since this is the default, @code{nofragment} is redundant normally.
-
-@item indent=@var{size}\@var{unit}
-Set indentation of the first music system to @var{size}, using
-@var{unit} as units. @var{unit} is one of the following strings:
-@code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
-LilyPond, not the text layout.
-
-@item noindent
-Set indentation of the first music system to zero. This option affects
-LilyPond, not the text layout. Since no indentation is the default,
-@code{noindent} is redundant normally.
-
-@item quote
-Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
-the output into a quotation block. The value @q{0.4@dmn{in}} can be
-controlled with the @code{exampleindent} option.
-
-@item exampleindent
-Set the amount by which the @code{quote} option indents a music snippet.
-
-@item relative
-@itemx relative=@var{n}
-Use relative octave mode. By default, notes are specified relative to
-middle@tie{}C. The optional integer argument specifies the octave of
-the starting note, where the default @code{1} is middle C.
-@code{relative} option only works when @code{fragment} option is set,
-so @code{fragment} is automatically implied by @code{relative},
-regardless of the presence of any @code{(no)fragment} option in the
-source.
-@end table
-
-LilyPond also uses @command{lilypond-book} to produce its own
-documentation. To do that, some more obscure music fragment options are
-available.
-
-@table @code
-@item verbatim
-The argument of a LilyPond command is copied to the output file and
-enclosed in a verbatim block, followed by any text given with the
-@code{intertext} option (not implemented yet); then the actual music is
-displayed. This option does not work well with @code{\lilypond@{@}} if
-it is part of a paragraph.
-
-If @code{verbatim} is used in a @code{lilypondfile} command, it is
-possible to enclose verbatim only a part of the source file. If the
-source file contain a comment containing @samp{begin verbatim} (without
-quotes), quoting the source in the verbatim block will start after the
-last occurrence of such a comment; similarly, quoting the source verbatim
-will stop just before the first occurrence of a comment containing
-@samp{end verbatim}, if there is any. In the following source file
-example, the music will be interpreted in relative mode, but the
-verbatim quote will not show the @code{relative} block, i.e.
-
-@example
-\relative c' @{ % begin verbatim
- c4 e2 g4
- f2 e % end verbatim
-@}
-@end example
-
-@noindent
-will be printed with a verbatim block like
-
-@example
- c4 e2 g4
- f2 e
-@end example
-
-@noindent
-If you would like to translate comments and variable names in verbatim
-output but not in the sources, you may set the environment variable
-@code{LYDOC_LOCALEDIR} to a directory path; the directory should
-contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
-as a domain.
-
-@item addversion
-(Only for Texinfo output.) Prepend line @code{\version
-@@w@{"@@version@{@}"@}} to @code{verbatim} output.
-
-@item texidoc
-(Only for Texinfo output.) If @command{lilypond} is called with the
-@option{--header=@/texidoc} option, and the file to be processed is
-called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
-is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
-option makes @command{lilypond-book} include such files, adding its
-contents as a documentation block right before the music snippet.
-
-Assuming the file @file{foo@/.ly} contains
-
-@example
-\header @{
- texidoc = "This file demonstrates a single note."
-@}
-@{ c'4 @}
-@end example
-
-@noindent
-and we have this in our Texinfo document @file{test.texinfo}
-
-@example
-@@lilypondfile[texidoc]@{foo.ly@}
-@end example
-
-@noindent
-the following command line gives the expected result
-
-@example
-lilypond-book --pdf --process="lilypond \
- -dbackend=eps --header=texidoc" test.texinfo
-@end example
-
-Most LilyPond test documents (in the @file{input} directory of the
-distribution) are small @file{.ly} files which look exactly like this.
-
-For localization purpose, if the Texinfo document contains
-@code{@@documentlanguage @var{LANG}} and @file{foo@/.ly} header
-contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
-is called with @option{--header=@/texidoc@var{LANG}}, then
-@file{foo@/.texidoc@var{LANG}} will be included instead of
-@file{foo@/.texidoc}.
-
-@item lilyquote
-(Only for Texinfo output.) This option is similar to quote, but only
-the music snippet (and the optional verbatim block implied by
-@code{verbatim} option) is put into a quotation block. This option is
-useful if you want to @code{quote} the music snippet but not the
-@code{texidoc} documentation block.
-
-@item doctitle
-(Only for Texinfo output.) This option works similarly to
-@code{texidoc} option: if @command{lilypond} is called with the
-@option{--header=@/doctitle} option, and the file to be processed is
-called @file{foo@/.ly} and contains a @code{doctitle} field in the
-@code{\header}, it creates a file @file{foo@/.doctitle}. When
-@code{doctitle} option is used, the contents of @file{foo@/.doctitle},
-which should be a single line of @var{text}, is inserted in the
-Texinfo document as @code{@@lydoctitle @var{text}}.
-@code{@@lydoctitle} should be a macro defined in the Texinfo document.
-The same remark about @code{texidoc} processing with localized
-languages also applies to @code{doctitle}.
-
-@item nogettext
-(Only for Texinfo output.) Do not translate comments and variable
-names in the snippet quoted verbatim.
-
-@item printfilename
-If a LilyPond input file is included with @code{\lilypondfile}, print
-the file name right before the music snippet. For HTML output, this
-is a link. Only the base name of the file is printed, i.e. the
-directory part of the file path is stripped.
-
-@end table
-
-
-@node Invoking lilypond-book
-@section Invoking @command{lilypond-book}
-
-@command{lilypond-book} produces a file with one of the following
-extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml},
-depending on the output format. All of @file{.tex}, @file{.texi} and
-@file{.xml} files need further processing.
-
-@subheading Format-specific instructions
-
-@subsubheading @LaTeX{}
-
-There are two ways of processing your @LaTeX{} document for printing or
-publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
-PostScript file with @LaTeX{} via a DVI to PostScript translator like
-@command{dvips}. The first way is simpler and recommended@footnote{Note
-that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
-@LaTeX{} document, that is why we explain the two ways.}, and whichever
-way you use, you can easily convert between PostScript and PDF with
-tools, like @command{ps2pdf} and @command{pdf2ps} included in
-Ghostscript package.
-
-To produce a PDF file through PDF@LaTeX{}, use
-
-@example
-lilypond-book --pdf yourfile.pdftex
-pdflatex yourfile.tex
-@end example
-
-@cindex outline fonts
-@cindex type1 fonts
-@cindex dvips
-@cindex invoking dvips
-To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
-should do
-
-@example
-lilypond-book yourfile.lytex
-latex yourfile.tex
-dvips -Ppdf yourfile.dvi
-ps2pdf yourfile.ps
-@end example
-
-@noindent
-The @file{.dvi} file created by this process will not contain
- note heads. This is normal; if you follow the instructions, they
-will be included in the @file{.ps} and @file{.pdf} files.
-
-Running @command{dvips} may produce some warnings about fonts; these
-are harmless and may be ignored. If you are running @command{latex} in
-twocolumn mode, remember to add @code{-t landscape} to the
-@command{dvips} options.
-
-@subsubheading Texinfo
-
-To produce a Texinfo document (in any output format), follow the normal
-procedures for Texinfo; this is, either call @command{texi2pdf} or
-@command{texi2dvi} or @command{makeinfo}, depending on the output format
-you want to create.
-@ifinfo
-@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
-an Info File, , , texinfo, GNU Texinfo}.
-@end ifinfo
-@ifnotinfo
-See the documentation of Texinfo for further details.
-@end ifnotinfo
-
-
-@subheading Command line options
-
-@command{lilypond-book} accepts the following command line options:
-
-@table @code
-@item -f @var{format}
-@itemx --format=@var{format}
-Specify the document type to process: @code{html}, @code{latex},
-@code{texi} (the default) or @code{docbook}. If this option is missing,
-@command{lilypond-book} tries to detect the format automatically, see
-@ref{Filename extensions}. Currently, @code{texi} is the same as
-@code{texi-html}.
-
-@c This complicated detail is not implemented, comment it out -jm
-@ignore
-The @code{texi} document type produces a Texinfo file with music
-fragments in the printed output only. For getting images in the HTML
-version, the format @code{texi-html} must be used instead.
-@end ignore
-
-@item -F @var{filter}
-@itemx --filter=@var{filter}
-Pipe snippets through @var{filter}. @code{lilypond-book} will
-not --filter and --process at the same time. For example,
-
-@example
-lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
-@end example
-
-@item -h
-@itemx --help
-Print a short help message.
-
-@item -I @var{dir}
-@itemx --include=@var{dir}
-Add @var{dir} to the include path. @command{lilypond-book} also looks
-for already compiled snippets in the include path, and does not write
-them back to the output directory, so in some cases it is necessary to
-invoke further processing commands such as @command{makeinfo} or
-@command{latex} with the same @code{-I @var{dir}} options.
-
-@item -o @var{dir}
-@itemx --output=@var{dir}
-Place generated files in directory @var{dir}. Running
-@command{lilypond-book} generates lots of small files that LilyPond will
-process. To avoid all that garbage in the source directory, use the
-@option{--output} command line option, and change to that directory
-before running @command{latex} or @command{makeinfo}.
-
-@example
-lilypond-book --output=out yourfile.lytex
-cd out
-...
-@end example
-
-@itemx --skip-lily-check
-Do not fail if no lilypond output is found. It is used for LilyPond
-Info documentation without images.
-
-@itemx --skip-png-check
-Do not fail if no PNG images are found for EPS files. It is used for
-LilyPond Info documentation without images.
-
-@itemx --lily-output-dir=@var{dir}
-Write lily-XXX files to directory @var{dir}, link into @code{--output}
-directory. Use this option to save building time for documents in
-different directories which share a lot of identical snippets.
-
-@itemx --info-images-dir=@var{dir}
-Format Texinfo output so that Info will look for images of music in
-@var{dir}.
-
-@itemx --latex-program=@var{prog}
-Run executable @command{prog} instead of @command{latex}. This is
-useful if your document is processed with @command{xelatex}, for
-example.
-
-@itemx --left-padding=@var{amount}
-Pad EPS boxes by this much. @var{amount} is measured in millimeters,
-and is 3.0 by default. This option should be used if the lines of
-music stick out of the right margin.
-
-The width of a tightly clipped system can vary, due to notation
-elements that stick into the left margin, such as bar numbers and
-instrument names. This option will shorten each line and move each
-line to the right by the same amount.
-
-
-@item -P @var{command}
-@itemx --process=@var{command}
-Process LilyPond snippets using @var{command}. The default command is
-@code{lilypond}. @code{lilypond-book} will not @code{--filter} and
-@code{--process} at the same time.
-
-@item --pdf
-Create PDF files for use with PDF@LaTeX{}.
-
-@item -V
-@itemx --verbose
-Be verbose.
-
-@item -v
-@itemx --version
-Print version information.
-@end table
-
-@knownissues
-
-The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
-@LaTeX{} commands that change margins and line widths after the preamble
-are ignored.
-
-Only the first @code{\score} of a LilyPond block is processed.
-
-
-@node Filename extensions
-@section Filename extensions
-
-You can use any filename extension for the input file, but if you do not
-use the recommended extension for a particular format you may need to
-manually specify the output format; for details, see @ref{Invoking
-lilypond-book}. Otherwise, @command{lilypond-book} automatically
-selects the output format based on the input filename's extension.
-
-@quotation
-@multitable @columnfractions .2 .5
-@item @strong{extension} @tab @strong{output format}
-@item
-@item @file{.html} @tab HTML
-@item @file{.itely} @tab Texinfo
-@item @file{.latex} @tab @LaTeX{}
-@item @file{.lytex} @tab @LaTeX{}
-@item @file{.lyxml} @tab DocBook
-@item @file{.tely} @tab Texinfo
-@item @file{.tex} @tab @LaTeX{}
-@item @file{.texi} @tab Texinfo
-@item @file{.texinfo} @tab Texinfo
-@item @file{.xml} @tab HTML
-@end multitable
-@end quotation
-
-If you use the same filename extension for the input file than the
-extension @command{lilypond-book} uses for the output file, and if the
-input file is in the same directory as @command{lilypond-book} working
-directory, you must use @code{--output} option to make
-@command{lilypond-book} running, otherwise it will exit with an error
-message like @qq{Output would overwrite input file}.
-
-
-@node lilypond-book templates
-@section lilypond-book templates
-
-These templates are for use with @code{lilypond-book}. If you're not familiar
-with this program, please refer to
-@rprogram{lilypond-book}.
-
-@subsection LaTeX
-
-You can include LilyPond fragments in a LaTeX document.
-
-@example
-\documentclass[]@{article@}
-
-\begin@{document@}
-
-Normal LaTeX text.
-
-\begin@{lilypond@}
-\relative c'' @{
-a4 b c d
-@}
-\end@{lilypond@}
-
-More LaTeX text.
-
-\begin@{lilypond@}
-\relative c'' @{
-d4 c b a
-@}
-\end@{lilypond@}
-\end@{document@}
-@end example
-
-@subsection Texinfo
-
-You can include LilyPond fragments in Texinfo; in fact, this entire manual
-is written in Texinfo.
-
-@example
-\input texinfo
-@@node Top
-
-Texinfo text
-
-@@lilypond[verbatim,fragment,ragged-right]
-a4 b c d
-@@end lilypond
-
-More Texinfo text
-
-@@lilypond[verbatim,fragment,ragged-right]
-d4 c b a
-@@end lilypond
-
-@@bye
-@end example
-
-
-@subsection xelatex
-
-@verbatim
-\documentclass{article}
-\usepackage{ifxetex}
-\ifxetex
-%xetex specific stuff
-\usepackage{xunicode,fontspec,xltxtra}
-\setmainfont[Numbers=OldStyle]{Times New Roman}
-\setsansfont{Arial}
-\else
-%This can be empty if you are not going to use pdftex
-\usepackage[T1]{fontenc}
-\usepackage[utf8]{inputenc}
-\usepackage{mathptmx}%Times
-\usepackage{helvet}%Helvetica
-\fi
-%Here you can insert all packages that pdftex also understands
-\usepackage[ngerman,finnish,english]{babel}
-\usepackage{graphicx}
-
-\begin{document}
-\title{A short document with LilyPond and xelatex}
-\maketitle
-
-Normal \textbf{font} commands inside the \emph{text} work,
-because they \textsf{are supported by \LaTeX{} and XeteX.}
-If you want to use specific commands like \verb+\XeTeX+, you
-should include them again in a \verb+\ifxetex+ environment.
-You can use this to print the \ifxetex \XeTeX{} command \else
-XeTeX command \fi which is not known to normal \LaTeX .
-
-In normal text you can easily use LilyPond commands, like this:
-
-\begin{lilypond}
-{a2 b c'8 c' c' c'}
-\end{lilypond}
-
-\noindent
-and so on.
-
-The fonts of snippets set with LilyPond will have to be set from
-inside
-of the snippet. For this you should read the AU on how to use
-lilypond-book.
-
-\selectlanguage{ngerman}
-Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
-anderen
-seltsamen Zeichen: __ ______, wenn sie von der Schriftart
-unterst__tzt werden.
-\end{document}
-@end verbatim
-
-
-@node Alternate methods of mixing text and music
-@section Alternative methods of mixing text and music
-
-This section shows methods to integrate text and music, different than
-the automated method with @command{lilypond-book}.
-
-@menu
-* Many quotes from a large score::
-* Inserting LilyPond output into OpenOffice.org::
-* Inserting LilyPond output into other programs::
-@end menu
-
-@node Many quotes from a large score
-@unnumberedsubsec Many quotes from a large score
-
-If you need to quote many fragments from a large score, you can also use
-the clip systems feature, see @ruser{Extracting fragments of music}.
-
-
-@node Inserting LilyPond output into OpenOffice.org
-@unnumberedsubsec Inserting LilyPond output into OpenOffice.org
-
-@cindex OpenOffice.org
-
-LilyPond notation can be added to OpenOffice.org with
-@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
-
-
-@node Inserting LilyPond output into other programs
-@unnumberedsubsec Inserting LilyPond output into other programs
-
-To insert LilyPond output in other programs, use @code{lilypond}
-instead of @code{lilypond-book}. Each example must be created
-individually and added to the document; consult the documentation for
-that program. Most programs will be able to insert LilyPond output in
-@file{PNG}, @file{EPS}, or @file{PDF} formats.
-
-To reduce the white space around your LilyPond score, use
-the following options
-
-@example
-\paper@{
- indent=0\mm
- line-width=120\mm
- oddFooterMarkup=##f
- oddHeaderMarkup=##f
- bookTitleMarkup = ##f
- scoreTitleMarkup = ##f
-@}
-
-@{ c1 @}
-@end example
-
-To produce a useful @file{EPS} file, use
-
-@example
-lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
-
-@file{PNG}:
-lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
-@end example
-
+++ /dev/null
-@c -*- coding: utf-8; mode: texinfo; -*-
-
-@ignore
- Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-
- When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
-@end ignore
-
-@c \version "2.12.0"
-
-
-@node Running lilypond
-@chapter Running @command{lilypond}
-
-This chapter details the technicalities of running LilyPond.
-
-@menu
-* Normal usage::
-* Command-line usage::
-* Error messages::
-* Common errors::
-* Point and click::
-* Text editor support::
-@end menu
-
-
-@node Normal usage
-@section Normal usage
-
-Most users run LilyPond through a GUI; if you have not done so
-already, read @rlearning{Introduction}. If you use an alternate
-editor to write lilypond files, see the documentation for that
-program.
-
-
-@node Command-line usage
-@section Command-line usage
-
-This section contains extra information about using LilyPond on the
-command-line. This may be desirable to pass extra options to the
-program. In addition, there are certain extra @q{helper} programs (such
-as @code{midi2ly}) which are only available on the command-line.
-
-By @q{command-line}, we mean the command line in the operating system.
-Windows users might be more familiar with the terms @q{DOS shell} or
-@q{command shell}. MacOS@tie{}X users might be more familiar with the terms
-@q{terminal} or @q{console}. Some additional setup is required
-for MacOS@tie{}X users; please see @rgeneral{MacOS X}.
-
-Describing how to use this part of an operating system is outside the
-scope of this manual; please consult other documentation on this topic
-if you are unfamiliar with the command-line.
-
-@menu
-* Invoking lilypond::
-* Command line options for lilypond::
-* Environment variables::
-@end menu
-
-@node Invoking lilypond
-@unnumberedsubsec Invoking @command{lilypond}
-
-The @command{lilypond} executable may be called as follows from
-the command line.
-
-@example
-lilypond [@var{option}]@dots{} @var{file}@dots{}
-@end example
-
-
-When invoked with a filename that has no extension, the @file{.ly}
-extension is tried first. To read input from stdin, use a
-dash (@code{-}) for @var{file}.
-
-When @file{filename.ly} is processed it will produce @file{filename.ps}
-and @file{filename.pdf} as output. Several files can be specified;
-they will each be processed independently. @footnote{The status of
-GUILE is not reset after processing a @code{.ly} file, so be careful
-not to change any system defaults from within Scheme.}
-
-If @file{filename.ly} contains more than one @code{\book}
-block, then the rest of the scores will be output in numbered files,
-starting with @file{filename-1.pdf}. In addition, the value of
-@code{output-suffix} will be inserted between the basename and the
-number. An input file containing
-
-@example
-#(define output-suffix "violin")
-\score @{ @dots{} @}
-#(define output-suffix "cello")
-\score @{ @dots{} @}
-@end example
-
-@noindent
-will output @var{base}@file{-violin.pdf} and
-@var{base}@file{-cello-1.pdf}.
-
-
-@node Command line options for lilypond
-@unnumberedsubsec Command line options for @command{lilypond}
-
-@cindex Invoking @command{lilypond}
-@cindex command line options for @command{lilypond}
-@cindex options, command line
-@cindex switches
-
-The following options are supported:
-
-@table @code
-
-@item -e,--evaluate=@var{expr}
-Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
-Multiple @code{-e} options may be given, they will be evaluated
-sequentially.
-
-The expression will be evaluated in the @code{guile-user} module, so
-if you want to use definitions in @var{expr}, use
-
-@example
-lilypond -e '(define-public a 42)'
-@end example
-
-@noindent
-on the command-line, and include
-
-@example
-#(use-modules (guile-user))
-@end example
-
-@noindent
-at the top of the @code{.ly} file.
-
-@item -f,--format=@var{format}
-which formats should be written. Choices for @code{format} are
-@code{svg}, @code{ps}, @code{pdf}, and @code{png}.
-
-Example: @code{lilypond -fpng @var{filename}.ly}
-
-
-
-@item -d,--define-default=@var{var}=@var{val}
-This sets the internal program option @var{var} to the Scheme value
-@var{val}. If @var{val} is not supplied, then @var{#t} is used. To
-switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
-
-@cindex point and click, command line
-
-@example
--dno-point-and-click
-@end example
-
-@noindent
-is the same as
-@example
--dpoint-and-click='#f'
-@end example
-
-Here are a few interesting options.
-
-@cindex help, command line
-
-@table @samp
-@item help
-Running @code{lilypond -dhelp} will print all of the @code{-d} options
-available.
-
-@cindex paper-size, command line
-
-@item paper-size
-This option sets the default paper-size,
-@example
--dpaper-size=\"letter\"
-@end example
-
-@noindent
-Note that the string must be enclosed in escaped quotes ( @code{\"} ).
-@c Match " in previous line to help context-sensitive editors
-
-@cindex safe, command line
-
-@item safe
-Do not trust the @code{.ly} input.
-
-When LilyPond formatting is available through a web server, either the
-@code{--safe} or the @code{--jail} option @b{MUST} be passed. The
-@code{--safe} option will prevent inline Scheme code from wreaking
-havoc, for example
-
-@quotation
-@verbatim
-#(system "rm -rf /")
-{
- c4^#(ly:export (ly:gulp-file "/etc/passwd"))
-}
-@end verbatim
-@end quotation
-
-The @code{-dsafe} option works by evaluating in-line Scheme
-expressions in a special safe module. This safe module is derived from
-GUILE @file{safe-r5rs} module, but adds a number of functions of the
-LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
-
-In addition, safe mode disallows @code{\include} directives and
-disables the use of backslashes in @TeX{} strings.
-
-In safe mode, it is not possible to import LilyPond variables
-into Scheme.
-
-@code{-dsafe} does @emph{not} detect resource overuse. It is still possible to
-make the program hang indefinitely, for example by feeding cyclic data
-structures into the backend. Therefore, if using LilyPond on a
-publicly accessible webserver, the process should be limited in both
-CPU and memory usage.
-
-The safe mode will prevent many useful LilyPond snippets from being
-compiled. The @code{--jail} is a more secure alternative, but
-requires more work to set up.
-
-@cindex output format, setting
-@item backend
-the output format to use for the back-end. Choices for @code{format} are
-@table @code
-@item ps
-@cindex PostScript output
- for PostScript.
-
- Postscript files include TTF, Type1 and OTF fonts. No subsetting of
- these fonts is done. When using oriental character sets, this can
- lead to huge files.
-
-@item eps
-
-@cindex Postscript, encapulated
-@cindex EPS (Encapsulated PostScript)
-
- for encapsulated PostScript. This dumps every page (system) as a separate
-@file{EPS} file, without fonts, and as one collated @file{EPS} file with
-all pages (systems) including fonts.
-
-This mode is used by default by @command{lilypond-book}.
-
-@item svg
-
-@cindex SVG (Scalable Vector Graphics)
-
- for SVG (Scalable Vector Graphics).
-
- This creates a single SVG file, without embedded fonts, for every
- page of output. It is recommended to install the Century
- Schoolbook fonts, included with your LilyPond installation, for
- optimal rendering. Under UNIX, simply copy these fonts from the
- LilyPond directory (typically
- @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
- @file{~/.fonts/}. The SVG output should be compatible with any
- SVG editor or user agent.
-
-@item scm
-
-@cindex Scheme dump
-
- for a dump of the raw, internal Scheme-based drawing commands.
-
-@item null
- do not output a printed score; has the same effect as @code{-dno-print-pages}.
-@end table
-
-Example: @code{lilypond -dbackend=svg @var{filename}.ly}
-
-@item preview
-@cindex preview, command line
-Generate an output file containing the titles and the first system
-
-@item print-pages
-Generate the full pages, the default. @code{-dno-print-pages} is
-useful in combination with @code{-dpreview}.
-
-@end table
-
-
-
-@item -h,--help
-Show a summary of usage.
-
-@item -H,--header=@var{FIELD}
-Dump a header field to file @file{BASENAME.@var{FIELD}}.
-
-@item --include, -I=@var{directory}
-Add @var{directory} to the search path for input files.
-@cindex file searching
-@cindex search path
-
-@item -i,--init=@var{file}
-Set init file to @var{file} (default: @file{init.ly}).
-
-@item -o,--output=@var{FILE}
-Set the default output file to @var{FILE}. The appropriate
-suffix will be added (e.g. @code{.pdf} for pdf)
-
-@cindex PostScript output
-
-@item --ps
-Generate PostScript.
-
-@cindex Portable Network Graphics (PNG) output
-
-@item --png
-Generate pictures of each page, in PNG format. This implies
-@code{--ps}. The resolution in DPI of the image may be set with
-@example
--dresolution=110
-@end example
-
-@cindex Portable Document Format (PDF) output
-
-@item --pdf
-Generate PDF. This implies @code{--ps}.
-
-
-
-@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
-Run @command{lilypond} in a chroot jail.
-
-The @code{--jail} option provides a more flexible alternative to
-@code{--safe} when LilyPond formatting is available through a web
-server or whenever LilyPond executes externally provided
-sources.
-
-The @code{--jail} option works by changing the root of @command{lilypond} to
-@var{jail} just before starting the actual compilation process. The user
-and group are then changed to match those provided, and the current
-directory is changed to @var{dir}. This setup guarantees that it is not
-possible (at least in theory) to escape from the jail. Note that for
-@code{--jail} to work @command{lilypond} must be run as root, which is usually
-accomplished in a safe way using @command{sudo}.
-
-Setting up a jail is a slightly delicate matter, as we must be sure that
-LilyPond is able to find whatever it needs to compile the source
-@emph{inside the jail}. A typical setup comprises the following items:
-
-@table @asis
-@item Setting up a separate filesystem
-A separate filesystem should be created for LilyPond, so that it can be
-mounted with safe options such as @code{noexec}, @code{nodev}, and
-@code{nosuid}. In this way, it is impossible to run executables or to
-write directly to a device from LilyPond. If you do not want to create a
-separate partition, just create a file of reasonable size and use it to
-mount a loop device. A separate filesystem also guarantees that LilyPond
-cannot write more space than it is allowed.
-
-@item Setting up a separate user
-A separate user and group (say, @code{lily}/@code{lily}) with low
-privileges should be used to run LilyPond inside the jail. There should
-be a single directory writable by this user, which should be passed in
-@var{dir}.
-
-@item Preparing the jail
-LilyPond needs to read a number of files while running. All these files
-are to be copied into the jail, under the same path they appear in the
-real root filesystem. The entire content of the LilyPond installation
-(e.g., @file{/usr/share/lilypond})
-should be copied.
-
-If problems arise, the simplest way to trace them down is to run
-LilyPond using @command{strace}, which will allow you to determine which
-files are missing.
-
-@item Running LilyPond
-In a jail mounted with @code{noexec} it is impossible to execute any external
-program. Therefore LilyPond must be run with a backend that does not
-require any such program. As we already mentioned, it must be also run
-with superuser privileges (which, of course, it will lose immediately),
-possibly using @command{sudo}. It is a good idea to limit the number of
-seconds of CPU time LilyPond can use (e.g., using @command{ulimit
--t}), and, if your operating system supports it, the amount of memory
-that can be allocated.
-@end table
-
-
-@item -v,--version
-Show version information.
-
-@item -V,--verbose
-Be verbose: show full paths of all files read, and give timing
-information.
-
-@item -w,--warranty
-Show the warranty with which GNU LilyPond comes. (It comes with
-@strong{NO WARRANTY}!)
-@end table
-
-@node Environment variables
-@unnumberedsubsec Environment variables
-
-
-@cindex LANG
-@cindex LILYPOND_DATADIR
-
-@command{lilypond} recognizes the following environment variables:
-@table @code
-@item LILYPOND_DATADIR
-This specifies a directory where locale messages and
-data files will be looked up by default. The directory should contain
-subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
-
-@item LANG
-This selects the language for the warning messages.
-
-@item LILYPOND_GC_YIELD
-With this variable the memory footprint and performance can be
-adjusted. It is a percentage tunes memory management behavior. With
-higher values, the program uses more memory, with smaller values, it
-uses more CPU time. The default value is @code{70}.
-
-@end table
-
-
-@node Error messages
-@section Error messages
-
-@cindex error messages
-Different error messages can appear while compiling a file:
-
-@table @emph
-
-@item Warning
-@cindex warning
-Something looks suspect. If you are requesting something out of the
-ordinary then you will understand the message, and can ignore it.
-However, warnings usually indicate that something is wrong with the
-input file.
-
-@item Error
-@cindex error
-Something is definitely wrong. The current processing step (parsing,
-interpreting, or formatting) will be finished, but the next step will
-be skipped.
-
-@item Fatal error
-@cindex fatal error
-Something is definitely wrong, and LilyPond cannot continue. This
-happens rarely. The most usual cause is misinstalled fonts.
-
-@item Scheme error
-@cindex trace, Scheme
-@cindex call trace
-@cindex Scheme error
-Errors that occur while executing Scheme code are caught by the Scheme
-interpreter. If running with the verbose option (@code{-V} or
-@code{--verbose}) then a call trace of the offending
-function call is printed.
-
-@item Programming error
-@cindex Programming error
-There was some internal inconsistency. These error messages are
-intended to help the programmers and debuggers. Usually, they can be
-ignored. Sometimes, they come in such big quantities that they obscure
-other output.
-
-@item Aborted (core dumped)
-@cindex Aborted (core dumped)
-This signals a serious programming error that caused the program to
-crash. Such errors are considered critical. If you stumble on one,
-send a bug-report.
-@end table
-
-@cindex errors, message format
-If warnings and errors can
-be linked to some part of the input file, then error messages have the
-following form
-
-@example
-@var{filename}:@var{lineno}:@var{columnno}: @var{message}
-@var{offending input line}
-@end example
-
-A line-break is inserted in the offending line to indicate the column
-where the error was found. For example,
-
-@example
-test.ly:2:19: error: not a duration: 5
- @{ c'4 e'
- 5 g' @}
-@end example
-
-These locations are LilyPond's best guess about where the warning or
-error occurred, but (by their very nature) warnings and errors occur
-when something unexpected happens. If you can't see an error in the
-indicated line of your input file, try checking one or two lines
-above the indicated position.
-
-More information about errors is given in @ref{Common errors}.
-
-
-@node Common errors
-@section Common errors
-
-The error conditions described below occur often, yet the cause
-is not obvious or easily found. Once seen and understood, they
-are easily handled.
-
-
-@menu
-* Music runs off the page::
-* An extra staff appears::
-* Apparent error in ../ly/init.ly::
-* Error message Unbound variable %::
-* Error message FT_Get_Glyph_Name::
-@end menu
-
-@node Music runs off the page
-@unnumberedsubsec Music runs off the page
-
-Music running off the page over the right margin or appearing
-unduly compressed is almost always due to entering an incorrect
-duration on a note, causing the final note in a measure to extend
-over the bar line. It is not invalid if the final note in a
-measure does not end on the automatically entered bar line, as the
-note is simply assumed to carry over into the next measure. But
-if a long sequence of such carry-over measures occurs the music
-can appear compressed or may flow off the page because automatic
-line breaks can be inserted only at the end of complete measures,
-i.e., where all notes end before or at the end of the measure.
-
-@warning{An incorrect duration can cause line breaks to be
-inhibited, leading to a line of highly compressed music or
-music which flows off the page.}
-
-The incorrect duration can be found easily if bar checks are used,
-see @ruser{Bar and bar number checks}.
-
-If you actually intend to have a series of such carry-over measures
-you will need to insert an invisible bar line where you want the
-line to break. For details, see @ruser{Bar lines}.
-
-
-@node An extra staff appears
-@unnumberedsubsec An extra staff appears
-
-If contexts are not created explicitly with @code{\new} they will be
-silently created as soon as a command is encountered which cannot
-be applied to an existing context. In simple scores the automatic
-creation of contexts is useful, and most of the examples in the
-LilyPond manuals take advantage of this simplification. But
-occasionally the silent creation of contexts can give rise to
-unexpected new staves or scores. For example, it might be expected
-that the following code would cause all note heads within the
-following staff to be colored red, but in fact it results in two
-staves with the note heads remaining the default black in the lower
-staff.
-
-@lilypond[quote,verbatim,relative=2]
-\override Staff.NoteHead #'color = #red
-\new Staff { a }
-@end lilypond
-
-This is because a @code{Staff} context does not exist when the
-override is processed, so one is implicitly created and the override
-is applied to it, but then the @code{\new Staff} command creates
-another, separate, staff into which the notes are placed. The
-correct code to color all note heads red is
-
-@lilypond[quote,verbatim,relative=2]
-\new Staff {
- \override Staff.NoteHead #'color = #red
- a
-}
-@end lilypond
-
-As a second example, if a @code{\relative} command is placed inside
-a @code{\repeat} command two staves result, the second offset from
-the first, because the @code{\repeat} command generates two
-@code{\relative} blocks, which each implicitly create @code{Staff}
-and @code{Voice} blocks.
-
-@lilypond[quote,verbatim]
-\repeat unfold 2 \relative { c d e f }
-@end lilypond
-
-The correct way is to reverse the @code{\repeat} and
-@code{\relative} commands, like this:
-
-@lilypond[quote,verbatim]
-\relative {
- \repeat unfold 2 { c d e f }
-}
-@end lilypond
-
-
-@node Apparent error in ../ly/init.ly
-@unnumberedsubsec Apparent error in @code{../ly/init.ly}
-
-Various obscure error messages may appear about syntax errors in
-@code{../ly/init.ly} if the input file is not correctly formed,
-for example, if it does not contain correctly
-matched braces or quote signs.
-
-The most common error is a missing brace, (@code{@}}), at the end of
-a @code{score} block. Here the solution is obvious: check the
-@code{score} block is correctly terminated. The correct structure
-of an input file is described in @rlearning{How LilyPond input files work}.
-Using an editor which automatically highlights matching brackets and
-braces is helpful to avoid such errors.
-
-A second common cause is no white space between the last syllable
-of a lyrics block and the terminating brace, (@code{@}}). Without
-this separation the brace is taken to be part of the syllable. It
-is always advisable to ensure there is white space before and after
-@emph{every} brace. For the importance of this when using lyrics,
-see @ruser{Lyrics explained}.
-
-This error message can also appear if a terminating quote sign,
-(@code{"}), is omitted. In this case an accompanying error message
-@c keep "-matching straight in fancy editors
-should give a line number close to the line in error. The
-mismatched quote will usually be on the line one or two above.
-
-@node Error message Unbound variable %
-@unnumberedsubsec Error message Unbound variable %
-
-This error message will appear at the bottom of the console
-output or log file together with a @qq{GUILE signalled an error ...}
-message every time a Scheme routine is called which (invalidly)
-contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
-
-LilyPond comments begin with a percent sign, (@code{%}), and must
-not be used within Scheme routines. Scheme comments begin with a
-semi-colon, (@code{;}).
-
-@node Error message FT_Get_Glyph_Name
-@unnumberedsubsec Error message FT_Get_Glyph_Name
-
-This error messages appears in the console output or log file if
-an input file contains a non-ASCII character and was not saved in
-UTF-8 encoding. For details, see @ruser{Text encoding}.
-
-
-@node Point and click
-@section Point and click
-
-@cindex point and click
-
-Point and click lets you find notes in the input by clicking on them
-in the PDF viewer. This makes it easier to find input that causes
-some error in the sheet music.
-
-When this functionality is active, LilyPond adds hyperlinks to the PDF
-file. These hyperlinks are sent to the web-browser, which opens a
-text-editor with the cursor in the right place.
-
-To make this chain work, you should configure your PDF viewer to
-follow hyperlinks using the @file{lilypond-invoke-editor} script
-supplied with LilyPond.
-
-For Xpdf on UNIX, the following should be present in
-@file{xpdfrc}@footnote{On UNIX, this file is found either in
-@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
-
-@example
-urlCommand "lilypond-invoke-editor %s"
-@end example
-
-The program @file{lilypond-invoke-editor} is a small helper
-program. It will invoke an editor for the special @code{textedit}
-URIs, and run a web browser for others. It tests the environment
-variable @code{EDITOR} for the following patterns,
-
-@table @code
-@item emacs
- this will invoke
-@example
-emacsclient --no-wait +@var{line}:@var{column} @var{file}
-@end example
-@item vim
- this will invoke
-@example
-gvim --remote +:@var{line}:norm@var{char} @var{file}
-@end example
-
-@item nedit
-this will invoke
-@example
- nc -noask +@var{line} @var{file}'
-@end example
-@end table
-
-The environment variable @code{LYEDITOR} is used to override this. It
-contains the command line to start the editor, where @code{%(file)s},
-@code{%(column)s}, @code{%(line)s} is replaced with the file, column
-and line respectively. The setting
-
-@example
-emacsclient --no-wait +%(line)s:%(column)s %(file)s
-@end example
-
-@noindent
-for @code{LYEDITOR} is equivalent to the standard emacsclient
-invocation.
-
-
-@cindex file size, output
-
-The point and click links enlarge the output files significantly. For
-reducing the size of PDF and PS files, point and click may be switched
-off by issuing
-
-@example
-\pointAndClickOff
-@end example
-
-@noindent
-in a @file{.ly} file. Point and click may be explicitly enabled with
-
-@example
-\pointAndClickOn
-@end example
-
-Alternately, you may disable point and click with a command-line
-option:
-
-@example
-lilypond -dno-point-and-click file.ly
-@end example
-
-@warning{You should always turn off point and click in any LilyPond
-files to be distributed to avoid including path information about
-your computer in the .pdf file, which can pose a security risk.}
-@node Text editor support
-@section Text editor support
-
-@cindex editors
-@cindex vim
-@cindex emacs
-@cindex modes, editor
-@cindex syntax coloring
-@cindex coloring, syntax
-
-There is support for different text editors for LilyPond.
-
-@menu
-* Emacs mode::
-* Vim mode::
-* Other editors::
-@end menu
-
-@node Emacs mode
-@unnumberedsubsec Emacs mode
-
-Emacs has a @file{lilypond-mode}, which provides keyword
-autocompletion, indentation, LilyPond specific parenthesis matching
-and syntax coloring, handy compile short-cuts and reading LilyPond
-manuals using Info. If @file{lilypond-mode} is not installed on your
-platform, see below.
-
-An Emacs mode for entering music and running LilyPond is contained in
-the source archive in the @file{elisp} directory. Do @command{make
-install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
-should be placed to @var{load-path}@file{/site-start.d/} or appended
-to your @file{~/.emacs} or @file{~/.emacs.el}.
-
-As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
-your @var{load-path} by appending the following line (as modified) to your
-@file{~/.emacs}
-
-@c any reason we do not advise: (push "~/site-lisp" load-path)
-@example
-(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
-@end example
-
-
-@node Vim mode
-@unnumberedsubsec Vim mode
-
-For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied,
-along with syntax coloring tools. A Vim mode for entering music and
-running LilyPond is contained in the source archive in @code{$VIM}
-directory.
-
-The LilyPond file type is detected if the file
-@file{~/.vim/filetype.vim} has the following content
-
-@example
-if exists("did_load_filetypes")
- finish
-endif
-augroup filetypedetect
- au! BufNewFile,BufRead *.ly,*.ily setf lilypond
-augroup END
-@end example
-
-Please include this path by appending the following line to your
-@file{~/.vimrc}
-
-@example
-set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
-@end example
-
-@noindent
-where $@{LILYPOND_VERSION@} is your LilyPond version. If LilyPond was not
-installed in @file{/usr/local/}, then change this path accordingly.
-
-
-@node Other editors
-@unnumberedsubsec Other editors
-
-Other editors (both text and graphical) support LilyPond, but
-their special configuration files are not distributed with
-LilyPond. Consult their documentation for more information. Such
-editors are listed in @rgeneral{Alternate editors}.
-
+++ /dev/null
-@c -*- coding: utf-8; mode: texinfo; -*-
-
-@ignore
- Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-
- When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
-@end ignore
-
-@c \version "2.12.0"
-
-@node Suggestions for writing files
-@chapter Suggestions for writing files
-
-Now you're ready to begin writing larger LilyPond input files --
-not just the little examples in the tutorial, but whole pieces.
-But how should you go about doing it?
-
-As long as LilyPond can understand your input files and produce
-the output that you want, it doesn't matter what your input files
-look like. However, there are a few other things to consider when
-writing LilyPond input files.
-
-@itemize
-@item What if you make a mistake? The structure of a LilyPond
-file can make certain errors easier (or harder) to find.
-
-@item What if you want to share your input files with somebody
-else? In fact, what if you want to alter your own input files in
-a few years? Some LilyPond input files are understandable at
-first glance; others may leave you scratching your head
-for an hour.
-
-@item What if you want to upgrade your LilyPond file for use
-with a later version of LilyPond? The input syntax changes
-occasionally as LilyPond improves. Most changes can be
-done automatically with @code{convert-ly}, but some changes
-might require manual assistance. LilyPond input files can be
-structured in order to be easier (or harder) to update.
-
-@end itemize
-
-@menu
-* General suggestions::
-* Typesetting existing music::
-* Large projects::
-* Troubleshooting::
-* Make and Makefiles::
-@end menu
-
-
-@node General suggestions
-@section General suggestions
-
-Here are a few suggestions that can help you to avoid or fix
-problems:
-
-@itemize
-@item @strong{Include @code{\version} numbers in every file}. Note that all
-templates contain @code{\version} information. We
-highly recommend that you always include the @code{\version}, no matter
-how small your file is. Speaking from personal experience, it's
-quite frustrating to try to remember which version of LilyPond you were
-using a few years ago. @command{convert-ly} requires you to declare
-which version of LilyPond you used.
-
-@item @strong{Include checks}: @ruser{Bar and bar number checks},
-@ruser{Octave checks}. If you include checks every so often, then
-if you make a mistake, you can pinpoint it quicker. How often is
-@q{every so often}? It depends on the complexity of the music.
-For very simple music, perhaps just once or twice. For very
-complex music, perhaps every bar.
-
-@item @strong{One bar per line of text}. If there is anything complicated,
-either in the music
-itself or in the output you desire, it's often good to write only one bar
-per line. Saving screen space by cramming eight bars per line just isn't
-worth it if you have to @q{debug} your input files.
-
-@item @strong{Comment your input files}. Use either bar numbers
-(every so often) or
-references to musical themes (@q{second theme in violins,} @q{fourth
-variation,} etc.). You may not need comments when you're writing the piece
-for the first time, but if you want to go back to change something two or
-three years later, or if you pass the source over to a friend, it will
-be much more
-challenging to determine your intentions or how your file is structured if
-you didn't comment the file.
-
-@item @strong{Indent your braces}. A lot of problems are caused by an
-imbalance
-in the number of @code{@{} and @code{@}}.
-
-@item @strong{Explicitly add durations} at the beginnings of sections
-and variables. If you specify @code{c4 d e} at the beginning of a
-phrase (instead of just @code{c d e}) you can save yourself some
-problems if you rearrange your music later.
-
-@item @strong{Separate tweaks} from music definitions. See
-@rlearning{Saving typing with variables and functions}, and
-@rlearning{Style sheets}.
-
-@end itemize
-
-
-@node Typesetting existing music
-@section Typesetting existing music
-
-If you are entering music from an existing score (i.e., typesetting a
-piece of existing sheet music),
-
-@itemize
-
-@item Enter the manuscript (the physical copy of the music) into
-LilyPond one system at a time (but still only one bar per line of text),
-and check each system when you finish it. You may use the
-@code{showLastLength} or @code{showFirstLength} properties to speed up
-processing -- see @ruser{Skipping corrected music}.
-
-@item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
-in the input file whenever the manuscript has a line break. This
-makes it much easier to compare the LilyPond music to the original
-music. When you are finished proofreading your score, you may
-define @code{mBreak = @{ @}} to remove all those line breaks. This
-will allow LilyPond to place line breaks wherever it feels are
-best.
-
-@item When entering a part for a transposing instrument into a
-variable, it is recommended that the notes are wrapped in
-
-@example
-\transpose c natural-pitch @{...@}
-@end example
-
-@noindent
-(where @code{natural-pitch} is the open pitch of the instrument) so
-that the music in the variable is effectively in C. You can transpose
-it back again when the variable is used, if required, but you might
-not want to (e.g., when printing a score in concert pitch,
-converting a trombone part from treble to bass clef, etc.)
-Mistakes in transpositions are less likely if all the music in
-variables is at a consistent pitch.
-
-Also, only ever transpose to/from C. That means that the only other
-keys you will use are the natural pitches of the instruments - bes
-for a B-flat trumpet, aes for an A-flat clarinet, etc.
-
-@end itemize
-
-
-@node Large projects
-@section Large projects
-
-When working on a large project, having a clear structure to your
-lilypond input files becomes vital.
-
-@itemize
-
-@item @strong{Use a variable for each voice}, with a minimum of
-structure inside the definition. The structure of the
-@code{\score} section is the most likely thing to change;
-the @code{violin} definition is extremely unlikely to change
-in a new version of LilyPond.
-
-@example
-violin = \relative c'' @{
-g4 c'8. e16
-@}
-...
-\score @{
- \new GrandStaff @{
- \new Staff @{
- \violin
- @}
- @}
-@}
-@end example
-
-@item @strong{Separate tweaks from music definitions}. This
-point was made previously, but for large
-projects it is absolutely vital. We might need to change
-the definition of @code{fthenp}, but then we only need
-to do this once, and we can still avoid touching anything
-inside @code{violin}.
-
-@example
-fthenp = _\markup@{
- \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
-violin = \relative c'' @{
-g4\fthenp c'8. e16
-@}
-@end example
-
-@end itemize
-
-
-@node Troubleshooting
-@section Troubleshooting
-
-Sooner or later, you will write a file that LilyPond cannot
-compile. The messages that LilyPond gives may help
-you find the error, but in many cases you need to do some
-investigation to determine the source of the problem.
-
-The most powerful tools for this purpose are the
-single line comment (indicated by @code{%}) and the block
-comment (indicated by @code{%@{ ... %@}}). If you don't
-know where a problem is, start commenting out huge portions
-of your input file. After you comment out a section, try
-compiling the file again. If it works, then the problem
-must exist in the portion you just commented. If it doesn't
-work, then keep on commenting out material until you have
-something that works.
-
-In an extreme case, you might end up with only
-
-@example
-\score @{
- <<
- % \melody
- % \harmony
- % \bass
- >>
- \layout@{@}
-@}
-@end example
-
-@noindent
-(in other words, a file without any music)
-
-If that happens, don't give up. Uncomment a bit -- say,
-the bass part -- and see if it works. If it doesn't work,
-then comment out all of the bass music (but leave
-@code{\bass} in the @code{\score} uncommented.
-
-@example
-bass = \relative c' @{
-%@{
- c4 c c c
- d d d d
-%@}
-@}
-@end example
-
-Now start slowly uncommenting more and more of the
-@code{bass} part until you find the problem line.
-
-Another very useful debugging technique is constructing
-@rgeneral{Tiny examples}.
-
-
-@node Make and Makefiles
-@section Make and Makefiles
-
-@cindex makefiles
-@cindex make
-
-Pretty well all the platforms Lilypond can run on support a software
-facility called @code{make}. This software reads a special file called a
-@code{Makefile} that defines what files depend on what others and what
-commands you need to give the operating system to produce one file from
-another. For example the makefile would spell out how to produce
-@code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
-running Lilypond.
-
-There are times when it is a good idea to create a @code{Makefile}
-for your project, either for your own convenience or
-as a courtesy to others who might have access to your source files.
-This is true for very large projects with many included files and
-different output options (e.g. full score, parts, conductor's
-score, piano reduction, etc.), or for projects that
-require difficult commands to build them (such as
-@code{lilypond-book} projects). Makefiles vary greatly in
-complexity and flexibility, according to the needs and skills of
-the authors. The program GNU Make comes installed on GNU/Linux
-distributions and on MacOS X, and it is also available for Windows.
-
-See the @strong{GNU Make Manual} for full details on using
-@code{make}, as what follows here gives only a glimpse of what it
-can do.
-
-The commands to define rules in a makefile differ
-according to platform; for instance the various forms of Linux and
-MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
-MacOS X, you need to configure the system to use the command-line
-intepreter. Here are some example makefiles, with versions for both
-Linux/MacOS and Windows.
-
-The first example is for an orchestral work in four
-movements with a directory structure as follows:
-
-@example
-Symphony/
-|-- MIDI/
-|-- Makefile
-|-- Notes/
-| |-- cello.ily
-| |-- figures.ily
-| |-- horn.ily
-| |-- oboe.ily
-| |-- trioString.ily
-| |-- viola.ily
-| |-- violinOne.ily
-| `-- violinTwo.ily
-|-- PDF/
-|-- Parts/
-| |-- symphony-cello.ly
-| |-- symphony-horn.ly
-| |-- symphony-oboes.ly
-| |-- symphony-viola.ly
-| |-- symphony-violinOne.ly
-| `-- symphony-violinTwo.ly
-|-- Scores/
-| |-- symphony.ly
-| |-- symphonyI.ly
-| |-- symphonyII.ly
-| |-- symphonyIII.ly
-| `-- symphonyIV.ly
-`-- symphonyDefs.ily
-@end example
-
-The @code{.ly} files in the @code{Scores} and
-@code{Parts} directories get their notes from @code{.ily}
-files in the @code{Notes} directory:
-
-@example
-%%% top of file "symphony-cello.ly"
-\include ../definitions.ily
-\include ../Notes/cello.ily
-@end example
-
-The makefile will have targets of @code{score} (entire piece in
-full score), @code{movements} (individual movements in full score),
-and @code{parts} (individual parts for performers). There
-is also a target @code{archive} that will create a tarball of
-the source files, suitable for sharing via web or email. Here is
-the makefile for GNU/Linux or MacOS X. It should be saved with the
-name @code{Makefile} in the top directory of the project:
-
-@warning{When a target or pattern rule is defined, the
-subsequent lines must begin with tabs, not spaces.}
-
-@example
-# the name stem of the output files
-piece = symphony
-# determine how many processors are present
-CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
-# The command to run lilypond
-LILY_CMD = lilypond -ddelete-intermediate-files \
- -dno-point-and-click -djob-count=$(CPU_CORES)
-
-# The suffixes used in this Makefile.
-.SUFFIXES: .ly .ily .pdf .midi
-
-# Input and output files are searched in the directories listed in
-# the VPATH variable. All of them are subdirectories of the current
-# directory (given by the GNU make variable `CURDIR').
-VPATH = \
- $(CURDIR)/Scores \
- $(CURDIR)/PDF \
- $(CURDIR)/Parts \
- $(CURDIR)/Notes
-
-# The pattern rule to create PDF and MIDI files from a LY input file.
-# The .pdf output files are put into the `PDF' subdirectory, and the
-# .midi files go into the `MIDI' subdirectory.
-%.pdf %.midi: %.ly
- $(LILY_CMD) $<; \ # this line begins with a tab
- if test -f "$*.pdf"; then \
- mv "$*.pdf" PDF/; \
- fi; \
- if test -f "$*.midi"; then \
- mv "$*.midi" MIDI/; \
- fi
-
-notes = \
- cello.ily \
- horn.ily \
- oboe.ily \
- viola.ily \
- violinOne.ily \
- violinTwo.ily
-
-# The dependencies of the movements.
-$(piece)I.pdf: $(piece)I.ly $(notes)
-$(piece)II.pdf: $(piece)II.ly $(notes)
-$(piece)III.pdf: $(piece)III.ly $(notes)
-$(piece)IV.pdf: $(piece)IV.ly $(notes)
-
-# The dependencies of the full score.
-$(piece).pdf: $(piece).ly $(notes)
-
-# The dependencies of the parts.
-$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
-$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
-$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
-$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
-$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
-$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
-
-# Type `make score' to generate the full score of all four
-# movements as one file.
-.PHONY: score
-score: $(piece).pdf
-
-# Type `make parts' to generate all parts.
-# Type `make foo.pdf' to generate the part for instrument `foo'.
-# Example: `make symphony-cello.pdf'.
-.PHONY: parts
-parts: $(piece)-cello.pdf \
- $(piece)-violinOne.pdf \
- $(piece)-violinTwo.pdf \
- $(piece)-viola.pdf \
- $(piece)-oboes.pdf \
- $(piece)-horn.pdf
-
-# Type `make movements' to generate files for the
-# four movements separately.
-.PHONY: movements
-movements: $(piece)I.pdf \
- $(piece)II.pdf \
- $(piece)III.pdf \
- $(piece)IV.pdf
-
-all: score parts movements
-
-archive:
- tar -cvvf stamitz.tar \ # this line begins with a tab
- --exclude=*pdf --exclude=*~ \
- --exclude=*midi --exclude=*.tar \
- ../Stamitz/*
-@end example
-
-
-There are special complications on the Windows platform. After
-downloading and installing GNU Make for Windows, you must set the
-correct path in the system's environment variables so that the
-DOS shell can find the Make program. To do this, right-click on
-"My Computer," then choose @code{Properties} and
-@code{Advanced}. Click @code{Environment Variables}, and then
-in the @code{System Variables} pane, highlight @code{Path}, click
-@code{edit}, and add the path to the GNU Make executable file, which
- will look something like this:
-
-@example
-C:\Program Files\GnuWin32\bin
-@end example
-
-The makefile itself has to be altered to handle different shell
-commands and to deal with spaces that are present
-in some default system directories. The @code{archive} target
-is eliminated since Windows does not have the @code{tar} command,
-and Windows also has a different default extension for midi files.
-
-
-@example
-## WINDOWS VERSION
-##
-piece = symphony
-LILY_CMD = lilypond -ddelete-intermediate-files \
- -dno-point-and-click \
- -djob-count=$(NUMBER_OF_PROCESSORS)
-
-#get the 8.3 name of CURDIR (workaround for spaces in PATH)
-workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
- do @@echo %%~sb)
-
-.SUFFIXES: .ly .ily .pdf .mid
-
-VPATH = \
- $(workdir)/Scores \
- $(workdir)/PDF \
- $(workdir)/Parts \
- $(workdir)/Notes
-
-%.pdf %.mid: %.ly
- $(LILY_CMD) $< # this line begins with a tab
- if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab
- if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab
-
-notes = \
- cello.ily \
- figures.ily \
- horn.ily \
- oboe.ily \
- trioString.ily \
- viola.ily \
- violinOne.ily \
- violinTwo.ily
-
-$(piece)I.pdf: $(piece)I.ly $(notes)
-$(piece)II.pdf: $(piece)II.ly $(notes)
-$(piece)III.pdf: $(piece)III.ly $(notes)
-$(piece)IV.pdf: $(piece)IV.ly $(notes)
-
-$(piece).pdf: $(piece).ly $(notes)
-
-$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
-$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
-$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
-$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
-$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
-$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
-
-.PHONY: score
-score: $(piece).pdf
-
-.PHONY: parts
-parts: $(piece)-cello.pdf \
- $(piece)-violinOne.pdf \
- $(piece)-violinTwo.pdf \
- $(piece)-viola.pdf \
- $(piece)-oboes.pdf \
- $(piece)-horn.pdf
-
-.PHONY: movements
-movements: $(piece)I.pdf \
- $(piece)II.pdf \
- $(piece)III.pdf \
- $(piece)IV.pdf
-
-all: score parts movements
-@end example
-
-
-The next Makefile is for a @command{lilypond-book} document done in
-LaTeX. This project has an index, which requires that the
-@command{latex} command be run twice to update links. Output files are
-all stored in the @code{out} directory for .pdf output and in the
-@code{htmlout} directory for the html output.
-
-@example
-SHELL=/bin/sh
-FILE=myproject
-OUTDIR=out
-WEBDIR=htmlout
-VIEWER=acroread
-BROWSER=firefox
-LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
-LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
-PDF=cd $(OUTDIR) && pdflatex $(FILE)
-HTML=cd $(WEBDIR) && latex2html $(FILE)
-INDEX=cd $(OUTDIR) && makeindex $(FILE)
-PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
-
-all: pdf web keep
-
-pdf:
- $(LILYBOOK_PDF) # begin with tab
- $(PDF) # begin with tab
- $(INDEX) # begin with tab
- $(PDF) # begin with tab
- $(PREVIEW) # begin with tab
-
-web:
- $(LILYBOOK_HTML) # begin with tab
- $(HTML) # begin with tab
- cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab
- $(BROWSER) $(FILE)/$(FILE).html & # begin with tab
-
-keep: pdf
- cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab
-
-clean:
- rm -rf $(OUTDIR) # begin with tab
-
-web-clean:
- rm -rf $(WEBDIR) # begin with tab
-
-archive:
- tar -cvvf myproject.tar \ # begin this line with tab
- --exclude=out/* \
- --exclude=htmlout/* \
- --exclude=myproject/* \
- --exclude=*midi \
- --exclude=*pdf \
- --exclude=*~ \
- ../MyProject/*
-@end example
-
-TODO: make this thing work on Windows
-
-The previous makefile does not work on Windows. An alternative
-for Windows users would be to create a simple batch file
-containing the build commands. This will not
-keep track of dependencies the way a makefile does, but it at
-least reduces the build process to a single command. Save the
-following code as @command{build.bat} or @command{build.cmd}.
-The batch file can be run at the DOS prompt or by simply
-double-clicking its icon.
-
-@example
-lilypond-book --output=out --pdf myproject.lytex
-cd out
-pdflatex myproject
-makeindex myproject
-pdflatex myproject
-cd ..
-copy out\myproject.pdf MyProject.pdf
-@end example
-
-
-@seealso
-Application Usage:
-FIXME
-@c @rprogram{Setup for MacOS X},
-@rprogram{Command-line usage},
-@rprogram{lilypond-book}
+++ /dev/null
-@c -*- coding: utf-8; mode: texinfo; -*-
-
-@ignore
- Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-
- When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
-@end ignore
-
-@c \version "2.12.0"
-
-
-@node Updating files with convert-ly
-@chapter Updating files with @command{convert-ly}
-
-@cindex Updating a LilyPond file
-@cindex convert-ly
-
-The LilyPond input syntax is routinely changed to simplify it or improve
-it in different ways. As a side effect of this, the LilyPond interpreter
-often is no longer compatible with older input files. To remedy this,
-the program @command{convert-ly} can be used to deal with most of the
-syntax changes between LilyPond versions.
-
-@menu
-* Why does the syntax change?::
-* Invoking convert-ly::
-* Command line options for convert-ly::
-* Problems running convert-ly::
-* Manual conversions::
-@end menu
-
-
-@node Why does the syntax change?
-@section Why does the syntax change?
-
-@cindex convert-ly
-@cindex updating old input files
-
-The LilyPond input syntax occasionally changes. As LilyPond
-itself improves, the syntax (input language) is modified
-accordingly. Sometimes these changes are made to make the input
-easier to read and write or sometimes the changes are made to
-accommodate new features of LilyPond.
-
-For example, all @code{\paper} and @code{\layout} property names
-are supposed to be written in the form @code{first-second-third}.
-However, in version 2.11.60, we noticed that the
-@code{printallheaders} property did not follow this convention.
-Should we leave it alone (confusing new users who must deal with
-an inconsistent input format), or change it (annoying old users
-with existing scores)? In this case, we decided to change the
-name to @code{print-all-headers}. Fortunately, this change can be
-automated with our @command{convert-ly} tool.
-
-Unfortunately, @code{convert-ly} cannot handle all input changes.
-For example, in LilyPond 2.4 and earlier, accents and non-English
-letters were entered using LaTeX -- displaying the French word for
-Christmas was entered as @code{No\"el}. But in LilyPond
-@c keep "-matching straight in fancy editors
-2.6 and above, the special @code{ë} must be entered directly into
-the LilyPond file as an UTF-8 character. @code{convert-ly} cannot
-change all the LaTeX special characters into UTF-8 characters; you
-must manually update your old LilyPond input files.
-
-
-@node Invoking convert-ly
-@section Invoking @command{convert-ly}
-
-@command{convert-ly} uses @code{\version} statements in the input
-file to detect the old version number. In most cases, to upgrade
-your input file it is sufficient to run
-
-@example
-convert-ly -e myfile.ly
-@end example
-
-@noindent
-in the directory containing the file. This will upgrade
-@code{myfile.ly} in-place and preserve the original file in
-@code{myfile.ly~}.
-
-@warning{@command{convert-ly} always converts up to the last
-syntax change handled by it. This means that the @code{\version}
-number left in the file is usually lower than the version of
-@command{convert-ly} itself.}
-
-To convert all the input files in a directory together use
-
-@example
-convert-ly -e *.ly
-@end example
-
-Alternatively, if you want to specify a different name for the
-upgraded file, preserving the original file and name unchanged,
-use
-
-@example
-convert-ly myfile.ly > mynewfile.ly
-@end example
-
-The program will list the version numbers for which conversions
-have been made. If no version numbers are listed the file is
-already up to date.
-
-MacOS@tie{}X users may execute these commands under the menu entry
-@code{Compile > Update syntax}.
-
-Windows users should enter these commands in a Command Prompt
-window, which is usually found under
-@code{Start > Accessories > Command Prompt}.
-
-
-@node Command line options for convert-ly
-@section Command line options for @command{convert-ly}
-
-The program is invoked as follows:
-
-@example
-convert-ly [@var{option}]@dots{} @var{filename}@dots{}
-@end example
-
-
-The following options can be given:
-
-@table @code
-@item -e,--edit
-Apply the conversions direct to the input file, modifying it
-in-place.
-
-@item -f,--from=@var{from-patchlevel}
-Set the version to convert from. If this is not set, @command{convert-ly}
-will guess this, on the basis of @code{\version} strings in the file.
-E.g. @code{--from=2.10.25}
-
-@item -n,--no-version
-Normally, @command{convert-ly} adds a @code{\version} indicator
-to the output. Specifying this option suppresses this.
-
-@item -s, --show-rules
-Show all known conversions and exit.
-
-@item --to=@var{to-patchlevel}
-Set the goal version of the conversion. It defaults to the latest
-available version. E.g. @code{--to=2.12.2}
-
-@item -h, --help
-Print usage help.
-@end table
-
-To upgrade LilyPond fragments in texinfo files, use
-
-@example
-convert-ly --from=... --to=... --no-version *.itely
-@end example
-
-To see the changes in the LilyPond syntax between two versions, use
-
-@example
-convert-ly --from=... --to=... -s
-@end example
-
-
-@node Problems running convert-ly
-@section Problems running @code{convert-ly}
-
-When running convert-ly in a Command Prompt window under Windows
-on a file which has spaces in the filename or in the path to it,
-it is necessary to surround the entire input file name with three
-(!) sets of double quotes:
-
-@example
-convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
-@end example
-
-If the simple @command{convert-ly -e *.ly} command fails because the
-expanded command line becomes too long, the @command{convert-ly}
-command may be placed in a loop instead. This example for UNIX
-will upgrade all @code{.ly} files in the current directory
-
-@example
-for f in *.ly; do convert-ly -e $f; done;
-@end example
-
-In the Windows Command Prompt window the corresponding command is
-
-@example
-for %x in (*.ly) do convert-ly -e """%x"""
-@end example
-
-Not all language changes are handled. Only one output option can be
-specified. Automatically updating scheme and LilyPond scheme
-interfaces is quite unlikely; be prepared to tweak scheme code
-manually.
-
-
-@node Manual conversions
-@section Manual conversions
-
-In theory, a program like @command{convert-ly} could handle any
-syntax change. After all, a computer program interprets the old
-version and the new version, so another computer program can
-translate one file into another@footnote{At least, this is
-possible in any LilyPond file which does not contain scheme. If
-there is scheme in the file, then the LilyPond file contains a
-Turing-complete language, and we run into problems with the famous
-@qq{Halting Problem} in computer science.}.
-
-However, the LilyPond project has limited resources: not all
-conversions are performed automatically. Below is a list of known
-problems.
-
-
-@verbatim
-1.6->2.0:
- Doesn't always convert figured bass correctly, specifically things like {<
->}. Mats' comment on working around this:
- To be able to run convert-ly
- on it, I first replaced all occurrences of '{<' to some dummy like '{#'
- and similarly I replaced '>}' with '&}'. After the conversion, I could
- then change back from '{ #' to '{ <' and from '& }' to '> }'.
- Doesn't convert all text markup correctly. In the old markup syntax,
- it was possible to group a number of markup commands together within
-parentheses, e.g.
- -#'((bold italic) "string")
- This will incorrectly be converted into
- -\markup{{\bold italic} "string"}
- instead of the correct
- -\markup{\bold \italic "string"}
-2.0->2.2:
- Doesn't handle \partcombine
- Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
-stanzas.
-2.0->2.4:
- \magnify isn't changed to \fontsize.
- - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
- remove-tag isn't changed.
- - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
- first-page-number isn't changed.
- - first-page-number no => print-first-page-number = ##f
- Line breaks in header strings aren't converted.
- - \\\\ as line break in \header strings => \markup \center-align <
- "First Line" "Second Line" >
- Crescendo and decrescendo terminators aren't converted.
- - \rced => \!
- - \rc => \!
-2.2->2.4:
- \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
-converted.
-2.4.2->2.5.9
- \markup{ \center-align <{ ... }> } should be converted to:
- \markup{ \center-align {\line { ... }} }
- but now, \line is missing.
-2.4->2.6
- Special LaTeX characters such as $~$ in text are not converted to UTF8.
-2.8
- \score{} must now begin with a music expression. Anything else
- (particularly \header{}) must come after the music.
-@end verbatim
-
-
--- /dev/null
+\input texinfo @c -*- coding: utf-8; mode: texinfo; -*-
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
+@setfilename lilypond-usage.info
+@settitle LilyPond Application Usage
+@documentencoding UTF-8
+@documentlanguage en
+@afourpaper
+
+@macro manualIntro
+This file explains how to execute the programs distributed with
+LilyPond version @version{}. In addition, it suggests some
+@qq{best practices} for efficient usage.
+@end macro
+
+@macro copyrightDeclare
+Copyright @copyright{}
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+by the authors.
+@end macro
+
+@set FDL
+@include macros.itexi
+
+
+@c don't remove this comment.
+@ignore
+@omfcreator Han-Wen Nienhuys, Jan Nieuwenhuizen and Graham Percival
+@omfdescription Application Usage of the LilyPond music engraving system
+@omftype program usage
+@omfcategory Applications|Publishing
+@omflanguage English
+@end ignore
+
+
+@lilyTitlePage{Usage}
+
+
+@c TOC -- non-tex
+@ifnottex
+
+@c maybe add a "Tasks" or "Specific tasks" or something like
+@c that, after Suggestions -gp
+@menu
+* Running lilypond:: Operation.
+* Updating files with convert-ly:: Updating input files.
+* lilypond-book:: Integrating text and music.
+* Converting from other formats:: Converting to lilypond source format.
+* Suggestions for writing files:: Best practices and effective bug-fixing.
+
+Appendices
+
+* GNU Free Documentation License:: License of this document.
+* LilyPond index::
+@end menu
+
+@docMain
+@end ifnottex
+
+
+@contents
+
+
+@include usage/running.itely
+@include usage/updating.itely
+@include usage/lilypond-book.itely
+@include usage/converters.itely
+@include usage/suggestions.itely
+
+@include fdl.itexi
+
+@node LilyPond index
+@appendix LilyPond index
+
+@printindex cp
+
+@bye
--- /dev/null
+depth = ../..
+
+LOCALSTEPMAKE_TEMPLATES = ly
+
+LATEX_FILES =$(call src-wildcard,*.latex)
+EXTRA_DIST_FILES = $(LATEX_FILES)
+
+include $(depth)/make/stepmake.make
+
+
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
+@c \version "2.12.0"
+
+@node Converting from other formats
+@chapter Converting from other formats
+
+Music can be entered also by importing it from other formats. This
+chapter documents the tools included in the distribution to do so.
+There are other tools that produce LilyPond input, for example GUI
+sequencers and XML converters. Refer to the
+@uref{http://@/lilypond@/.org,website} for more details.
+
+These are separate programs from @command{lilypond} itself, and are
+run on the command line; see @ref{Command-line usage} for more
+information. If you have MacOS 10.3 or 10.4 and you have trouble
+running some of these scripts, e.g. @code{convert-ly}, see
+@rgeneral{MacOS X}.
+
+
+@knownissues
+We unfortunately do not have the resources to maintain these
+programs; please consider them @qq{as-is}. Patches are appreciated, but
+bug reports will almost certainly not be resolved.
+
+@menu
+* Invoking midi2ly:: Importing MIDI.
+* Invoking musicxml2ly:: Importing MusicXML.
+* Invoking abc2ly:: Importing ABC.
+* Invoking etf2ly:: Importing Finale.
+* Other formats::
+@end menu
+
+
+
+@node Invoking midi2ly
+@section Invoking @command{midi2ly}
+
+@cindex MIDI
+
+@command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
+file.
+
+MIDI (Music Instrument Digital Interface) is a standard for digital
+instruments: it specifies cabling, a serial protocol and a file
+format. The MIDI file format is a de facto standard format for
+exporting music from other programs, so this capability may come in
+useful when importing files from a program that has a converter for a
+direct format.
+
+@command{midi2ly} converts tracks into @rinternals{Staff} and
+channels into @rinternals{Voice} contexts. Relative mode is used
+for pitches, durations are only written when necessary.
+
+It is possible to record a MIDI file using a digital keyboard, and
+then convert it to @file{.ly}. However, human players are not
+rhythmically exact enough to make a MIDI to LY conversion trivial.
+When invoked with quantizing (@code{-s} and @code{-d} options)
+@command{midi2ly} tries to compensate for these timing errors, but is not
+very good at this. It is therefore not recommended to use @command{midi2ly}
+for human-generated midi files.
+
+
+It is invoked from the command-line as follows,
+@example
+midi2ly [@var{option}]@dots{} @var{midi-file}
+@end example
+
+Note that by @q{command-line}, we mean the command line of the
+operating system. See @ref{Converting from other formats}, for
+more information about this.
+
+The following options are supported by @command{midi2ly}.
+
+@table @code
+@item -a, --absolute-pitches
+Print absolute pitches.
+
+@item -d, --duration-quant=@var{DUR}
+Quantize note durations on @var{DUR}.
+
+@item -e, --explicit-durations
+Print explicit durations.
+
+@item -h,--help
+Show summary of usage.
+
+@item -k, --key=@var{acc}[:@var{minor}]
+Set default key. @math{@var{acc} > 0} sets number of sharps;
+@math{@var{acc} < 0} sets number of flats. A minor key is indicated by
+@code{:1}.
+
+@item -o, --output=@var{file}
+Write output to @var{file}.
+
+@item -s, --start-quant=@var{DUR}
+Quantize note starts on @var{DUR}.
+
+@item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
+Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
+
+@item -v, --verbose
+Be verbose.
+
+@item -V, --version
+Print version number.
+
+@item -w, --warranty
+Show warranty and copyright.
+
+@item -x, --text-lyrics
+Treat every text as a lyric.
+@end table
+
+
+@knownissues
+
+Overlapping notes in an arpeggio will not be correctly rendered. The
+first note will be read and the others will be ignored. Set them all
+to a single duration and add phrase markings or pedal indicators.
+
+
+@node Invoking musicxml2ly
+@section Invoking @code{musicxml2ly}
+
+@cindex MusicXML
+
+@uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
+for representing music notation.
+
+@command{musicxml2ly} extracts the notes, articulations, score structure,
+lyrics, etc. from part-wise MusicXML files, and writes them to a .ly
+file. It is invoked from the command-line.
+
+
+It is invoked from the command-line as follows,
+@example
+musicxml2ly [@var{option}]@dots{} @var{xml-file}
+@end example
+
+Note that by @q{command-line}, we mean the command line of the
+operating system. See @ref{Converting from other formats}, for
+more information about this.
+
+If the given filename is @file{-}, @command{musicxml2ly} reads input
+from the command line.
+
+The following options are supported by @command{musicxml2ly}:
+
+@table @code
+@item -a, --absolute
+convert pitches in absolute mode.
+
+@item -h,--help
+print usage and option summary.
+
+@item -l, --language=LANG
+use a different language file 'LANG.ly' and corresponding pitch names,
+e.g. 'deutsch' for deutsch.ly and German note names.
+
+@item --lxml
+use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
+
+@item --nd --no-articulation-directions
+do not convert directions (@code{^}, @code{_} or @code{-}) for
+articulations, dynamics, etc.
+
+@item --no-beaming
+do not convert beaming information, use LilyPond's automatic
+beaming instead.
+
+@item -o,--output=@var{file}
+set output filename to @var{file}. If @var{file} is @file{-}, the output
+will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
+be used.
+
+@item -r,--relative
+convert pitches in relative mode (default).
+
+@item -v,--verbose
+be verbose.
+
+@item --version
+print version information.
+
+@item -z,--compressed
+input file is a zip-compressed MusicXML file.
+@end table
+
+
+@node Invoking abc2ly
+@section Invoking @code{abc2ly}
+
+@warning{This program is not supported, and may be remove from
+future versions of LilyPond.}
+
+@cindex ABC
+
+ABC is a fairly simple ASCII based format. It is described at the ABC site:
+
+@quotation
+@uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
+@end quotation
+
+@command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
+
+@example
+abc2ly [@var{option}]@dots{} @var{abc-file}
+@end example
+
+The following options are supported by @command{abc2ly}:
+
+@table @code
+@item -b,--beams=None
+preserve ABC's notion of beams
+@item -h,--help
+this help
+@item -o,--output=@var{file}
+set output filename to @var{file}.
+@item -s,--strict
+be strict about success
+@item --version
+print version information.
+@end table
+
+There is a rudimentary facility for adding LilyPond code to the ABC
+source file. If you say:
+
+@example
+%%LY voices \set autoBeaming = ##f
+@end example
+
+This will cause the text following the keyword @q{voices} to be inserted
+into the current voice of the LilyPond output file.
+
+Similarly,
+
+@example
+%%LY slyrics more words
+@end example
+
+will cause the text following the @q{slyrics} keyword to be inserted
+into the current line of lyrics.
+
+
+@knownissues
+
+The ABC standard is not very @q{standard}. For extended features
+(e.g., polyphonic music) different conventions exist.
+
+Multiple tunes in one file cannot be converted.
+
+ABC synchronizes words and notes at the beginning of a line;
+@command{abc2ly} does not.
+
+@command{abc2ly} ignores the ABC beaming.
+
+
+@node Invoking etf2ly
+@section Invoking @command{etf2ly}
+
+@warning{This program is not supported, and may be remove from
+future versions of LilyPond.}
+
+@cindex ETF
+@cindex enigma
+@cindex Finale
+@cindex Coda Technology
+
+ETF (Enigma Transport Format) is a format used by Coda Music
+Technology's Finale product. @command{etf2ly} will convert part of an ETF
+file to a ready-to-use LilyPond file.
+
+It is invoked from the command-line as follows.
+
+@example
+etf2ly [@var{option}]@dots{} @var{etf-file}
+@end example
+
+Note that by @q{command-line}, we mean the command line of the
+operating system. See @ref{Converting from other formats}, for
+more information about this.
+
+The following options are supported by @command{etf2ly}:
+
+@table @code
+@item -h,--help
+this help
+@item -o,--output=@var{FILE}
+set output filename to @var{FILE}
+@item --version
+version information
+@end table
+
+
+@knownissues
+
+The list of articulation scripts is incomplete. Empty measures
+confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
+
+
+@node Other formats
+@section Other formats
+
+@cindex External programs, generating LilyPond files
+
+LilyPond itself does not come with support for any other formats,
+but some external tools can also generate LilyPond files. These
+are listed in @rgeneral{Alternate editors}.
+
--- /dev/null
+\documentclass[a4paper]{article}
+
+%\def\preLilyPondExample{}}
+%\def\postLilyPondExample{}
+
+
+\begin{document}
+
+\begin{lilypond}
+\relative { c' d e f g a b c }
+\end{lilypond}
+
+
+\begin[fragment]{lilypond}
+c d e
+\end{lilypond}
+
+
+% show interaction of margins lilypond+verses
+
+% outdated
+% generate standard lilypond titles
+\input titledefs.tex
+\def\preLilyPondExample{\def\mustmakelilypondtitle{}}
+
+\begin{lilypond}
+\header {
+ title = "Title"
+ subtitle = "Subtitle"
+ subsubtitle = "Subsubtitle"
+ opus = "Opus 1"
+ piece = "Piece"
+ composer = "Composer"
+ enteredby = "JCN"
+ instrument = "instrument"
+}
+\layout { linewidth = -1. }
+\relative c'' { a b c d }
+\end{lilypond}
+
+\begin{enumerate}
+\item Vers one. aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa
+\item Vers two. bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb
+\end{enumerate}
+
+\end{document}
--- /dev/null
+\documentclass[a4paper, 12pt]{article}
+% keep \documentclass on 1st line for lilypond-book auto-detection
+
+%
+% This is way too long and hairy --
+%
+%
+
+
+
+
+%\def\preLilyPondExample{}
+%\def\postLilyPondExample{}
+%\usepackage{graphics}
+%\usepackage{landscape}
+
+\begin{document}
+%uncomment this to try twocolumn mode
+%\twocolumn
+
+
+\section{LilyPond-book + LaTeX}
+
+This is an examplefile for mixing LilyPond and Latex. It is also
+used to test lilypond-book. View the source to see how it is done.
+
+A simple scale:
+
+\begin{lilypond}
+\score{
+ \relative c'{c d e f g a b c}
+}
+\end{lilypond}
+
+LilyPond-book search for the \verb|\score| command when it decides
+if the code is only a fragment. Thus, in the following code, you have
+to use \verb|fragment| option, because the comment confuses lilypond-book.
+
+\begin[fragment]{lilypond}
+c d e % \score
+\end{lilypond}
+
+There is also a shorthand version \verb|\lilypond[fragment]{c' e' g'}|:
+
+\lilypond[fragment]{c' e' g'}
+
+that is the same as writing
+\begin{verbatim}
+\begin[fragment]{lilypond}
+c' e' g'
+\end{lilypond}
+\end{verbatim}
+
+This C major
+%%\begin[staffsize=11\pt,fragment]{lilypond}
+\begin[11pt,fragment]{lilypond}
+\context Voice <<c' e' g'>>
+\end{lilypond}
+and C minor
+\lilypond[fragment,11pt]{\context Voice <<c' es' g'>>} chords are floating inside the text.
+
+\subsection{verb and verbatim}
+
+As you see, the begin/end verbatim command inside
+does not confuse lilypond-book:
+
+\verb|\begin[fragment]{lilypond}c d e\end{lilypond}|
+
+Neither does a verbatim inside verb:
+
+\verb|\begin{verbatim}\begin[fragment]{lilypond}c d e\end{lilypond}\end{verbatim}|
+
+or verb inside verbatim:
+
+\begin{verbatim}
+\verb|\begin[fragment]{lilypond}c d e\end{lilypond}|
+\end{verbatim}
+
+But this is just to stress \verb|lilypond-book|. What you need is:
+
+\verb|\lilypond[fragment]{c' d' e'}|
+
+and
+
+\begin{verbatim}
+\begin{lilypond}
+c d e
+\end{lilypond}
+\end{verbatim}
+
+\subsection{The 'verbatim' and 'intertext' option}
+This shows the verbatim option:
+\begin[fragment,verbatim, intertext="gives this music:"]{lilypond}
+c' d' e'
+\end{lilypond}
+
+\subsection{LaTeX comments}
+This is a line with lilypond code
+after the comment char % \lilypond{\context Voice <<c' e' g'>>}
+% \lilypond{\context Voice <<c' e' g'>>}
+
+If you do not see any music from the heading 'LaTeX comments' and until
+this line, then lilypond-book is handling latex comments pretty well :-)
+
+\subsection{To float or not to float}
+This music
+\begin[fragment]{lilypond}
+c' e'
+\end{lilypond}
+should be floating inside the text by using the \verb|eps| options.
+
+This music
+
+\begin[fragment]{lilypond}
+c' e'
+\end{lilypond}
+
+has also the \verb|eps| options, but is not floating because there
+are an emptry line before and after the lilypond block. That is
+correct behaviour because it follows La\TeX{} convention that an
+empty line signals a new paragraph. The \verb|eps| option
+is not necessary when you want the music in a paragraph on its own.
+
+\subsection{More examples}
+
+Itemize environment:
+\begin{itemize}
+\item
+\lilypond[11pt,fragment]{ c'} do
+\item
+\lilypond[11pt,fragment]{d'} re
+\item
+\lilypond[11pt,fragment]{e'} mi
+\item
+\lilypond[11pt,fragment]{f'} fa
+\item
+\lilypond[11pt,fragment]{g'} sol
+\end{itemize}
+
+Tables\footnote{ and footnote:
+\lilypond[11pt,fragment]{c' e' g'} }:
+\marginpar{ Yes, even as marginpar
+\lilypond[11pt,fragment]{c' d' e'} }
+
+\begin{tabular}{|l|l|r|}
+\hline
+\em Notes & \em Name \\
+\hline
+\lilypond[11pt,fragment,filename="cdur"]{\context Voice <<c' e' g'>>} & major \\
+\lilypond[11pt,fragment]{\context Voice <<c' es' g'>>} & minor \\
+\lilypond[11pt,fragment]{\context Voice <<c' es' ges'>>} & diminished \\
+\lilypond[11pt,fragment]{\context Voice <<c' e' gis'>>} & augmented \\
+\hline
+\end{tabular}
+
+\pagebreak
+
+Testing of spacing. The next music is surrounded by an empty line.
+text text text text text text text text text text text text
+text text text text text text text text text text text text
+
+\begin{lilypond}
+\score{ \relative c'{ c d e f g a b c} }
+\end{lilypond}
+
+text text text text text text text text text text text text
+text text text text text text text text text text text text
+text text text text text text text text text text text text
+
+Next has no empty lines.
+text text text text text text text text text text text text
+text text text text text text text text text text text text
+text text text text text text text text text text text text
+\begin{lilypond}
+\score{ \relative c'{ c d e f g a b c} }
+\end{lilypond}
+text text text text text text text text text text text text
+text text text text text text text text text text text text
+
+%% need to use an -I ../../../input/test to find the file
+%% \lilypondfile{tie.ly}
+
+\end{document}
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
+@c \version "2.12.0"
+
+@c Note: keep this node named so that `info lilypond-book' brings you here.
+@node lilypond-book
+@chapter Running @command{lilypond-book}
+
+If you want to add pictures of music to a document, you can simply do it
+the way you would do with other types of pictures. The pictures are
+created separately, yielding PostScript output or PNG images, and those
+are included into a @LaTeX{} or HTML document.
+
+@command{lilypond-book} provides a way to automate this process: This
+program extracts snippets of music from your document, runs
+@command{lilypond} on them, and outputs the document with pictures
+substituted for the music. The line width and font size definitions for
+the music are adjusted to match the layout of your document.
+
+This is a separate program from @command{lilypond} itself, and is run
+on the command line; for more information, see @ref{Command-line
+usage}. If you have MacOS 10.3 or 10.4 and you have trouble running
+@code{lilypond-book}, see @rgeneral{MacOS X}.
+
+This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
+documents.
+
+@cindex texinfo
+@cindex latex
+@cindex texinfo
+@cindex texi
+@cindex html
+@cindex docbook
+@cindex documents, adding music to
+@cindex HTML, music in
+@cindex Texinfo, music in
+@cindex DocBook, music in
+@cindex @LaTeX{}, music in
+
+@menu
+* An example of a musicological document::
+* Integrating music and text::
+* Music fragment options::
+* Invoking lilypond-book::
+* Filename extensions::
+* lilypond-book templates::
+* Alternate methods of mixing text and music::
+@end menu
+
+
+@node An example of a musicological document
+@section An example of a musicological document
+
+@cindex musicology
+Some texts contain music examples. These texts are musicological
+treatises, songbooks, or manuals like this. Such texts can be made by
+hand, simply by importing a PostScript figure into the word processor.
+However, there is an automated procedure to reduce the amount of work
+involved in HTML, @LaTeX{}, Texinfo and DocBook documents.
+
+A script called @code{lilypond-book} will extract the music fragments,
+format them, and put back the resulting notation. Here we show a small
+example for use with @LaTeX{}. The example also contains explanatory
+text, so we will not comment on it further.
+
+@subheading Input
+
+@quotation
+@verbatim
+\documentclass[a4paper]{article}
+
+\begin{document}
+
+Documents for \verb+lilypond-book+ may freely mix music and text.
+For example,
+
+\begin{lilypond}
+\relative c' {
+ c2 g'2 \times 2/3 { f8 e d } c'2 g4
+}
+\end{lilypond}
+
+Options are put in brackets.
+
+\begin[fragment,quote,staffsize=26,verbatim]{lilypond}
+ c'4 f16
+\end{lilypond}
+
+Larger examples can be put into a separate file, and introduced with
+\verb+\lilypondfile+.
+
+\lilypondfile[quote,noindent]{screech-boink.ly}
+
+(If needed, replace screech-boink.ly by any .ly file you put in the same
+directory as this file.)
+
+\end{document}
+@end verbatim
+@end quotation
+
+@subheading Processing
+
+Save the code above to a file called @file{lilybook.lytex}, then in a
+terminal run
+
+@c keep space after @version{} so TeX doesn't choke
+@example
+lilypond-book --output=out --pdf lilybook.lytex
+@emph{lilypond-book (GNU LilyPond) @version{} }
+@emph{Reading lilybook.lytex...}
+@emph{..lots of stuff deleted..}
+@emph{Compiling lilybook.tex...}
+cd out
+pdflatex lilybook
+@emph{..lots of stuff deleted..}
+xpdf lilybook
+@emph{(replace @command{xpdf} by your favorite PDF viewer)}
+@end example
+
+Running @command{lilypond-book} and @command{latex} creates a lot of
+temporary files, which would clutter up the working directory. To
+remedy this, use the @code{--output=@var{dir}} option. It will create
+the files in a separate subdirectory @file{dir}.
+
+Finally the result of the @LaTeX{} example shown above.@footnote{This
+tutorial is processed with Texinfo, so the example gives slightly
+different results in layout.} This finishes the tutorial section.
+
+@page
+
+@subheading Output
+
+Documents for @command{lilypond-book} may freely mix music and text.
+For example,
+
+@lilypond
+\relative c' {
+ c2 g'2 \times 2/3 { f8 e d } c'2 g4
+}
+@end lilypond
+
+Options are put in brackets.
+
+@lilypond[fragment,quote,staffsize=26,verbatim]
+c'4 f16
+@end lilypond
+
+Larger examples can be put into a separate file, and introduced with
+@code{\lilypondfile}.
+
+@lilypondfile[quote,noindent]{screech-boink.ly}
+
+
+@page
+
+@node Integrating music and text
+@section Integrating music and text
+
+Here we explain how to integrate LilyPond with various output formats.
+
+@menu
+* LaTeX::
+* Texinfo::
+* HTML::
+* DocBook::
+@end menu
+
+@node LaTeX
+@subsection @LaTeX{}
+
+@LaTeX{} is the de-facto standard for publishing layouts in the exact
+sciences. It is built on top of the @TeX{} typesetting engine,
+providing the best typography available anywhere.
+
+See
+@uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
+@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
+to use @LaTeX{}.
+
+Music is entered using
+
+@example
+\begin[options,go,here]@{lilypond@}
+ YOUR LILYPOND CODE
+\end@{lilypond@}
+@end example
+
+@noindent
+or
+
+@example
+\lilypondfile[options,go,here]@{@var{filename}@}
+@end example
+
+@noindent
+or
+
+@example
+\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+@end example
+
+Additionally, @code{\lilypondversion} displays the current version
+of lilypond.
+Running @command{lilypond-book} yields a file that can be further
+processed with @LaTeX{}.
+
+We show some examples here. The @code{lilypond} environment
+
+@example
+\begin[quote,fragment,staffsize=26]@{lilypond@}
+ c' d' e' f' g'2 g'2
+\end@{lilypond@}
+@end example
+
+@noindent
+produces
+
+@lilypond[quote,fragment,staffsize=26]
+c' d' e' f' g'2 g'2
+@end lilypond
+
+The short version
+
+@example
+\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
+@end example
+
+@noindent
+produces
+
+@lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
+
+@noindent
+Currently, you cannot include @code{@{} or @code{@}} within
+@code{\lilypond@{@}}, so this command is only useful with the
+@code{fragment} option.
+
+The default line width of the music will be adjusted by examining the
+commands in the document preamble, the part of the document before
+@code{\begin@{document@}}. The @command{lilypond-book} command sends
+these to @LaTeX{} to find out how wide the text is. The line width for
+the music fragments is then adjusted to the text width. Note that this
+heuristic algorithm can fail easily; in such cases it is necessary to
+use the @code{line-width} music fragment option.
+
+@cindex titling and lilypond-book
+@cindex \header in @LaTeX{} documents
+
+Each snippet will call the following macros if they have been defined by
+the user:
+
+@itemize @bullet
+@item @code{\preLilyPondExample} called before the music,
+
+@item @code{\postLilyPondExample} called after the music,
+
+@item @code{\betweenLilyPondSystem[1]} is called between systems if
+@code{lilypond-book} has split the snippet into several PostScript
+files. It must be defined as taking one parameter and will be
+passed the number of files already included in this snippet.
+The default is to simply insert a @code{\linebreak}.
+@end itemize
+
+@ignore
+Broken stuff. :(
+
+@cindex Latex, feta symbols
+@cindex fetachar
+
+To include feta symbols (such as flat, segno, etc) in a LaTeX
+document, use @code{\input@{titledefs@}}
+
+@example
+\documentclass[a4paper]@{article@}
+
+\input@{titledefs@}
+
+\begin@{document@}
+
+\fetachar\fetasharp
+
+\end@{document@}
+@end example
+
+The font symbol names are defined in the file feta20.tex; to find
+the location of this file, use the command
+
+@example
+kpsewhich feta20.tex
+@end example
+
+@end ignore
+
+@snippets
+
+Sometimes it is useful to display music elements (such as ties and slurs)
+as if they continued after the end of the fragment. This can be done by
+breaking the staff and suppressing inclusion of the rest of the LilyPond
+output.
+
+In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
+inclusion of other systems is terminated once the required number of
+systems are included. Since @code{\betweenLilyPondSystem} is first
+called @emph{after} the first system, including only the first system
+is trivial.
+
+@example
+\def\betweenLilyPondSystem#1@{\endinput@}
+
+\begin[fragment]@{lilypond@}
+ c'1\( e'( c'~ \break c' d) e f\)
+\end@{lilypond@}
+@end example
+
+If a greater number of systems is requested, a @TeX{} conditional must
+be used before the @code{\endinput}. In this example, replace @q{2} by
+the number of systems you want in the output.
+
+@example
+\def\betweenLilyPondSystem#1@{
+ \ifnum##1<2\else\expandafter\endinput\fi
+@}
+@end example
+
+@noindent
+(Since @code{\endinput} immediately stops the processing of the current
+input file we need @code{\expandafter} to delay the call of @code{\endinput}
+after executing @code{\fi} so that the @code{\if}-@code{\fi} clause is
+balanced.)
+
+Remember that the definition of @code{\betweenLilyPondSystem} is
+effective until @TeX{} quits the current group (such as the @LaTeX{}
+environment) or is overridden by another definition (which is, in
+most cases, for the rest of the document). To reset your
+definition, write
+
+@example
+\let\betweenLilyPondSystem\undefined
+@end example
+
+@noindent
+in your @LaTeX{} source.
+
+This may be simplified by defining a @TeX{} macro
+
+@example
+\def\onlyFirstNSystems#1@{
+ \def\betweenLilyPondSystem##1@{%
+ \ifnum##1<#1\else\expandafter\endinput\fi@}
+@}
+@end example
+
+@noindent
+and then saying only how many systems you want before each fragment,
+
+@example
+\onlyFirstNSystems@{3@}
+\begin@{lilypond@}...\end@{lilypond@}
+\onlyFirstNSystems@{1@}
+\begin@{lilypond@}...\end@{lilypond@}
+@end example
+
+
+@seealso
+There are specific @command{lilypond-book} command line options and
+other details to know when processing @LaTeX{} documents, see
+@ref{Invoking lilypond-book}.
+
+
+@node Texinfo
+@subsection Texinfo
+
+Texinfo is the standard format for documentation of the GNU project. An
+example of a Texinfo document is this manual. The HTML, PDF, and Info
+versions of the manual are made from the Texinfo document.
+
+In the input file, music is specified with
+
+@example
+@@lilypond[options,go,here]
+ YOUR LILYPOND CODE
+@@end lilypond
+@end example
+
+@noindent
+or
+
+@example
+@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+@end example
+
+@noindent
+or
+
+@example
+@@lilypondfile[options,go,here]@{@var{filename}@}
+@end example
+
+Additionally, @code{@@lilypondversion} displays the current version
+of lilypond.
+
+When @command{lilypond-book} is run on it, this results in a Texinfo
+file (with extension @file{.texi}) containing @code{@@image} tags for
+HTML, Info and printed output. @command{lilypond-book} generates images
+of the music in EPS and PDF formats for use in the printed output, and
+in PNG format for use in HTML and Info output.
+
+We show two simple examples here. A @code{lilypond} environment
+
+@example
+@@lilypond[fragment]
+c' d' e' f' g'2 g'
+@@end lilypond
+@end example
+
+@noindent
+produces
+
+@lilypond[fragment]
+c' d' e' f' g'2 g'
+@end lilypond
+
+The short version
+
+@example
+@@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
+@end example
+
+@noindent
+produces
+
+@lilypond[fragment,staffsize=11]{<c' e' g'>}
+
+Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
+in-line image. It always gets a paragraph of its own.
+
+
+@node HTML
+@subsection HTML
+
+Music is entered using
+
+@example
+<lilypond fragment relative=2>
+\key c \minor c4 es g2
+</lilypond>
+@end example
+@noindent
+@command{lilypond-book} then produces an HTML file with appropriate image
+tags for the music fragments:
+
+@lilypond[fragment,relative=2]
+\key c \minor c4 es g2
+@end lilypond
+
+For inline pictures, use @code{<lilypond ... />}, where the options
+are separated by a colon from the music, for example
+
+@example
+Some music in <lilypond relative=2: a b c/> a line of text.
+@end example
+
+
+To include separate files, say
+
+@example
+<lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
+@end example
+
+Additionally, @code{<lilypondversion/>} displays the current version
+of lilypond.
+
+
+@cindex titling in HTML
+@cindex preview image
+@cindex thumbnail
+
+@node DocBook
+@subsection DocBook
+
+For inserting LilyPond snippets it is good to keep the conformity of our
+DocBook document, thus allowing us to use DocBook editors, validation
+etc. So we don't use custom tags, only specify a convention based on the
+standard DocBook elements.
+
+@subheading Common conventions
+
+For inserting all type of snippets we use the @code{mediaobject} and
+@code{inlinemediaobject} element, so our snippets can be formatted
+inline or not inline. The snippet formatting options are always
+provided in the @code{role} property of the innermost element (see in
+next sections). Tags are chosen to allow DocBook editors format the
+content gracefully. The DocBook files to be processed with
+@command{lilypond-book} should have the extension @file{.lyxml}.
+
+@subheading Including a LilyPond file
+
+This is the most simple case. We must use the @file{.ly} extension for
+the included file, and insert it as a standard @code{imageobject}, with
+the following structure:
+
+@example
+<mediaobject>
+ <imageobject>
+ <imagedata fileref="music1.ly" role="printfilename" />
+ </imageobject>
+</mediaobject>
+@end example
+
+Note that you can use @code{mediaobject} or @code{inlinemediaobject}
+as the outermost element as you wish.
+
+@subheading Including LilyPond code
+
+Including LilyPond code is possible by using a @code{programlisting},
+where the language is set to @code{lilypond} with the following
+structure:
+
+@example
+<inlinemediaobject>
+ <textobject>
+ <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
+\context Staff \with @{
+ \remove Time_signature_engraver
+ \remove Clef_engraver@}
+ @{ c4( fis) @}
+ </programlisting>
+ </textobject>
+</inlinemediaobject>
+@end example
+
+As you can see, the outermost element is a @code{mediaobject} or
+@code{inlinemediaobject}, and there is a @code{textobject} containing
+the @code{programlisting} inside.
+
+@subheading Processing the DocBook document
+
+Running @command{lilypond-book} on our @file{.lyxml} file will create a
+valid DocBook document to be further processed with @file{.xml}
+extension. If you use
+@uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
+PDF file from this document automatically. For HTML (HTML Help,
+JavaHelp etc.) generation you can use the official DocBook XSL
+stylesheets, however, it is possible that you have to make some
+customization for it.
+
+
+@node Music fragment options
+@section Music fragment options
+
+In the following, a @q{LilyPond command} refers to any command described
+in the previous sections which is handled by @command{lilypond-book} to
+produce a music snippet. For simplicity, LilyPond commands are only
+shown in @LaTeX{} syntax.
+
+Note that the option string is parsed from left to right; if an option
+occurs multiple times, the last one is taken.
+
+The following options are available for LilyPond commands:
+
+@table @code
+@item staffsize=@var{ht}
+Set staff size to @var{ht}, which is measured in points.
+
+@item ragged-right
+Produce ragged-right lines with natural spacing, i.e.,
+@code{ragged-right = ##t} is added to the LilyPond snippet. This is the
+default for the @code{\lilypond@{@}} command if no @code{line-width}
+option is present. It is also the default for the @code{lilypond}
+environment if the @code{fragment} option is set, and no line width is
+explicitly specified.
+
+@item noragged-right
+For single-line snippets, allow the staff length to be stretched to
+equal that of the line width, i.e., @code{ragged-right = ##f} is
+added to the LilyPond snippet.
+
+@item line-width
+@itemx line-width=@var{size}\@var{unit}
+Set line width to @var{size}, using @var{unit} as units. @var{unit} is
+one of the following strings: @code{cm}, @code{mm}, @code{in}, or
+@code{pt}. This option affects LilyPond output (this is, the staff
+length of the music snippet), not the text layout.
+
+If used without an argument, set line width to a default value (as
+computed with a heuristic algorithm).
+
+If no @code{line-width} option is given, @command{lilypond-book} tries to
+guess a default for @code{lilypond} environments which don't use the
+@code{ragged-right} option.
+
+@item notime
+Do not print the time signature, and turns off the timing (time signature,
+bar lines) in the score.
+
+@item fragment
+Make @command{lilypond-book} add some boilerplate code so that you can
+simply enter, say,
+
+@example
+c'4
+@end example
+
+@noindent
+without @code{\layout}, @code{\score}, etc.
+
+@item nofragment
+Do not add additional code to complete LilyPond code in music snippets.
+Since this is the default, @code{nofragment} is redundant normally.
+
+@item indent=@var{size}\@var{unit}
+Set indentation of the first music system to @var{size}, using
+@var{unit} as units. @var{unit} is one of the following strings:
+@code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
+LilyPond, not the text layout.
+
+@item noindent
+Set indentation of the first music system to zero. This option affects
+LilyPond, not the text layout. Since no indentation is the default,
+@code{noindent} is redundant normally.
+
+@item quote
+Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
+the output into a quotation block. The value @q{0.4@dmn{in}} can be
+controlled with the @code{exampleindent} option.
+
+@item exampleindent
+Set the amount by which the @code{quote} option indents a music snippet.
+
+@item relative
+@itemx relative=@var{n}
+Use relative octave mode. By default, notes are specified relative to
+middle@tie{}C. The optional integer argument specifies the octave of
+the starting note, where the default @code{1} is middle C.
+@code{relative} option only works when @code{fragment} option is set,
+so @code{fragment} is automatically implied by @code{relative},
+regardless of the presence of any @code{(no)fragment} option in the
+source.
+@end table
+
+LilyPond also uses @command{lilypond-book} to produce its own
+documentation. To do that, some more obscure music fragment options are
+available.
+
+@table @code
+@item verbatim
+The argument of a LilyPond command is copied to the output file and
+enclosed in a verbatim block, followed by any text given with the
+@code{intertext} option (not implemented yet); then the actual music is
+displayed. This option does not work well with @code{\lilypond@{@}} if
+it is part of a paragraph.
+
+If @code{verbatim} is used in a @code{lilypondfile} command, it is
+possible to enclose verbatim only a part of the source file. If the
+source file contain a comment containing @samp{begin verbatim} (without
+quotes), quoting the source in the verbatim block will start after the
+last occurrence of such a comment; similarly, quoting the source verbatim
+will stop just before the first occurrence of a comment containing
+@samp{end verbatim}, if there is any. In the following source file
+example, the music will be interpreted in relative mode, but the
+verbatim quote will not show the @code{relative} block, i.e.
+
+@example
+\relative c' @{ % begin verbatim
+ c4 e2 g4
+ f2 e % end verbatim
+@}
+@end example
+
+@noindent
+will be printed with a verbatim block like
+
+@example
+ c4 e2 g4
+ f2 e
+@end example
+
+@noindent
+If you would like to translate comments and variable names in verbatim
+output but not in the sources, you may set the environment variable
+@code{LYDOC_LOCALEDIR} to a directory path; the directory should
+contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
+as a domain.
+
+@item addversion
+(Only for Texinfo output.) Prepend line @code{\version
+@@w@{"@@version@{@}"@}} to @code{verbatim} output.
+
+@item texidoc
+(Only for Texinfo output.) If @command{lilypond} is called with the
+@option{--header=@/texidoc} option, and the file to be processed is
+called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
+is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
+option makes @command{lilypond-book} include such files, adding its
+contents as a documentation block right before the music snippet.
+
+Assuming the file @file{foo@/.ly} contains
+
+@example
+\header @{
+ texidoc = "This file demonstrates a single note."
+@}
+@{ c'4 @}
+@end example
+
+@noindent
+and we have this in our Texinfo document @file{test.texinfo}
+
+@example
+@@lilypondfile[texidoc]@{foo.ly@}
+@end example
+
+@noindent
+the following command line gives the expected result
+
+@example
+lilypond-book --pdf --process="lilypond \
+ -dbackend=eps --header=texidoc" test.texinfo
+@end example
+
+Most LilyPond test documents (in the @file{input} directory of the
+distribution) are small @file{.ly} files which look exactly like this.
+
+For localization purpose, if the Texinfo document contains
+@code{@@documentlanguage @var{LANG}} and @file{foo@/.ly} header
+contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
+is called with @option{--header=@/texidoc@var{LANG}}, then
+@file{foo@/.texidoc@var{LANG}} will be included instead of
+@file{foo@/.texidoc}.
+
+@item lilyquote
+(Only for Texinfo output.) This option is similar to quote, but only
+the music snippet (and the optional verbatim block implied by
+@code{verbatim} option) is put into a quotation block. This option is
+useful if you want to @code{quote} the music snippet but not the
+@code{texidoc} documentation block.
+
+@item doctitle
+(Only for Texinfo output.) This option works similarly to
+@code{texidoc} option: if @command{lilypond} is called with the
+@option{--header=@/doctitle} option, and the file to be processed is
+called @file{foo@/.ly} and contains a @code{doctitle} field in the
+@code{\header}, it creates a file @file{foo@/.doctitle}. When
+@code{doctitle} option is used, the contents of @file{foo@/.doctitle},
+which should be a single line of @var{text}, is inserted in the
+Texinfo document as @code{@@lydoctitle @var{text}}.
+@code{@@lydoctitle} should be a macro defined in the Texinfo document.
+The same remark about @code{texidoc} processing with localized
+languages also applies to @code{doctitle}.
+
+@item nogettext
+(Only for Texinfo output.) Do not translate comments and variable
+names in the snippet quoted verbatim.
+
+@item printfilename
+If a LilyPond input file is included with @code{\lilypondfile}, print
+the file name right before the music snippet. For HTML output, this
+is a link. Only the base name of the file is printed, i.e. the
+directory part of the file path is stripped.
+
+@end table
+
+
+@node Invoking lilypond-book
+@section Invoking @command{lilypond-book}
+
+@command{lilypond-book} produces a file with one of the following
+extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml},
+depending on the output format. All of @file{.tex}, @file{.texi} and
+@file{.xml} files need further processing.
+
+@subheading Format-specific instructions
+
+@subsubheading @LaTeX{}
+
+There are two ways of processing your @LaTeX{} document for printing or
+publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
+PostScript file with @LaTeX{} via a DVI to PostScript translator like
+@command{dvips}. The first way is simpler and recommended@footnote{Note
+that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
+@LaTeX{} document, that is why we explain the two ways.}, and whichever
+way you use, you can easily convert between PostScript and PDF with
+tools, like @command{ps2pdf} and @command{pdf2ps} included in
+Ghostscript package.
+
+To produce a PDF file through PDF@LaTeX{}, use
+
+@example
+lilypond-book --pdf yourfile.pdftex
+pdflatex yourfile.tex
+@end example
+
+@cindex outline fonts
+@cindex type1 fonts
+@cindex dvips
+@cindex invoking dvips
+To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
+should do
+
+@example
+lilypond-book yourfile.lytex
+latex yourfile.tex
+dvips -Ppdf yourfile.dvi
+ps2pdf yourfile.ps
+@end example
+
+@noindent
+The @file{.dvi} file created by this process will not contain
+ note heads. This is normal; if you follow the instructions, they
+will be included in the @file{.ps} and @file{.pdf} files.
+
+Running @command{dvips} may produce some warnings about fonts; these
+are harmless and may be ignored. If you are running @command{latex} in
+twocolumn mode, remember to add @code{-t landscape} to the
+@command{dvips} options.
+
+@subsubheading Texinfo
+
+To produce a Texinfo document (in any output format), follow the normal
+procedures for Texinfo; this is, either call @command{texi2pdf} or
+@command{texi2dvi} or @command{makeinfo}, depending on the output format
+you want to create.
+@ifinfo
+@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
+an Info File, , , texinfo, GNU Texinfo}.
+@end ifinfo
+@ifnotinfo
+See the documentation of Texinfo for further details.
+@end ifnotinfo
+
+
+@subheading Command line options
+
+@command{lilypond-book} accepts the following command line options:
+
+@table @code
+@item -f @var{format}
+@itemx --format=@var{format}
+Specify the document type to process: @code{html}, @code{latex},
+@code{texi} (the default) or @code{docbook}. If this option is missing,
+@command{lilypond-book} tries to detect the format automatically, see
+@ref{Filename extensions}. Currently, @code{texi} is the same as
+@code{texi-html}.
+
+@c This complicated detail is not implemented, comment it out -jm
+@ignore
+The @code{texi} document type produces a Texinfo file with music
+fragments in the printed output only. For getting images in the HTML
+version, the format @code{texi-html} must be used instead.
+@end ignore
+
+@item -F @var{filter}
+@itemx --filter=@var{filter}
+Pipe snippets through @var{filter}. @code{lilypond-book} will
+not --filter and --process at the same time. For example,
+
+@example
+lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
+@end example
+
+@item -h
+@itemx --help
+Print a short help message.
+
+@item -I @var{dir}
+@itemx --include=@var{dir}
+Add @var{dir} to the include path. @command{lilypond-book} also looks
+for already compiled snippets in the include path, and does not write
+them back to the output directory, so in some cases it is necessary to
+invoke further processing commands such as @command{makeinfo} or
+@command{latex} with the same @code{-I @var{dir}} options.
+
+@item -o @var{dir}
+@itemx --output=@var{dir}
+Place generated files in directory @var{dir}. Running
+@command{lilypond-book} generates lots of small files that LilyPond will
+process. To avoid all that garbage in the source directory, use the
+@option{--output} command line option, and change to that directory
+before running @command{latex} or @command{makeinfo}.
+
+@example
+lilypond-book --output=out yourfile.lytex
+cd out
+...
+@end example
+
+@itemx --skip-lily-check
+Do not fail if no lilypond output is found. It is used for LilyPond
+Info documentation without images.
+
+@itemx --skip-png-check
+Do not fail if no PNG images are found for EPS files. It is used for
+LilyPond Info documentation without images.
+
+@itemx --lily-output-dir=@var{dir}
+Write lily-XXX files to directory @var{dir}, link into @code{--output}
+directory. Use this option to save building time for documents in
+different directories which share a lot of identical snippets.
+
+@itemx --info-images-dir=@var{dir}
+Format Texinfo output so that Info will look for images of music in
+@var{dir}.
+
+@itemx --latex-program=@var{prog}
+Run executable @command{prog} instead of @command{latex}. This is
+useful if your document is processed with @command{xelatex}, for
+example.
+
+@itemx --left-padding=@var{amount}
+Pad EPS boxes by this much. @var{amount} is measured in millimeters,
+and is 3.0 by default. This option should be used if the lines of
+music stick out of the right margin.
+
+The width of a tightly clipped system can vary, due to notation
+elements that stick into the left margin, such as bar numbers and
+instrument names. This option will shorten each line and move each
+line to the right by the same amount.
+
+
+@item -P @var{command}
+@itemx --process=@var{command}
+Process LilyPond snippets using @var{command}. The default command is
+@code{lilypond}. @code{lilypond-book} will not @code{--filter} and
+@code{--process} at the same time.
+
+@item --pdf
+Create PDF files for use with PDF@LaTeX{}.
+
+@item -V
+@itemx --verbose
+Be verbose.
+
+@item -v
+@itemx --version
+Print version information.
+@end table
+
+@knownissues
+
+The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
+@LaTeX{} commands that change margins and line widths after the preamble
+are ignored.
+
+Only the first @code{\score} of a LilyPond block is processed.
+
+
+@node Filename extensions
+@section Filename extensions
+
+You can use any filename extension for the input file, but if you do not
+use the recommended extension for a particular format you may need to
+manually specify the output format; for details, see @ref{Invoking
+lilypond-book}. Otherwise, @command{lilypond-book} automatically
+selects the output format based on the input filename's extension.
+
+@quotation
+@multitable @columnfractions .2 .5
+@item @strong{extension} @tab @strong{output format}
+@item
+@item @file{.html} @tab HTML
+@item @file{.itely} @tab Texinfo
+@item @file{.latex} @tab @LaTeX{}
+@item @file{.lytex} @tab @LaTeX{}
+@item @file{.lyxml} @tab DocBook
+@item @file{.tely} @tab Texinfo
+@item @file{.tex} @tab @LaTeX{}
+@item @file{.texi} @tab Texinfo
+@item @file{.texinfo} @tab Texinfo
+@item @file{.xml} @tab HTML
+@end multitable
+@end quotation
+
+If you use the same filename extension for the input file than the
+extension @command{lilypond-book} uses for the output file, and if the
+input file is in the same directory as @command{lilypond-book} working
+directory, you must use @code{--output} option to make
+@command{lilypond-book} running, otherwise it will exit with an error
+message like @qq{Output would overwrite input file}.
+
+
+@node lilypond-book templates
+@section lilypond-book templates
+
+These templates are for use with @code{lilypond-book}. If you're not familiar
+with this program, please refer to
+@rprogram{lilypond-book}.
+
+@subsection LaTeX
+
+You can include LilyPond fragments in a LaTeX document.
+
+@example
+\documentclass[]@{article@}
+
+\begin@{document@}
+
+Normal LaTeX text.
+
+\begin@{lilypond@}
+\relative c'' @{
+a4 b c d
+@}
+\end@{lilypond@}
+
+More LaTeX text.
+
+\begin@{lilypond@}
+\relative c'' @{
+d4 c b a
+@}
+\end@{lilypond@}
+\end@{document@}
+@end example
+
+@subsection Texinfo
+
+You can include LilyPond fragments in Texinfo; in fact, this entire manual
+is written in Texinfo.
+
+@example
+\input texinfo
+@@node Top
+
+Texinfo text
+
+@@lilypond[verbatim,fragment,ragged-right]
+a4 b c d
+@@end lilypond
+
+More Texinfo text
+
+@@lilypond[verbatim,fragment,ragged-right]
+d4 c b a
+@@end lilypond
+
+@@bye
+@end example
+
+
+@subsection xelatex
+
+@verbatim
+\documentclass{article}
+\usepackage{ifxetex}
+\ifxetex
+%xetex specific stuff
+\usepackage{xunicode,fontspec,xltxtra}
+\setmainfont[Numbers=OldStyle]{Times New Roman}
+\setsansfont{Arial}
+\else
+%This can be empty if you are not going to use pdftex
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{mathptmx}%Times
+\usepackage{helvet}%Helvetica
+\fi
+%Here you can insert all packages that pdftex also understands
+\usepackage[ngerman,finnish,english]{babel}
+\usepackage{graphicx}
+
+\begin{document}
+\title{A short document with LilyPond and xelatex}
+\maketitle
+
+Normal \textbf{font} commands inside the \emph{text} work,
+because they \textsf{are supported by \LaTeX{} and XeteX.}
+If you want to use specific commands like \verb+\XeTeX+, you
+should include them again in a \verb+\ifxetex+ environment.
+You can use this to print the \ifxetex \XeTeX{} command \else
+XeTeX command \fi which is not known to normal \LaTeX .
+
+In normal text you can easily use LilyPond commands, like this:
+
+\begin{lilypond}
+{a2 b c'8 c' c' c'}
+\end{lilypond}
+
+\noindent
+and so on.
+
+The fonts of snippets set with LilyPond will have to be set from
+inside
+of the snippet. For this you should read the AU on how to use
+lilypond-book.
+
+\selectlanguage{ngerman}
+Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
+anderen
+seltsamen Zeichen: __ ______, wenn sie von der Schriftart
+unterst__tzt werden.
+\end{document}
+@end verbatim
+
+
+@node Alternate methods of mixing text and music
+@section Alternative methods of mixing text and music
+
+This section shows methods to integrate text and music, different than
+the automated method with @command{lilypond-book}.
+
+@menu
+* Many quotes from a large score::
+* Inserting LilyPond output into OpenOffice.org::
+* Inserting LilyPond output into other programs::
+@end menu
+
+@node Many quotes from a large score
+@unnumberedsubsec Many quotes from a large score
+
+If you need to quote many fragments from a large score, you can also use
+the clip systems feature, see @ruser{Extracting fragments of music}.
+
+
+@node Inserting LilyPond output into OpenOffice.org
+@unnumberedsubsec Inserting LilyPond output into OpenOffice.org
+
+@cindex OpenOffice.org
+
+LilyPond notation can be added to OpenOffice.org with
+@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
+
+
+@node Inserting LilyPond output into other programs
+@unnumberedsubsec Inserting LilyPond output into other programs
+
+To insert LilyPond output in other programs, use @code{lilypond}
+instead of @code{lilypond-book}. Each example must be created
+individually and added to the document; consult the documentation for
+that program. Most programs will be able to insert LilyPond output in
+@file{PNG}, @file{EPS}, or @file{PDF} formats.
+
+To reduce the white space around your LilyPond score, use
+the following options
+
+@example
+\paper@{
+ indent=0\mm
+ line-width=120\mm
+ oddFooterMarkup=##f
+ oddHeaderMarkup=##f
+ bookTitleMarkup = ##f
+ scoreTitleMarkup = ##f
+@}
+
+@{ c1 @}
+@end example
+
+To produce a useful @file{EPS} file, use
+
+@example
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
+
+@file{PNG}:
+lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly
+@end example
+
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
+@c \version "2.12.0"
+
+
+@node Running lilypond
+@chapter Running @command{lilypond}
+
+This chapter details the technicalities of running LilyPond.
+
+@menu
+* Normal usage::
+* Command-line usage::
+* Error messages::
+* Common errors::
+* Point and click::
+* Text editor support::
+@end menu
+
+
+@node Normal usage
+@section Normal usage
+
+Most users run LilyPond through a GUI; if you have not done so
+already, read @rlearning{Introduction}. If you use an alternate
+editor to write lilypond files, see the documentation for that
+program.
+
+
+@node Command-line usage
+@section Command-line usage
+
+This section contains extra information about using LilyPond on the
+command-line. This may be desirable to pass extra options to the
+program. In addition, there are certain extra @q{helper} programs (such
+as @code{midi2ly}) which are only available on the command-line.
+
+By @q{command-line}, we mean the command line in the operating system.
+Windows users might be more familiar with the terms @q{DOS shell} or
+@q{command shell}. MacOS@tie{}X users might be more familiar with the terms
+@q{terminal} or @q{console}. Some additional setup is required
+for MacOS@tie{}X users; please see @rgeneral{MacOS X}.
+
+Describing how to use this part of an operating system is outside the
+scope of this manual; please consult other documentation on this topic
+if you are unfamiliar with the command-line.
+
+@menu
+* Invoking lilypond::
+* Command line options for lilypond::
+* Environment variables::
+@end menu
+
+@node Invoking lilypond
+@unnumberedsubsec Invoking @command{lilypond}
+
+The @command{lilypond} executable may be called as follows from
+the command line.
+
+@example
+lilypond [@var{option}]@dots{} @var{file}@dots{}
+@end example
+
+
+When invoked with a filename that has no extension, the @file{.ly}
+extension is tried first. To read input from stdin, use a
+dash (@code{-}) for @var{file}.
+
+When @file{filename.ly} is processed it will produce @file{filename.ps}
+and @file{filename.pdf} as output. Several files can be specified;
+they will each be processed independently. @footnote{The status of
+GUILE is not reset after processing a @code{.ly} file, so be careful
+not to change any system defaults from within Scheme.}
+
+If @file{filename.ly} contains more than one @code{\book}
+block, then the rest of the scores will be output in numbered files,
+starting with @file{filename-1.pdf}. In addition, the value of
+@code{output-suffix} will be inserted between the basename and the
+number. An input file containing
+
+@example
+#(define output-suffix "violin")
+\score @{ @dots{} @}
+#(define output-suffix "cello")
+\score @{ @dots{} @}
+@end example
+
+@noindent
+will output @var{base}@file{-violin.pdf} and
+@var{base}@file{-cello-1.pdf}.
+
+
+@node Command line options for lilypond
+@unnumberedsubsec Command line options for @command{lilypond}
+
+@cindex Invoking @command{lilypond}
+@cindex command line options for @command{lilypond}
+@cindex options, command line
+@cindex switches
+
+The following options are supported:
+
+@table @code
+
+@item -e,--evaluate=@var{expr}
+Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
+Multiple @code{-e} options may be given, they will be evaluated
+sequentially.
+
+The expression will be evaluated in the @code{guile-user} module, so
+if you want to use definitions in @var{expr}, use
+
+@example
+lilypond -e '(define-public a 42)'
+@end example
+
+@noindent
+on the command-line, and include
+
+@example
+#(use-modules (guile-user))
+@end example
+
+@noindent
+at the top of the @code{.ly} file.
+
+@item -f,--format=@var{format}
+which formats should be written. Choices for @code{format} are
+@code{svg}, @code{ps}, @code{pdf}, and @code{png}.
+
+Example: @code{lilypond -fpng @var{filename}.ly}
+
+
+
+@item -d,--define-default=@var{var}=@var{val}
+This sets the internal program option @var{var} to the Scheme value
+@var{val}. If @var{val} is not supplied, then @var{#t} is used. To
+switch off an option, @code{no-} may be prefixed to @var{var}, e.g.
+
+@cindex point and click, command line
+
+@example
+-dno-point-and-click
+@end example
+
+@noindent
+is the same as
+@example
+-dpoint-and-click='#f'
+@end example
+
+Here are a few interesting options.
+
+@cindex help, command line
+
+@table @samp
+@item help
+Running @code{lilypond -dhelp} will print all of the @code{-d} options
+available.
+
+@cindex paper-size, command line
+
+@item paper-size
+This option sets the default paper-size,
+@example
+-dpaper-size=\"letter\"
+@end example
+
+@noindent
+Note that the string must be enclosed in escaped quotes ( @code{\"} ).
+@c Match " in previous line to help context-sensitive editors
+
+@cindex safe, command line
+
+@item safe
+Do not trust the @code{.ly} input.
+
+When LilyPond formatting is available through a web server, either the
+@code{--safe} or the @code{--jail} option @b{MUST} be passed. The
+@code{--safe} option will prevent inline Scheme code from wreaking
+havoc, for example
+
+@quotation
+@verbatim
+#(system "rm -rf /")
+{
+ c4^#(ly:export (ly:gulp-file "/etc/passwd"))
+}
+@end verbatim
+@end quotation
+
+The @code{-dsafe} option works by evaluating in-line Scheme
+expressions in a special safe module. This safe module is derived from
+GUILE @file{safe-r5rs} module, but adds a number of functions of the
+LilyPond API. These functions are listed in @file{scm/@/safe@/-lily@/.scm}.
+
+In addition, safe mode disallows @code{\include} directives and
+disables the use of backslashes in @TeX{} strings.
+
+In safe mode, it is not possible to import LilyPond variables
+into Scheme.
+
+@code{-dsafe} does @emph{not} detect resource overuse. It is still possible to
+make the program hang indefinitely, for example by feeding cyclic data
+structures into the backend. Therefore, if using LilyPond on a
+publicly accessible webserver, the process should be limited in both
+CPU and memory usage.
+
+The safe mode will prevent many useful LilyPond snippets from being
+compiled. The @code{--jail} is a more secure alternative, but
+requires more work to set up.
+
+@cindex output format, setting
+@item backend
+the output format to use for the back-end. Choices for @code{format} are
+@table @code
+@item ps
+@cindex PostScript output
+ for PostScript.
+
+ Postscript files include TTF, Type1 and OTF fonts. No subsetting of
+ these fonts is done. When using oriental character sets, this can
+ lead to huge files.
+
+@item eps
+
+@cindex Postscript, encapulated
+@cindex EPS (Encapsulated PostScript)
+
+ for encapsulated PostScript. This dumps every page (system) as a separate
+@file{EPS} file, without fonts, and as one collated @file{EPS} file with
+all pages (systems) including fonts.
+
+This mode is used by default by @command{lilypond-book}.
+
+@item svg
+
+@cindex SVG (Scalable Vector Graphics)
+
+ for SVG (Scalable Vector Graphics).
+
+ This creates a single SVG file, without embedded fonts, for every
+ page of output. It is recommended to install the Century
+ Schoolbook fonts, included with your LilyPond installation, for
+ optimal rendering. Under UNIX, simply copy these fonts from the
+ LilyPond directory (typically
+ @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
+ @file{~/.fonts/}. The SVG output should be compatible with any
+ SVG editor or user agent.
+
+@item scm
+
+@cindex Scheme dump
+
+ for a dump of the raw, internal Scheme-based drawing commands.
+
+@item null
+ do not output a printed score; has the same effect as @code{-dno-print-pages}.
+@end table
+
+Example: @code{lilypond -dbackend=svg @var{filename}.ly}
+
+@item preview
+@cindex preview, command line
+Generate an output file containing the titles and the first system
+
+@item print-pages
+Generate the full pages, the default. @code{-dno-print-pages} is
+useful in combination with @code{-dpreview}.
+
+@end table
+
+
+
+@item -h,--help
+Show a summary of usage.
+
+@item -H,--header=@var{FIELD}
+Dump a header field to file @file{BASENAME.@var{FIELD}}.
+
+@item --include, -I=@var{directory}
+Add @var{directory} to the search path for input files.
+@cindex file searching
+@cindex search path
+
+@item -i,--init=@var{file}
+Set init file to @var{file} (default: @file{init.ly}).
+
+@item -o,--output=@var{FILE}
+Set the default output file to @var{FILE}. The appropriate
+suffix will be added (e.g. @code{.pdf} for pdf)
+
+@cindex PostScript output
+
+@item --ps
+Generate PostScript.
+
+@cindex Portable Network Graphics (PNG) output
+
+@item --png
+Generate pictures of each page, in PNG format. This implies
+@code{--ps}. The resolution in DPI of the image may be set with
+@example
+-dresolution=110
+@end example
+
+@cindex Portable Document Format (PDF) output
+
+@item --pdf
+Generate PDF. This implies @code{--ps}.
+
+
+
+@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
+Run @command{lilypond} in a chroot jail.
+
+The @code{--jail} option provides a more flexible alternative to
+@code{--safe} when LilyPond formatting is available through a web
+server or whenever LilyPond executes externally provided
+sources.
+
+The @code{--jail} option works by changing the root of @command{lilypond} to
+@var{jail} just before starting the actual compilation process. The user
+and group are then changed to match those provided, and the current
+directory is changed to @var{dir}. This setup guarantees that it is not
+possible (at least in theory) to escape from the jail. Note that for
+@code{--jail} to work @command{lilypond} must be run as root, which is usually
+accomplished in a safe way using @command{sudo}.
+
+Setting up a jail is a slightly delicate matter, as we must be sure that
+LilyPond is able to find whatever it needs to compile the source
+@emph{inside the jail}. A typical setup comprises the following items:
+
+@table @asis
+@item Setting up a separate filesystem
+A separate filesystem should be created for LilyPond, so that it can be
+mounted with safe options such as @code{noexec}, @code{nodev}, and
+@code{nosuid}. In this way, it is impossible to run executables or to
+write directly to a device from LilyPond. If you do not want to create a
+separate partition, just create a file of reasonable size and use it to
+mount a loop device. A separate filesystem also guarantees that LilyPond
+cannot write more space than it is allowed.
+
+@item Setting up a separate user
+A separate user and group (say, @code{lily}/@code{lily}) with low
+privileges should be used to run LilyPond inside the jail. There should
+be a single directory writable by this user, which should be passed in
+@var{dir}.
+
+@item Preparing the jail
+LilyPond needs to read a number of files while running. All these files
+are to be copied into the jail, under the same path they appear in the
+real root filesystem. The entire content of the LilyPond installation
+(e.g., @file{/usr/share/lilypond})
+should be copied.
+
+If problems arise, the simplest way to trace them down is to run
+LilyPond using @command{strace}, which will allow you to determine which
+files are missing.
+
+@item Running LilyPond
+In a jail mounted with @code{noexec} it is impossible to execute any external
+program. Therefore LilyPond must be run with a backend that does not
+require any such program. As we already mentioned, it must be also run
+with superuser privileges (which, of course, it will lose immediately),
+possibly using @command{sudo}. It is a good idea to limit the number of
+seconds of CPU time LilyPond can use (e.g., using @command{ulimit
+-t}), and, if your operating system supports it, the amount of memory
+that can be allocated.
+@end table
+
+
+@item -v,--version
+Show version information.
+
+@item -V,--verbose
+Be verbose: show full paths of all files read, and give timing
+information.
+
+@item -w,--warranty
+Show the warranty with which GNU LilyPond comes. (It comes with
+@strong{NO WARRANTY}!)
+@end table
+
+@node Environment variables
+@unnumberedsubsec Environment variables
+
+
+@cindex LANG
+@cindex LILYPOND_DATADIR
+
+@command{lilypond} recognizes the following environment variables:
+@table @code
+@item LILYPOND_DATADIR
+This specifies a directory where locale messages and
+data files will be looked up by default. The directory should contain
+subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
+
+@item LANG
+This selects the language for the warning messages.
+
+@item LILYPOND_GC_YIELD
+With this variable the memory footprint and performance can be
+adjusted. It is a percentage tunes memory management behavior. With
+higher values, the program uses more memory, with smaller values, it
+uses more CPU time. The default value is @code{70}.
+
+@end table
+
+
+@node Error messages
+@section Error messages
+
+@cindex error messages
+Different error messages can appear while compiling a file:
+
+@table @emph
+
+@item Warning
+@cindex warning
+Something looks suspect. If you are requesting something out of the
+ordinary then you will understand the message, and can ignore it.
+However, warnings usually indicate that something is wrong with the
+input file.
+
+@item Error
+@cindex error
+Something is definitely wrong. The current processing step (parsing,
+interpreting, or formatting) will be finished, but the next step will
+be skipped.
+
+@item Fatal error
+@cindex fatal error
+Something is definitely wrong, and LilyPond cannot continue. This
+happens rarely. The most usual cause is misinstalled fonts.
+
+@item Scheme error
+@cindex trace, Scheme
+@cindex call trace
+@cindex Scheme error
+Errors that occur while executing Scheme code are caught by the Scheme
+interpreter. If running with the verbose option (@code{-V} or
+@code{--verbose}) then a call trace of the offending
+function call is printed.
+
+@item Programming error
+@cindex Programming error
+There was some internal inconsistency. These error messages are
+intended to help the programmers and debuggers. Usually, they can be
+ignored. Sometimes, they come in such big quantities that they obscure
+other output.
+
+@item Aborted (core dumped)
+@cindex Aborted (core dumped)
+This signals a serious programming error that caused the program to
+crash. Such errors are considered critical. If you stumble on one,
+send a bug-report.
+@end table
+
+@cindex errors, message format
+If warnings and errors can
+be linked to some part of the input file, then error messages have the
+following form
+
+@example
+@var{filename}:@var{lineno}:@var{columnno}: @var{message}
+@var{offending input line}
+@end example
+
+A line-break is inserted in the offending line to indicate the column
+where the error was found. For example,
+
+@example
+test.ly:2:19: error: not a duration: 5
+ @{ c'4 e'
+ 5 g' @}
+@end example
+
+These locations are LilyPond's best guess about where the warning or
+error occurred, but (by their very nature) warnings and errors occur
+when something unexpected happens. If you can't see an error in the
+indicated line of your input file, try checking one or two lines
+above the indicated position.
+
+More information about errors is given in @ref{Common errors}.
+
+
+@node Common errors
+@section Common errors
+
+The error conditions described below occur often, yet the cause
+is not obvious or easily found. Once seen and understood, they
+are easily handled.
+
+
+@menu
+* Music runs off the page::
+* An extra staff appears::
+* Apparent error in ../ly/init.ly::
+* Error message Unbound variable %::
+* Error message FT_Get_Glyph_Name::
+@end menu
+
+@node Music runs off the page
+@unnumberedsubsec Music runs off the page
+
+Music running off the page over the right margin or appearing
+unduly compressed is almost always due to entering an incorrect
+duration on a note, causing the final note in a measure to extend
+over the bar line. It is not invalid if the final note in a
+measure does not end on the automatically entered bar line, as the
+note is simply assumed to carry over into the next measure. But
+if a long sequence of such carry-over measures occurs the music
+can appear compressed or may flow off the page because automatic
+line breaks can be inserted only at the end of complete measures,
+i.e., where all notes end before or at the end of the measure.
+
+@warning{An incorrect duration can cause line breaks to be
+inhibited, leading to a line of highly compressed music or
+music which flows off the page.}
+
+The incorrect duration can be found easily if bar checks are used,
+see @ruser{Bar and bar number checks}.
+
+If you actually intend to have a series of such carry-over measures
+you will need to insert an invisible bar line where you want the
+line to break. For details, see @ruser{Bar lines}.
+
+
+@node An extra staff appears
+@unnumberedsubsec An extra staff appears
+
+If contexts are not created explicitly with @code{\new} they will be
+silently created as soon as a command is encountered which cannot
+be applied to an existing context. In simple scores the automatic
+creation of contexts is useful, and most of the examples in the
+LilyPond manuals take advantage of this simplification. But
+occasionally the silent creation of contexts can give rise to
+unexpected new staves or scores. For example, it might be expected
+that the following code would cause all note heads within the
+following staff to be colored red, but in fact it results in two
+staves with the note heads remaining the default black in the lower
+staff.
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.NoteHead #'color = #red
+\new Staff { a }
+@end lilypond
+
+This is because a @code{Staff} context does not exist when the
+override is processed, so one is implicitly created and the override
+is applied to it, but then the @code{\new Staff} command creates
+another, separate, staff into which the notes are placed. The
+correct code to color all note heads red is
+
+@lilypond[quote,verbatim,relative=2]
+\new Staff {
+ \override Staff.NoteHead #'color = #red
+ a
+}
+@end lilypond
+
+As a second example, if a @code{\relative} command is placed inside
+a @code{\repeat} command two staves result, the second offset from
+the first, because the @code{\repeat} command generates two
+@code{\relative} blocks, which each implicitly create @code{Staff}
+and @code{Voice} blocks.
+
+@lilypond[quote,verbatim]
+\repeat unfold 2 \relative { c d e f }
+@end lilypond
+
+The correct way is to reverse the @code{\repeat} and
+@code{\relative} commands, like this:
+
+@lilypond[quote,verbatim]
+\relative {
+ \repeat unfold 2 { c d e f }
+}
+@end lilypond
+
+
+@node Apparent error in ../ly/init.ly
+@unnumberedsubsec Apparent error in @code{../ly/init.ly}
+
+Various obscure error messages may appear about syntax errors in
+@code{../ly/init.ly} if the input file is not correctly formed,
+for example, if it does not contain correctly
+matched braces or quote signs.
+
+The most common error is a missing brace, (@code{@}}), at the end of
+a @code{score} block. Here the solution is obvious: check the
+@code{score} block is correctly terminated. The correct structure
+of an input file is described in @rlearning{How LilyPond input files work}.
+Using an editor which automatically highlights matching brackets and
+braces is helpful to avoid such errors.
+
+A second common cause is no white space between the last syllable
+of a lyrics block and the terminating brace, (@code{@}}). Without
+this separation the brace is taken to be part of the syllable. It
+is always advisable to ensure there is white space before and after
+@emph{every} brace. For the importance of this when using lyrics,
+see @ruser{Lyrics explained}.
+
+This error message can also appear if a terminating quote sign,
+(@code{"}), is omitted. In this case an accompanying error message
+@c keep "-matching straight in fancy editors
+should give a line number close to the line in error. The
+mismatched quote will usually be on the line one or two above.
+
+@node Error message Unbound variable %
+@unnumberedsubsec Error message Unbound variable %
+
+This error message will appear at the bottom of the console
+output or log file together with a @qq{GUILE signalled an error ...}
+message every time a Scheme routine is called which (invalidly)
+contains a @emph{LilyPond} rather than a @emph{Scheme} comment.
+
+LilyPond comments begin with a percent sign, (@code{%}), and must
+not be used within Scheme routines. Scheme comments begin with a
+semi-colon, (@code{;}).
+
+@node Error message FT_Get_Glyph_Name
+@unnumberedsubsec Error message FT_Get_Glyph_Name
+
+This error messages appears in the console output or log file if
+an input file contains a non-ASCII character and was not saved in
+UTF-8 encoding. For details, see @ruser{Text encoding}.
+
+
+@node Point and click
+@section Point and click
+
+@cindex point and click
+
+Point and click lets you find notes in the input by clicking on them
+in the PDF viewer. This makes it easier to find input that causes
+some error in the sheet music.
+
+When this functionality is active, LilyPond adds hyperlinks to the PDF
+file. These hyperlinks are sent to the web-browser, which opens a
+text-editor with the cursor in the right place.
+
+To make this chain work, you should configure your PDF viewer to
+follow hyperlinks using the @file{lilypond-invoke-editor} script
+supplied with LilyPond.
+
+For Xpdf on UNIX, the following should be present in
+@file{xpdfrc}@footnote{On UNIX, this file is found either in
+@file{/etc/xpdfrc} or as @file{.xpdfrc} in your home directory.}
+
+@example
+urlCommand "lilypond-invoke-editor %s"
+@end example
+
+The program @file{lilypond-invoke-editor} is a small helper
+program. It will invoke an editor for the special @code{textedit}
+URIs, and run a web browser for others. It tests the environment
+variable @code{EDITOR} for the following patterns,
+
+@table @code
+@item emacs
+ this will invoke
+@example
+emacsclient --no-wait +@var{line}:@var{column} @var{file}
+@end example
+@item vim
+ this will invoke
+@example
+gvim --remote +:@var{line}:norm@var{char} @var{file}
+@end example
+
+@item nedit
+this will invoke
+@example
+ nc -noask +@var{line} @var{file}'
+@end example
+@end table
+
+The environment variable @code{LYEDITOR} is used to override this. It
+contains the command line to start the editor, where @code{%(file)s},
+@code{%(column)s}, @code{%(line)s} is replaced with the file, column
+and line respectively. The setting
+
+@example
+emacsclient --no-wait +%(line)s:%(column)s %(file)s
+@end example
+
+@noindent
+for @code{LYEDITOR} is equivalent to the standard emacsclient
+invocation.
+
+
+@cindex file size, output
+
+The point and click links enlarge the output files significantly. For
+reducing the size of PDF and PS files, point and click may be switched
+off by issuing
+
+@example
+\pointAndClickOff
+@end example
+
+@noindent
+in a @file{.ly} file. Point and click may be explicitly enabled with
+
+@example
+\pointAndClickOn
+@end example
+
+Alternately, you may disable point and click with a command-line
+option:
+
+@example
+lilypond -dno-point-and-click file.ly
+@end example
+
+@warning{You should always turn off point and click in any LilyPond
+files to be distributed to avoid including path information about
+your computer in the .pdf file, which can pose a security risk.}
+@node Text editor support
+@section Text editor support
+
+@cindex editors
+@cindex vim
+@cindex emacs
+@cindex modes, editor
+@cindex syntax coloring
+@cindex coloring, syntax
+
+There is support for different text editors for LilyPond.
+
+@menu
+* Emacs mode::
+* Vim mode::
+* Other editors::
+@end menu
+
+@node Emacs mode
+@unnumberedsubsec Emacs mode
+
+Emacs has a @file{lilypond-mode}, which provides keyword
+autocompletion, indentation, LilyPond specific parenthesis matching
+and syntax coloring, handy compile short-cuts and reading LilyPond
+manuals using Info. If @file{lilypond-mode} is not installed on your
+platform, see below.
+
+An Emacs mode for entering music and running LilyPond is contained in
+the source archive in the @file{elisp} directory. Do @command{make
+install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
+should be placed to @var{load-path}@file{/site-start.d/} or appended
+to your @file{~/.emacs} or @file{~/.emacs.el}.
+
+As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
+your @var{load-path} by appending the following line (as modified) to your
+@file{~/.emacs}
+
+@c any reason we do not advise: (push "~/site-lisp" load-path)
+@example
+(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
+@end example
+
+
+@node Vim mode
+@unnumberedsubsec Vim mode
+
+For @uref{http://@/www@/.vim@/.org,VIM}, a @file{vimrc} is supplied,
+along with syntax coloring tools. A Vim mode for entering music and
+running LilyPond is contained in the source archive in @code{$VIM}
+directory.
+
+The LilyPond file type is detected if the file
+@file{~/.vim/filetype.vim} has the following content
+
+@example
+if exists("did_load_filetypes")
+ finish
+endif
+augroup filetypedetect
+ au! BufNewFile,BufRead *.ly,*.ily setf lilypond
+augroup END
+@end example
+
+Please include this path by appending the following line to your
+@file{~/.vimrc}
+
+@example
+set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
+@end example
+
+@noindent
+where $@{LILYPOND_VERSION@} is your LilyPond version. If LilyPond was not
+installed in @file{/usr/local/}, then change this path accordingly.
+
+
+@node Other editors
+@unnumberedsubsec Other editors
+
+Other editors (both text and graphical) support LilyPond, but
+their special configuration files are not distributed with
+LilyPond. Consult their documentation for more information. Such
+editors are listed in @rgeneral{Alternate editors}.
+
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
+@c \version "2.12.0"
+
+@node Suggestions for writing files
+@chapter Suggestions for writing files
+
+Now you're ready to begin writing larger LilyPond input files --
+not just the little examples in the tutorial, but whole pieces.
+But how should you go about doing it?
+
+As long as LilyPond can understand your input files and produce
+the output that you want, it doesn't matter what your input files
+look like. However, there are a few other things to consider when
+writing LilyPond input files.
+
+@itemize
+@item What if you make a mistake? The structure of a LilyPond
+file can make certain errors easier (or harder) to find.
+
+@item What if you want to share your input files with somebody
+else? In fact, what if you want to alter your own input files in
+a few years? Some LilyPond input files are understandable at
+first glance; others may leave you scratching your head
+for an hour.
+
+@item What if you want to upgrade your LilyPond file for use
+with a later version of LilyPond? The input syntax changes
+occasionally as LilyPond improves. Most changes can be
+done automatically with @code{convert-ly}, but some changes
+might require manual assistance. LilyPond input files can be
+structured in order to be easier (or harder) to update.
+
+@end itemize
+
+@menu
+* General suggestions::
+* Typesetting existing music::
+* Large projects::
+* Troubleshooting::
+* Make and Makefiles::
+@end menu
+
+
+@node General suggestions
+@section General suggestions
+
+Here are a few suggestions that can help you to avoid or fix
+problems:
+
+@itemize
+@item @strong{Include @code{\version} numbers in every file}. Note that all
+templates contain @code{\version} information. We
+highly recommend that you always include the @code{\version}, no matter
+how small your file is. Speaking from personal experience, it's
+quite frustrating to try to remember which version of LilyPond you were
+using a few years ago. @command{convert-ly} requires you to declare
+which version of LilyPond you used.
+
+@item @strong{Include checks}: @ruser{Bar and bar number checks},
+@ruser{Octave checks}. If you include checks every so often, then
+if you make a mistake, you can pinpoint it quicker. How often is
+@q{every so often}? It depends on the complexity of the music.
+For very simple music, perhaps just once or twice. For very
+complex music, perhaps every bar.
+
+@item @strong{One bar per line of text}. If there is anything complicated,
+either in the music
+itself or in the output you desire, it's often good to write only one bar
+per line. Saving screen space by cramming eight bars per line just isn't
+worth it if you have to @q{debug} your input files.
+
+@item @strong{Comment your input files}. Use either bar numbers
+(every so often) or
+references to musical themes (@q{second theme in violins,} @q{fourth
+variation,} etc.). You may not need comments when you're writing the piece
+for the first time, but if you want to go back to change something two or
+three years later, or if you pass the source over to a friend, it will
+be much more
+challenging to determine your intentions or how your file is structured if
+you didn't comment the file.
+
+@item @strong{Indent your braces}. A lot of problems are caused by an
+imbalance
+in the number of @code{@{} and @code{@}}.
+
+@item @strong{Explicitly add durations} at the beginnings of sections
+and variables. If you specify @code{c4 d e} at the beginning of a
+phrase (instead of just @code{c d e}) you can save yourself some
+problems if you rearrange your music later.
+
+@item @strong{Separate tweaks} from music definitions. See
+@rlearning{Saving typing with variables and functions}, and
+@rlearning{Style sheets}.
+
+@end itemize
+
+
+@node Typesetting existing music
+@section Typesetting existing music
+
+If you are entering music from an existing score (i.e., typesetting a
+piece of existing sheet music),
+
+@itemize
+
+@item Enter the manuscript (the physical copy of the music) into
+LilyPond one system at a time (but still only one bar per line of text),
+and check each system when you finish it. You may use the
+@code{showLastLength} or @code{showFirstLength} properties to speed up
+processing -- see @ruser{Skipping corrected music}.
+
+@item Define @code{mBreak = @{ \break @}} and insert @code{\mBreak}
+in the input file whenever the manuscript has a line break. This
+makes it much easier to compare the LilyPond music to the original
+music. When you are finished proofreading your score, you may
+define @code{mBreak = @{ @}} to remove all those line breaks. This
+will allow LilyPond to place line breaks wherever it feels are
+best.
+
+@item When entering a part for a transposing instrument into a
+variable, it is recommended that the notes are wrapped in
+
+@example
+\transpose c natural-pitch @{...@}
+@end example
+
+@noindent
+(where @code{natural-pitch} is the open pitch of the instrument) so
+that the music in the variable is effectively in C. You can transpose
+it back again when the variable is used, if required, but you might
+not want to (e.g., when printing a score in concert pitch,
+converting a trombone part from treble to bass clef, etc.)
+Mistakes in transpositions are less likely if all the music in
+variables is at a consistent pitch.
+
+Also, only ever transpose to/from C. That means that the only other
+keys you will use are the natural pitches of the instruments - bes
+for a B-flat trumpet, aes for an A-flat clarinet, etc.
+
+@end itemize
+
+
+@node Large projects
+@section Large projects
+
+When working on a large project, having a clear structure to your
+lilypond input files becomes vital.
+
+@itemize
+
+@item @strong{Use a variable for each voice}, with a minimum of
+structure inside the definition. The structure of the
+@code{\score} section is the most likely thing to change;
+the @code{violin} definition is extremely unlikely to change
+in a new version of LilyPond.
+
+@example
+violin = \relative c'' @{
+g4 c'8. e16
+@}
+...
+\score @{
+ \new GrandStaff @{
+ \new Staff @{
+ \violin
+ @}
+ @}
+@}
+@end example
+
+@item @strong{Separate tweaks from music definitions}. This
+point was made previously, but for large
+projects it is absolutely vital. We might need to change
+the definition of @code{fthenp}, but then we only need
+to do this once, and we can still avoid touching anything
+inside @code{violin}.
+
+@example
+fthenp = _\markup@{
+ \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
+violin = \relative c'' @{
+g4\fthenp c'8. e16
+@}
+@end example
+
+@end itemize
+
+
+@node Troubleshooting
+@section Troubleshooting
+
+Sooner or later, you will write a file that LilyPond cannot
+compile. The messages that LilyPond gives may help
+you find the error, but in many cases you need to do some
+investigation to determine the source of the problem.
+
+The most powerful tools for this purpose are the
+single line comment (indicated by @code{%}) and the block
+comment (indicated by @code{%@{ ... %@}}). If you don't
+know where a problem is, start commenting out huge portions
+of your input file. After you comment out a section, try
+compiling the file again. If it works, then the problem
+must exist in the portion you just commented. If it doesn't
+work, then keep on commenting out material until you have
+something that works.
+
+In an extreme case, you might end up with only
+
+@example
+\score @{
+ <<
+ % \melody
+ % \harmony
+ % \bass
+ >>
+ \layout@{@}
+@}
+@end example
+
+@noindent
+(in other words, a file without any music)
+
+If that happens, don't give up. Uncomment a bit -- say,
+the bass part -- and see if it works. If it doesn't work,
+then comment out all of the bass music (but leave
+@code{\bass} in the @code{\score} uncommented.
+
+@example
+bass = \relative c' @{
+%@{
+ c4 c c c
+ d d d d
+%@}
+@}
+@end example
+
+Now start slowly uncommenting more and more of the
+@code{bass} part until you find the problem line.
+
+Another very useful debugging technique is constructing
+@rgeneral{Tiny examples}.
+
+
+@node Make and Makefiles
+@section Make and Makefiles
+
+@cindex makefiles
+@cindex make
+
+Pretty well all the platforms Lilypond can run on support a software
+facility called @code{make}. This software reads a special file called a
+@code{Makefile} that defines what files depend on what others and what
+commands you need to give the operating system to produce one file from
+another. For example the makefile would spell out how to produce
+@code{ballad.pdf} and @code{ballad.midi} from @code{ballad.ly} by
+running Lilypond.
+
+There are times when it is a good idea to create a @code{Makefile}
+for your project, either for your own convenience or
+as a courtesy to others who might have access to your source files.
+This is true for very large projects with many included files and
+different output options (e.g. full score, parts, conductor's
+score, piano reduction, etc.), or for projects that
+require difficult commands to build them (such as
+@code{lilypond-book} projects). Makefiles vary greatly in
+complexity and flexibility, according to the needs and skills of
+the authors. The program GNU Make comes installed on GNU/Linux
+distributions and on MacOS X, and it is also available for Windows.
+
+See the @strong{GNU Make Manual} for full details on using
+@code{make}, as what follows here gives only a glimpse of what it
+can do.
+
+The commands to define rules in a makefile differ
+according to platform; for instance the various forms of Linux and
+MacOS use @code{bash}, while Windows uses @code{cmd}. Note that on
+MacOS X, you need to configure the system to use the command-line
+intepreter. Here are some example makefiles, with versions for both
+Linux/MacOS and Windows.
+
+The first example is for an orchestral work in four
+movements with a directory structure as follows:
+
+@example
+Symphony/
+|-- MIDI/
+|-- Makefile
+|-- Notes/
+| |-- cello.ily
+| |-- figures.ily
+| |-- horn.ily
+| |-- oboe.ily
+| |-- trioString.ily
+| |-- viola.ily
+| |-- violinOne.ily
+| `-- violinTwo.ily
+|-- PDF/
+|-- Parts/
+| |-- symphony-cello.ly
+| |-- symphony-horn.ly
+| |-- symphony-oboes.ly
+| |-- symphony-viola.ly
+| |-- symphony-violinOne.ly
+| `-- symphony-violinTwo.ly
+|-- Scores/
+| |-- symphony.ly
+| |-- symphonyI.ly
+| |-- symphonyII.ly
+| |-- symphonyIII.ly
+| `-- symphonyIV.ly
+`-- symphonyDefs.ily
+@end example
+
+The @code{.ly} files in the @code{Scores} and
+@code{Parts} directories get their notes from @code{.ily}
+files in the @code{Notes} directory:
+
+@example
+%%% top of file "symphony-cello.ly"
+\include ../definitions.ily
+\include ../Notes/cello.ily
+@end example
+
+The makefile will have targets of @code{score} (entire piece in
+full score), @code{movements} (individual movements in full score),
+and @code{parts} (individual parts for performers). There
+is also a target @code{archive} that will create a tarball of
+the source files, suitable for sharing via web or email. Here is
+the makefile for GNU/Linux or MacOS X. It should be saved with the
+name @code{Makefile} in the top directory of the project:
+
+@warning{When a target or pattern rule is defined, the
+subsequent lines must begin with tabs, not spaces.}
+
+@example
+# the name stem of the output files
+piece = symphony
+# determine how many processors are present
+CPU_CORES=`cat /proc/cpuinfo | grep -m1 "cpu cores" | sed s/".*: "//`
+# The command to run lilypond
+LILY_CMD = lilypond -ddelete-intermediate-files \
+ -dno-point-and-click -djob-count=$(CPU_CORES)
+
+# The suffixes used in this Makefile.
+.SUFFIXES: .ly .ily .pdf .midi
+
+# Input and output files are searched in the directories listed in
+# the VPATH variable. All of them are subdirectories of the current
+# directory (given by the GNU make variable `CURDIR').
+VPATH = \
+ $(CURDIR)/Scores \
+ $(CURDIR)/PDF \
+ $(CURDIR)/Parts \
+ $(CURDIR)/Notes
+
+# The pattern rule to create PDF and MIDI files from a LY input file.
+# The .pdf output files are put into the `PDF' subdirectory, and the
+# .midi files go into the `MIDI' subdirectory.
+%.pdf %.midi: %.ly
+ $(LILY_CMD) $<; \ # this line begins with a tab
+ if test -f "$*.pdf"; then \
+ mv "$*.pdf" PDF/; \
+ fi; \
+ if test -f "$*.midi"; then \
+ mv "$*.midi" MIDI/; \
+ fi
+
+notes = \
+ cello.ily \
+ horn.ily \
+ oboe.ily \
+ viola.ily \
+ violinOne.ily \
+ violinTwo.ily
+
+# The dependencies of the movements.
+$(piece)I.pdf: $(piece)I.ly $(notes)
+$(piece)II.pdf: $(piece)II.ly $(notes)
+$(piece)III.pdf: $(piece)III.ly $(notes)
+$(piece)IV.pdf: $(piece)IV.ly $(notes)
+
+# The dependencies of the full score.
+$(piece).pdf: $(piece).ly $(notes)
+
+# The dependencies of the parts.
+$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
+$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
+$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
+$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
+$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
+$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
+
+# Type `make score' to generate the full score of all four
+# movements as one file.
+.PHONY: score
+score: $(piece).pdf
+
+# Type `make parts' to generate all parts.
+# Type `make foo.pdf' to generate the part for instrument `foo'.
+# Example: `make symphony-cello.pdf'.
+.PHONY: parts
+parts: $(piece)-cello.pdf \
+ $(piece)-violinOne.pdf \
+ $(piece)-violinTwo.pdf \
+ $(piece)-viola.pdf \
+ $(piece)-oboes.pdf \
+ $(piece)-horn.pdf
+
+# Type `make movements' to generate files for the
+# four movements separately.
+.PHONY: movements
+movements: $(piece)I.pdf \
+ $(piece)II.pdf \
+ $(piece)III.pdf \
+ $(piece)IV.pdf
+
+all: score parts movements
+
+archive:
+ tar -cvvf stamitz.tar \ # this line begins with a tab
+ --exclude=*pdf --exclude=*~ \
+ --exclude=*midi --exclude=*.tar \
+ ../Stamitz/*
+@end example
+
+
+There are special complications on the Windows platform. After
+downloading and installing GNU Make for Windows, you must set the
+correct path in the system's environment variables so that the
+DOS shell can find the Make program. To do this, right-click on
+"My Computer," then choose @code{Properties} and
+@code{Advanced}. Click @code{Environment Variables}, and then
+in the @code{System Variables} pane, highlight @code{Path}, click
+@code{edit}, and add the path to the GNU Make executable file, which
+ will look something like this:
+
+@example
+C:\Program Files\GnuWin32\bin
+@end example
+
+The makefile itself has to be altered to handle different shell
+commands and to deal with spaces that are present
+in some default system directories. The @code{archive} target
+is eliminated since Windows does not have the @code{tar} command,
+and Windows also has a different default extension for midi files.
+
+
+@example
+## WINDOWS VERSION
+##
+piece = symphony
+LILY_CMD = lilypond -ddelete-intermediate-files \
+ -dno-point-and-click \
+ -djob-count=$(NUMBER_OF_PROCESSORS)
+
+#get the 8.3 name of CURDIR (workaround for spaces in PATH)
+workdir = $(shell for /f "tokens=*" %%b in ("$(CURDIR)") \
+ do @@echo %%~sb)
+
+.SUFFIXES: .ly .ily .pdf .mid
+
+VPATH = \
+ $(workdir)/Scores \
+ $(workdir)/PDF \
+ $(workdir)/Parts \
+ $(workdir)/Notes
+
+%.pdf %.mid: %.ly
+ $(LILY_CMD) $< # this line begins with a tab
+ if exist "$*.pdf" move /Y "$*.pdf" PDF/ # begin with tab
+ if exist "$*.mid" move /Y "$*.mid" MIDI/ # begin with tab
+
+notes = \
+ cello.ily \
+ figures.ily \
+ horn.ily \
+ oboe.ily \
+ trioString.ily \
+ viola.ily \
+ violinOne.ily \
+ violinTwo.ily
+
+$(piece)I.pdf: $(piece)I.ly $(notes)
+$(piece)II.pdf: $(piece)II.ly $(notes)
+$(piece)III.pdf: $(piece)III.ly $(notes)
+$(piece)IV.pdf: $(piece)IV.ly $(notes)
+
+$(piece).pdf: $(piece).ly $(notes)
+
+$(piece)-cello.pdf: $(piece)-cello.ly cello.ily
+$(piece)-horn.pdf: $(piece)-horn.ly horn.ily
+$(piece)-oboes.pdf: $(piece)-oboes.ly oboe.ily
+$(piece)-viola.pdf: $(piece)-viola.ly viola.ily
+$(piece)-violinOne.pdf: $(piece)-violinOne.ly violinOne.ily
+$(piece)-violinTwo.pdf: $(piece)-violinTwo.ly violinTwo.ily
+
+.PHONY: score
+score: $(piece).pdf
+
+.PHONY: parts
+parts: $(piece)-cello.pdf \
+ $(piece)-violinOne.pdf \
+ $(piece)-violinTwo.pdf \
+ $(piece)-viola.pdf \
+ $(piece)-oboes.pdf \
+ $(piece)-horn.pdf
+
+.PHONY: movements
+movements: $(piece)I.pdf \
+ $(piece)II.pdf \
+ $(piece)III.pdf \
+ $(piece)IV.pdf
+
+all: score parts movements
+@end example
+
+
+The next Makefile is for a @command{lilypond-book} document done in
+LaTeX. This project has an index, which requires that the
+@command{latex} command be run twice to update links. Output files are
+all stored in the @code{out} directory for .pdf output and in the
+@code{htmlout} directory for the html output.
+
+@example
+SHELL=/bin/sh
+FILE=myproject
+OUTDIR=out
+WEBDIR=htmlout
+VIEWER=acroread
+BROWSER=firefox
+LILYBOOK_PDF=lilypond-book --output=$(OUTDIR) --pdf $(FILE).lytex
+LILYBOOK_HTML=lilypond-book --output=$(WEBDIR) $(FILE).lytex
+PDF=cd $(OUTDIR) && pdflatex $(FILE)
+HTML=cd $(WEBDIR) && latex2html $(FILE)
+INDEX=cd $(OUTDIR) && makeindex $(FILE)
+PREVIEW=$(VIEWER) $(OUTDIR)/$(FILE).pdf &
+
+all: pdf web keep
+
+pdf:
+ $(LILYBOOK_PDF) # begin with tab
+ $(PDF) # begin with tab
+ $(INDEX) # begin with tab
+ $(PDF) # begin with tab
+ $(PREVIEW) # begin with tab
+
+web:
+ $(LILYBOOK_HTML) # begin with tab
+ $(HTML) # begin with tab
+ cp -R $(WEBDIR)/$(FILE)/ ./ # begin with tab
+ $(BROWSER) $(FILE)/$(FILE).html & # begin with tab
+
+keep: pdf
+ cp $(OUTDIR)/$(FILE).pdf $(FILE).pdf # begin with tab
+
+clean:
+ rm -rf $(OUTDIR) # begin with tab
+
+web-clean:
+ rm -rf $(WEBDIR) # begin with tab
+
+archive:
+ tar -cvvf myproject.tar \ # begin this line with tab
+ --exclude=out/* \
+ --exclude=htmlout/* \
+ --exclude=myproject/* \
+ --exclude=*midi \
+ --exclude=*pdf \
+ --exclude=*~ \
+ ../MyProject/*
+@end example
+
+TODO: make this thing work on Windows
+
+The previous makefile does not work on Windows. An alternative
+for Windows users would be to create a simple batch file
+containing the build commands. This will not
+keep track of dependencies the way a makefile does, but it at
+least reduces the build process to a single command. Save the
+following code as @command{build.bat} or @command{build.cmd}.
+The batch file can be run at the DOS prompt or by simply
+double-clicking its icon.
+
+@example
+lilypond-book --output=out --pdf myproject.lytex
+cd out
+pdflatex myproject
+makeindex myproject
+pdflatex myproject
+cd ..
+copy out\myproject.pdf MyProject.pdf
+@end example
+
+
+@seealso
+Application Usage:
+FIXME
+@c @rprogram{Setup for MacOS X},
+@rprogram{Command-line usage},
+@rprogram{lilypond-book}
--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
+@c \version "2.12.0"
+
+
+@node Updating files with convert-ly
+@chapter Updating files with @command{convert-ly}
+
+@cindex Updating a LilyPond file
+@cindex convert-ly
+
+The LilyPond input syntax is routinely changed to simplify it or improve
+it in different ways. As a side effect of this, the LilyPond interpreter
+often is no longer compatible with older input files. To remedy this,
+the program @command{convert-ly} can be used to deal with most of the
+syntax changes between LilyPond versions.
+
+@menu
+* Why does the syntax change?::
+* Invoking convert-ly::
+* Command line options for convert-ly::
+* Problems running convert-ly::
+* Manual conversions::
+@end menu
+
+
+@node Why does the syntax change?
+@section Why does the syntax change?
+
+@cindex convert-ly
+@cindex updating old input files
+
+The LilyPond input syntax occasionally changes. As LilyPond
+itself improves, the syntax (input language) is modified
+accordingly. Sometimes these changes are made to make the input
+easier to read and write or sometimes the changes are made to
+accommodate new features of LilyPond.
+
+For example, all @code{\paper} and @code{\layout} property names
+are supposed to be written in the form @code{first-second-third}.
+However, in version 2.11.60, we noticed that the
+@code{printallheaders} property did not follow this convention.
+Should we leave it alone (confusing new users who must deal with
+an inconsistent input format), or change it (annoying old users
+with existing scores)? In this case, we decided to change the
+name to @code{print-all-headers}. Fortunately, this change can be
+automated with our @command{convert-ly} tool.
+
+Unfortunately, @code{convert-ly} cannot handle all input changes.
+For example, in LilyPond 2.4 and earlier, accents and non-English
+letters were entered using LaTeX -- displaying the French word for
+Christmas was entered as @code{No\"el}. But in LilyPond
+@c keep "-matching straight in fancy editors
+2.6 and above, the special @code{ë} must be entered directly into
+the LilyPond file as an UTF-8 character. @code{convert-ly} cannot
+change all the LaTeX special characters into UTF-8 characters; you
+must manually update your old LilyPond input files.
+
+
+@node Invoking convert-ly
+@section Invoking @command{convert-ly}
+
+@command{convert-ly} uses @code{\version} statements in the input
+file to detect the old version number. In most cases, to upgrade
+your input file it is sufficient to run
+
+@example
+convert-ly -e myfile.ly
+@end example
+
+@noindent
+in the directory containing the file. This will upgrade
+@code{myfile.ly} in-place and preserve the original file in
+@code{myfile.ly~}.
+
+@warning{@command{convert-ly} always converts up to the last
+syntax change handled by it. This means that the @code{\version}
+number left in the file is usually lower than the version of
+@command{convert-ly} itself.}
+
+To convert all the input files in a directory together use
+
+@example
+convert-ly -e *.ly
+@end example
+
+Alternatively, if you want to specify a different name for the
+upgraded file, preserving the original file and name unchanged,
+use
+
+@example
+convert-ly myfile.ly > mynewfile.ly
+@end example
+
+The program will list the version numbers for which conversions
+have been made. If no version numbers are listed the file is
+already up to date.
+
+MacOS@tie{}X users may execute these commands under the menu entry
+@code{Compile > Update syntax}.
+
+Windows users should enter these commands in a Command Prompt
+window, which is usually found under
+@code{Start > Accessories > Command Prompt}.
+
+
+@node Command line options for convert-ly
+@section Command line options for @command{convert-ly}
+
+The program is invoked as follows:
+
+@example
+convert-ly [@var{option}]@dots{} @var{filename}@dots{}
+@end example
+
+
+The following options can be given:
+
+@table @code
+@item -e,--edit
+Apply the conversions direct to the input file, modifying it
+in-place.
+
+@item -f,--from=@var{from-patchlevel}
+Set the version to convert from. If this is not set, @command{convert-ly}
+will guess this, on the basis of @code{\version} strings in the file.
+E.g. @code{--from=2.10.25}
+
+@item -n,--no-version
+Normally, @command{convert-ly} adds a @code{\version} indicator
+to the output. Specifying this option suppresses this.
+
+@item -s, --show-rules
+Show all known conversions and exit.
+
+@item --to=@var{to-patchlevel}
+Set the goal version of the conversion. It defaults to the latest
+available version. E.g. @code{--to=2.12.2}
+
+@item -h, --help
+Print usage help.
+@end table
+
+To upgrade LilyPond fragments in texinfo files, use
+
+@example
+convert-ly --from=... --to=... --no-version *.itely
+@end example
+
+To see the changes in the LilyPond syntax between two versions, use
+
+@example
+convert-ly --from=... --to=... -s
+@end example
+
+
+@node Problems running convert-ly
+@section Problems running @code{convert-ly}
+
+When running convert-ly in a Command Prompt window under Windows
+on a file which has spaces in the filename or in the path to it,
+it is necessary to surround the entire input file name with three
+(!) sets of double quotes:
+
+@example
+convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
+@end example
+
+If the simple @command{convert-ly -e *.ly} command fails because the
+expanded command line becomes too long, the @command{convert-ly}
+command may be placed in a loop instead. This example for UNIX
+will upgrade all @code{.ly} files in the current directory
+
+@example
+for f in *.ly; do convert-ly -e $f; done;
+@end example
+
+In the Windows Command Prompt window the corresponding command is
+
+@example
+for %x in (*.ly) do convert-ly -e """%x"""
+@end example
+
+Not all language changes are handled. Only one output option can be
+specified. Automatically updating scheme and LilyPond scheme
+interfaces is quite unlikely; be prepared to tweak scheme code
+manually.
+
+
+@node Manual conversions
+@section Manual conversions
+
+In theory, a program like @command{convert-ly} could handle any
+syntax change. After all, a computer program interprets the old
+version and the new version, so another computer program can
+translate one file into another@footnote{At least, this is
+possible in any LilyPond file which does not contain scheme. If
+there is scheme in the file, then the LilyPond file contains a
+Turing-complete language, and we run into problems with the famous
+@qq{Halting Problem} in computer science.}.
+
+However, the LilyPond project has limited resources: not all
+conversions are performed automatically. Below is a list of known
+problems.
+
+
+@verbatim
+1.6->2.0:
+ Doesn't always convert figured bass correctly, specifically things like {<
+>}. Mats' comment on working around this:
+ To be able to run convert-ly
+ on it, I first replaced all occurrences of '{<' to some dummy like '{#'
+ and similarly I replaced '>}' with '&}'. After the conversion, I could
+ then change back from '{ #' to '{ <' and from '& }' to '> }'.
+ Doesn't convert all text markup correctly. In the old markup syntax,
+ it was possible to group a number of markup commands together within
+parentheses, e.g.
+ -#'((bold italic) "string")
+ This will incorrectly be converted into
+ -\markup{{\bold italic} "string"}
+ instead of the correct
+ -\markup{\bold \italic "string"}
+2.0->2.2:
+ Doesn't handle \partcombine
+ Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
+stanzas.
+2.0->2.4:
+ \magnify isn't changed to \fontsize.
+ - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
+ remove-tag isn't changed.
+ - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
+ first-page-number isn't changed.
+ - first-page-number no => print-first-page-number = ##f
+ Line breaks in header strings aren't converted.
+ - \\\\ as line break in \header strings => \markup \center-align <
+ "First Line" "Second Line" >
+ Crescendo and decrescendo terminators aren't converted.
+ - \rced => \!
+ - \rc => \!
+2.2->2.4:
+ \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
+converted.
+2.4.2->2.5.9
+ \markup{ \center-align <{ ... }> } should be converted to:
+ \markup{ \center-align {\line { ... }} }
+ but now, \line is missing.
+2.4->2.6
+ Special LaTeX characters such as $~$ in text are not converted to UTF8.
+2.8
+ \score{} must now begin with a music expression. Anything else
+ (particularly \header{}) must come after the music.
+@end verbatim
+
+
projects / lilypond.git / commitdiff