Lilypond-book: Rewrite docs for MusicXML snippets

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

diff --git a/Documentation/usage/lilypond-book.itely b/Documentation/usage/lilypond-book.itely
index 86cc588778f2c6592ad9cdfec69c4d8e8f0bcb8b..31590d91dd101a0045ca0580aebddc4bfc9edf42 100644 (file)
--- a/Documentation/usage/lilypond-book.itely
+++ b/Documentation/usage/lilypond-book.itely
@@ -200,27 +200,44 @@ See
 @emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
 to use @LaTeX{}.
 
-Music is entered using
+@code{lilypond-book} provides the following commands and environments to include
+music in @LaTeX{} files:
+
+@itemize
+
+@item
+the @code{\lilypond@{...@}} command, where you can directly enter short
+lilypond code
+
+@item
+the @code{\begin@{lilypond@}...\end@{lilypond@}} environment, where you
+can directly enter longer lilypond code
+
+@item
+the @code{\lilypondfile@{...@}} command to insert a lilypond file
+
+@item
+the @code{\musicxmlfile@{...@}} command to insert a MusicXML file, which
+will be processed by @code{musicxml2ly} and @code{lilypond}.
+
+@end itemize
+
+In the input file, music is specified with any of the following commands:
 
 @example
 \begin@{lilypond@}[options,go,here]
   YOUR LILYPOND CODE
 \end@{lilypond@}
-@end example
 
-@noindent
-or
+\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
 
-@example
 \lilypondfile[options,go,here]@{@var{filename}@}
+
+\musicxmlfile[options,go,here]@{@var{filename}@}
 @end example
 
-@noindent
-or
 
-@example
-\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
-@end example
+@noindent
 
 Additionally, @code{\lilypondversion} displays the current version
 of lilypond.
@@ -397,26 +414,40 @@ 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
+@code{lilypond-book} provides the following commands and environments to include
+music into Texinfo files:
+
+@itemize
+
+@item
+the @code{@@lilypond@{...@}} command, where you can directly enter short
+lilypond code
+
+@item
+the @code{@@lilypond...@@end lilypond} environment, where you can directly
+enter longer lilypond code
+
+@item
+the @code{@@lilypondfile@{...@}} command to insert a lilypond file
+
+@item
+the @code{@@musicxmlfile@{...@}} command to insert a MusicXML file, which
+will be processed by @code{musicxml2ly} and @code{lilypond}.
+
+@end itemize
+
+In the input file, music is specified with any of the following commands
 
 @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}@}
+
+@@musicxmlfile[options,go,here]@{@var{filename}@}
 @end example
 
 Additionally, @code{@@lilypondversion} displays the current version
@@ -461,8 +492,51 @@ in-line image.  It always gets a paragraph of its own.
 @node HTML
 @subsection HTML
 
-Music is entered using
+@code{lilypond-book} provides the following commands and environments to include
+music in HTML files:
+
+@itemize
+
+@item
+the @code{<lilypond .... />} command, where you can directly enter short lilypond code
+
+@item
+the @code{<lilyond>...</lilypond>} environment, where you can directly enter longer
+lilypond code
+
+@item
+the @code{<lilypondfile>...</lilypondfile>} command to insert a lilypond file
+
+@item
+the @code{<musicxmlfile>...</musicxmlfile>} command to insert a MusicXML file, which
+will be processed by @code{musicxml2ly} and @code{lilypond}.
+
+@end itemize
+
+In the input file, music is specified with any of the following commands:
+
+\begin@{lilypond@}[options,go,here]
+  YOUR LILYPOND CODE
+\end@{lilypond@}
+
+\lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
+
+\lilypondfile[options,go,here]@{@var{filename}@}
+
+\musicxmlfile[options,go,here]@{@var{filename}@}
+@example
+<lilypond options go here>
+  YOUR LILYPOND CODE
+</lilypond>
+
+<lilypond options go here: YOUR LILYPOND CODE />
 
+<lilypondfile options go here>@var{filename}</lilypondfile>
+
+<musicxmlfile options go here>@var{filename}</musicxmlfile>
+@end example
+
+For example, you can write
 @example
 <lilypond fragment relative=2>
 \key c \minor c4 es g2
@@ -490,6 +564,9 @@ To include separate files, say
 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
 @end example
 
+@code{<musicxmlfile>} uses the same syntax as @code{<lilypondfile>}, but simply
+references a MusicXML file rather than a LilyPond file.
+
 For a list of options to use with the @code{lilypond} or
 @code{lilypondfile} tags, see @ref{Music fragment options}.