From: Graham Percival Date: Sat, 26 Sep 2009 14:03:00 +0000 (+0100) Subject: Doc: rename application to usage. X-Git-Tag: release/2.13.5-0~36 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=1aa51adb465071fc1d9fc2b964426af357b18c19;p=lilypond.git Doc: rename application to usage. --- diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index 8c324a46ff..a474cf9c73 100644 --- a/Documentation/GNUmakefile +++ b/Documentation/GNUmakefile @@ -9,7 +9,7 @@ depth = .. 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 @@ -72,7 +72,7 @@ HTML_PAGE_NAMES= index translations devel 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) diff --git a/Documentation/application.tely b/Documentation/application.tely deleted file mode 100644 index 2399bca341..0000000000 --- a/Documentation/application.tely +++ /dev/null @@ -1,82 +0,0 @@ -\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 diff --git a/Documentation/application/GNUmakefile b/Documentation/application/GNUmakefile deleted file mode 100644 index 26e33a6901..0000000000 --- a/Documentation/application/GNUmakefile +++ /dev/null @@ -1,10 +0,0 @@ -depth = ../.. - -LOCALSTEPMAKE_TEMPLATES = ly - -LATEX_FILES =$(call src-wildcard,*.latex) -EXTRA_DIST_FILES = $(LATEX_FILES) - -include $(depth)/make/stepmake.make - - diff --git a/Documentation/application/converters.itely b/Documentation/application/converters.itely deleted file mode 100644 index 9efee75e0c..0000000000 --- a/Documentation/application/converters.itely +++ /dev/null @@ -1,317 +0,0 @@ -@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}. - diff --git a/Documentation/application/latex-example.latex b/Documentation/application/latex-example.latex deleted file mode 100644 index da9c12b871..0000000000 --- a/Documentation/application/latex-example.latex +++ /dev/null @@ -1,46 +0,0 @@ -\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} diff --git a/Documentation/application/latex-lilypond-example.latex b/Documentation/application/latex-lilypond-example.latex deleted file mode 100644 index a8b799badb..0000000000 --- a/Documentation/application/latex-lilypond-example.latex +++ /dev/null @@ -1,183 +0,0 @@ -\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 <> -\end{lilypond} -and C minor -\lilypond[fragment,11pt]{\context Voice <>} 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 <>} -% \lilypond{\context Voice <>} - -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 <>} & major \\ -\lilypond[11pt,fragment]{\context Voice <>} & minor \\ -\lilypond[11pt,fragment]{\context Voice <>} & diminished \\ -\lilypond[11pt,fragment]{\context Voice <>} & 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} diff --git a/Documentation/application/lilypond-book.itely b/Documentation/application/lilypond-book.itely deleted file mode 100644 index 7fe3090315..0000000000 --- a/Documentation/application/lilypond-book.itely +++ /dev/null @@ -1,1163 +0,0 @@ -@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]@{@} -@end example - -@noindent -produces - -@lilypond[quote,fragment,staffsize=11]{} - -@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]@{@} -@end example - -@noindent -produces - -@lilypond[fragment,staffsize=11]{} - -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 - -\key c \minor c4 es g2 - -@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{}, where the options -are separated by a colon from the music, for example - -@example -Some music in a line of text. -@end example - - -To include separate files, say - -@example -@var{filename} -@end example - -Additionally, @code{} 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 - - - - - -@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 - - - -\context Staff \with @{ - \remove Time_signature_engraver - \remove Clef_engraver@} - @{ c4( fis) @} - - - -@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 - diff --git a/Documentation/application/running.itely b/Documentation/application/running.itely deleted file mode 100644 index a112a91248..0000000000 --- a/Documentation/application/running.itely +++ /dev/null @@ -1,810 +0,0 @@ -@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}. - diff --git a/Documentation/application/suggestions.itely b/Documentation/application/suggestions.itely deleted file mode 100644 index dc1cb14f6c..0000000000 --- a/Documentation/application/suggestions.itely +++ /dev/null @@ -1,608 +0,0 @@ -@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} diff --git a/Documentation/application/updating.itely b/Documentation/application/updating.itely deleted file mode 100644 index 71bb0edfcb..0000000000 --- a/Documentation/application/updating.itely +++ /dev/null @@ -1,261 +0,0 @@ -@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 - - diff --git a/Documentation/usage.tely b/Documentation/usage.tely new file mode 100644 index 0000000000..53baccd893 --- /dev/null +++ b/Documentation/usage.tely @@ -0,0 +1,82 @@ +\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 diff --git a/Documentation/usage/GNUmakefile b/Documentation/usage/GNUmakefile new file mode 100644 index 0000000000..26e33a6901 --- /dev/null +++ b/Documentation/usage/GNUmakefile @@ -0,0 +1,10 @@ +depth = ../.. + +LOCALSTEPMAKE_TEMPLATES = ly + +LATEX_FILES =$(call src-wildcard,*.latex) +EXTRA_DIST_FILES = $(LATEX_FILES) + +include $(depth)/make/stepmake.make + + diff --git a/Documentation/usage/converters.itely b/Documentation/usage/converters.itely new file mode 100644 index 0000000000..9efee75e0c --- /dev/null +++ b/Documentation/usage/converters.itely @@ -0,0 +1,317 @@ +@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}. + diff --git a/Documentation/usage/latex-example.latex b/Documentation/usage/latex-example.latex new file mode 100644 index 0000000000..da9c12b871 --- /dev/null +++ b/Documentation/usage/latex-example.latex @@ -0,0 +1,46 @@ +\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} diff --git a/Documentation/usage/latex-lilypond-example.latex b/Documentation/usage/latex-lilypond-example.latex new file mode 100644 index 0000000000..a8b799badb --- /dev/null +++ b/Documentation/usage/latex-lilypond-example.latex @@ -0,0 +1,183 @@ +\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 <> +\end{lilypond} +and C minor +\lilypond[fragment,11pt]{\context Voice <>} 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 <>} +% \lilypond{\context Voice <>} + +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 <>} & major \\ +\lilypond[11pt,fragment]{\context Voice <>} & minor \\ +\lilypond[11pt,fragment]{\context Voice <>} & diminished \\ +\lilypond[11pt,fragment]{\context Voice <>} & 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} diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely new file mode 100644 index 0000000000..7fe3090315 --- /dev/null +++ b/Documentation/usage/lilypond-book.itely @@ -0,0 +1,1163 @@ +@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]@{@} +@end example + +@noindent +produces + +@lilypond[quote,fragment,staffsize=11]{} + +@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]@{@} +@end example + +@noindent +produces + +@lilypond[fragment,staffsize=11]{} + +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 + +\key c \minor c4 es g2 + +@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{}, where the options +are separated by a colon from the music, for example + +@example +Some music in a line of text. +@end example + + +To include separate files, say + +@example +@var{filename} +@end example + +Additionally, @code{} 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 + + + + + +@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 + + + +\context Staff \with @{ + \remove Time_signature_engraver + \remove Clef_engraver@} + @{ c4( fis) @} + + + +@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 + diff --git a/Documentation/usage/running.itely b/Documentation/usage/running.itely new file mode 100644 index 0000000000..a112a91248 --- /dev/null +++ b/Documentation/usage/running.itely @@ -0,0 +1,810 @@ +@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}. + diff --git a/Documentation/usage/suggestions.itely b/Documentation/usage/suggestions.itely new file mode 100644 index 0000000000..dc1cb14f6c --- /dev/null +++ b/Documentation/usage/suggestions.itely @@ -0,0 +1,608 @@ +@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} diff --git a/Documentation/usage/updating.itely b/Documentation/usage/updating.itely new file mode 100644 index 0000000000..71bb0edfcb --- /dev/null +++ b/Documentation/usage/updating.itely @@ -0,0 +1,261 @@ +@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 + +