* make/lilypond-vars.make: centralize LILYPOND_BOOK_FLAGS setting.

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

diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index e0ad3a271e8ade88734490bd4d58e6ead53ca0d3..81c26f4693d26387147945e37c5a65a1f29f6555 100644 (file)
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -30,7 +30,7 @@ This procedure may be applied to La@TeX{}, @code{html} or Texinfo
 documents.  A tutorial on using lilypond-book is in @ref{Integrating
 text and music}.  For more information about La@TeX{}
 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
 documents.  A tutorial on using lilypond-book is in @ref{Integrating
 text and music}.  For more information about La@TeX{}
 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so

-Short Introduction to LaTeX} provides a introction to using La@TeX{}.
+Short Introduction to LaTeX} provides a introduction to using La@TeX{}.

 
 
 
 
 
 


@@ -78,7 +78,7 @@ show two simple examples here.  First a complete block:
 @noindent
 produces
 
 @noindent
 produces
 

-@lilypond
+@lilypond[fragment]

   c' d' e' f' g'2 g'
 @end lilypond
 
   c' d' e' f' g'2 g'
 @end lilypond
 


@@ -91,7 +91,7 @@ Then the short version:
 @noindent
 produces
 
 @noindent
 produces
 

-@lilypond[staffsize=11]{ <c' e' g'> }
+@lilypond[fragment,staffsize=11]{ <c' e' g'> }

 
 When producing texinfo, lilypond-book also generates bitmaps of the
 music, so you can make a HTML document with embedded music.
 
 When producing texinfo, lilypond-book also generates bitmaps of the
 music, so you can make a HTML document with embedded music.


@@ -135,7 +135,7 @@ We show some examples here:
 @noindent
 produces
 
 @noindent
 produces
 

-@lilypond[staffsize=26]
+@lilypond[fragment,staffsize=26]

   c' d' e' f' g'2 g'2
 @end lilypond
 
   c' d' e' f' g'2 g'2
 @end lilypond
 


@@ -148,7 +148,7 @@ Then the short version:
 @noindent
 produces
 
 @noindent
 produces
 

-@lilypond[staffsize=11]{<c' e' g'>}
+@lilypond[fragment,staffsize=11]{<c' e' g'>}

 
 The linewidth of the music will be adjust by examining the commands in
 the document preamble, the part of the document before
 
 The linewidth of the music will be adjust by examining the commands in
 the document preamble, the part of the document before


@@ -164,28 +164,13 @@ and the
 @end ignore
 are also interpreted.
 
 @end ignore
 are also interpreted.
 

-The titling from the @code{\header} section of the fragments can be
-imported by adding the following to the top of the La@TeX{} file:
+@cindex titling and lilypond-book
+@cindex @code{\header} in La@TeX{} documents

 
 

-@example
-\input titledefs.tex
-\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
-@end example

 
 The music will be surrounded by @code{\preLilyPondExample} and
 @code{\postLilyPondExample}, which are defined to be empty by default.
 
 
 The music will be surrounded by @code{\preLilyPondExample} and
 @code{\postLilyPondExample}, which are defined to be empty by default.
 

-@cindex titling and lilypond-book
-@cindex lilypond-book and titling
-@cindex @code{\header} in La@TeX{} documents
-
-To add titling from the @code{\header} section of the files, add the
-following to the top of the La@TeX{} file:
-@example
-\input titledefs.tex
-\def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
-@end example
-

 @cindex outline fonts
 @cindex type1 fonts
 @cindex dvips
 @cindex outline fonts
 @cindex type1 fonts
 @cindex dvips


@@ -201,6 +186,22 @@ the dvips command line:
 @noindent
 PDF can then be produced with @code{ps2pdf}.
 
 @noindent
 PDF can then be produced with @code{ps2pdf}.
 

+@cindex international characters
+@cindex latin1
+
+LilyPond does not use the LaTeX font handling scheme for lyrics and text
+markups, so if you use characters in your lilypond-book
+documents that are not included in the standard US-ASCII character set,
+include @code{\usepackage[latin1]@{inputenc@}} in the file 
+header but do not include @code{\usepackage[[T1]@{fontenc@}}. Character
+sets other than latin1 are not supported directly but may be handled by
+explicitly specifying the @code{font-name} property in LilyPond and
+using the corresponding LaTeX packages. Please consult the mailing list
+for more details.
+
+
+
+

 
 @node Integrating HTML and music
 @section Integrating HTML and music
 
 @node Integrating HTML and music
 @section Integrating HTML and music


@@ -218,16 +219,16 @@ of which lilypond-book will produce a HTML with appropriate image tags for the
 music fragments:
  
 @example
 music fragments:
  
 @example

-<lilypond relative=1 verbatim>
+<lilypond relative=2 verbatim>

   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 </lilypond>
 @end example
 
   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 </lilypond>
 @end example
 

-@lilypond[relative=1]
+@lilypond[fragment,relative=2]

   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 @end lilypond
 
   \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
 @end lilypond
 

-For inline pictures, use @code{<lilypond ... />} syntax, eg.
+For inline pictures, use @code{<lilypond ... />} syntax, e.g.

 @example
 Some music in <lilypond a b c/> a line of text.
 @end example
 @example
 Some music in <lilypond a b c/> a line of text.
 @end example


@@ -254,30 +255,25 @@ following options:
 
 @table @code
 @item verbatim
 
 @table @code
 @item verbatim

-CONTENTS is copied into the source enclosed in a verbatim block,
-followed by any text given with the @code{intertext} option, then
+@var{contents} is copied into the source, enclosed in a verbatim block;
+followed by any text given with the @code{intertext} option; then

 the actual music is displayed.  This option does not work with
 the short version of the music blocks:
 
 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 
 @item filename=@var{filename}
 the actual music is displayed.  This option does not work with
 the short version of the music blocks:
 
 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
 
 @item filename=@var{filename}

-name the file (for @code{printfilename} option). The argument should
-be unquoted. 
-
-@item staffsize=POINTS
-@lilypond[staffsize=31.41592658]
-\relative c' {
-  r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
-  d16[ g, a b] c[ a b g] d'8[ g f\prall g]
-}
-@end lilypond
+This names the file for the @code{printfilename} option. The argument
+should be unquoted.
+
+@item staffsize=@var{ht}
+Sets the staff height to @var{ht}, which is measured in points.

 
 @item raggedright
 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
 works well for small music fragments.
 
 
 @item raggedright
 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
 works well for small music fragments.
 

-@item linewidth=@var{size}\\@var{unit}
+@item linewidth=@var{size}\@var{unit}

 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
 This option affects LilyPond output, not the text layout.
 
 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
 This option affects LilyPond output, not the text layout.
 


@@ -287,17 +283,17 @@ prevents printing time signature.
 @item fragment
 @item nofragment
 overrides @command{lilypond-book} auto detection of what type of code is
 @item fragment
 @item nofragment
 overrides @command{lilypond-book} auto detection of what type of code is

-in the LilyPond block, voice contents or complete code.
+in the LilyPond block, voice contents, or complete code.

 
 

-@item indent=@var{size}\\@var{unit}
+@item indent=@var{size}\@var{unit}

 sets indentation of the first music system to @var{size},
 where @var{unit} = cm, mm, in, or pt.  This option affects LilyPond,
 sets indentation of the first music system to @var{size},
 where @var{unit} = cm, mm, in, or pt.  This option affects LilyPond,

-not the text layout.  For single-line fragments the default is to
+not the text layout.  For single-line fragments, the default is to

 use no indentation.
 
 For example
 @example
 use no indentation.
 
 For example
 @example

-  \begin[indent=\\5cm,raggedright]@{lilypond@}
+  \begin[indent=5\cm,raggedright]@{lilypond@}

   ...
   \end@{lilypond@}
 @end example
   ...
   \end@{lilypond@}
 @end example


@@ -307,6 +303,10 @@ For example
 sets indentation of the first music system to zero.  This option
 affects LilyPond, not the text layout.
 
 sets indentation of the first music system to zero.  This option
 affects LilyPond, not the text layout.
 

+@item quote
+sets linewidth to the width of a quotation and puts the output
+in a quotation block.
+

 @item texidoc
 Includes the @code{texidoc} field, if defined in the file. This is
 only for Texinfo output.
 @item texidoc
 Includes the @code{texidoc} field, if defined in the file. This is
 only for Texinfo output.


@@ -324,8 +324,11 @@ documents are composed from small @file{.ly} files in this way:
 
 @item relative, relative=@var{N}
 uses relative octave mode.  By default, notes are specified relative
 
 @item relative, relative=@var{N}
 uses relative octave mode.  By default, notes are specified relative

-central C.  The optional integer argument specifies the octave of the
-starting note, where the default @code{1} is central C.
+to middle C.  The optional integer argument specifies the octave of the
+@item relative, relative=@var{N}
+uses relative octave mode.  By default, notes are specified relative
+to middle C.  The optional integer argument specifies the octave of the
+starting note, where the default @code{1} is middle C.

 @end table
 
 
 @end table
 
 


@@ -335,14 +338,8 @@ starting note, where the default @code{1} is central C.
 
 Running @command{lilypond-book} generates lots of small files that
 LilyPond will process.  To avoid all that garbage in the source
 
 Running @command{lilypond-book} generates lots of small files that
 LilyPond will process.  To avoid all that garbage in the source

-directory, it is advisable to change to a temporary directory first:
-@example
-cd out && lilypond-book ../yourfile.tex
-@end example
-
-@noindent
-or to use the @option{--output} command line option, and change to
-that director before running La@TeX{} or @file{makeinfo}:
+directory use the @option{--output} command line option, and change to
+that directory before running La@TeX{} or @file{makeinfo}:

 
 @example
 lilypond-book --output=out yourfile.lytex
 
 @example
 lilypond-book --output=out yourfile.lytex


@@ -355,7 +352,7 @@ cd out && latex yourfile.tex
 @table @code
 @item @option{-f @var{format}}, @option{--format=@var{format}}
 Specify the document type to process: @code{html}, @code{latex} or
 @table @code
 @item @option{-f @var{format}}, @option{--format=@var{format}}
 Specify the document type to process: @code{html}, @code{latex} or

-@code{texi} (the default).  @command{lilypond-book} usually figures this
+@code{texi} (the default).  @command{lilypond-book}  figures this

 out automatically.
 
 The @code{texi} document type produces a texinfo file with music
 out automatically.
 
 The @code{texi} document type produces a texinfo file with music


@@ -382,7 +379,7 @@ Place generated files in @var{dir}.
 
 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
 Process lilypond snippets using @var{command}.  The default command is
 
 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
 Process lilypond snippets using @var{command}.  The default command is

-@var{lilypon-bin}.
+@code{lilypond}.

 
 @item @option{--verbose}
 Be verbose.
 
 @item @option{--verbose}
 Be verbose.


@@ -407,13 +404,7 @@ La@TeX{} commands that change margins and line widths are ignored.
 Only the first @code{\score} of a LilyPond block is processed.
 
 @c CHECKME--FIXME
 Only the first @code{\score} of a LilyPond block is processed.
 
 @c CHECKME--FIXME

-The size of a music block is limited to 1.5 kb, due to technical
+The size of a music block is limited to 1.5 KB, due to technical

 problems with the Python regular expression engine.  For longer files,
 use @code{\lilypondfile}.
 
 problems with the Python regular expression engine.  For longer files,
 use @code{\lilypondfile}.
 

-@command{lilypond-book} processes all music fragments in one big run.
-The state of the GUILE interpreter is not reset between fragments;
-this means that changes made to global GUILE definitions, e.g. done
-with @code{set!} or @code{set-cdr!}, can leak from one fragment into
-the next fragment.
-