(lilypond_version_re_str): handle

[lilypond.git] / Documentation / user / lilypond-book.itely

diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index 18ccc8a7d484b3ffdaf40a1a6d97b74a26a03873..a10a8ebe7d4972125dae403d24660da233c15784 100644 (file)
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -36,6 +36,7 @@ Short Introduction to LaTeX} provides a introduction to using La@TeX{}.
 
 
 @menu
+* An example of a musicological document::  
 * Integrating Texinfo and music::  
 * Integrating LaTeX and music::  
 * Integrating HTML and music::  
@@ -45,6 +46,109 @@ Short Introduction to LaTeX} provides a introduction to using La@TeX{}.
 
 
 
+
+@node An example of a musicological document
+@section  An example of a musicological document
+
+@cindex musicology
+@cindex La@TeX{}, music in
+@cindex HTML, music in
+@cindex Texinfo, music in
+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 HTML, La@TeX{}, and Texinfo 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
+
+@verbatim
+\documentclass[a4paper]{article}
+\begin{document}
+
+Documents for lilypond-book may freely mix music and text.  For
+example,
+
+\begin{lilypond}
+\relative {
+  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 in a separate file, and introduced with
+\verb+\lilypondfile+.
+
+\lilypondfile[quote,noindent]{screech-boink.ly}
+
+\end{document}
+@end verbatim
+
+Under Unix, you can view the results as follows
+
+@example
+cd input/tutorial
+mkdir -p out/
+lilypond-book --output=out/ lilybook.tex
+@emph{lilypond-book (GNU LilyPond) 2.3.11}
+@emph{Reading `input/tutorial/lilybook.tex'}
+@emph{..lots of stuff deleted..}
+@emph{Compiling `out//lilybook.tex'}
+cd out
+latex lilybook
+@emph{lots of stuff deleted}
+xdvi lilybook 
+@end example
+
+To convert the file into a nice PDF document, run the following
+commands
+
+@example
+dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
+ps2pdf lilybook.ps
+@end example
+
+Running lilypond-book and running 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 La@TeX{} example shown above.@footnote{ This
+tutorial is processed with Texinfo, so the example is as well.  This
+gives slightly different results in layout.}  This finishes the
+tutorial section.
+
+@page
+
+Documents for 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 in a separate file, and introduced with
+@code{\lilypondfile}.
+
+@lilypondfile[quote,noindent]{screech-boink.ly}
+
+
 @cindex texinfo
 @cindex latex
 @cindex texinfo