From 60b7a1f24ceeffcc67d0e878949dd4145e255f6a Mon Sep 17 00:00:00 2001 From: fred Date: Wed, 27 Mar 2002 01:02:54 +0000 Subject: [PATCH] lilypond-1.3.149 --- Documentation/user/lilypond-book.itely | 264 +++++++++++++------------ Documentation/user/refman.itely | 34 +++- 2 files changed, 161 insertions(+), 137 deletions(-) diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely index bfa123b1fe..d11d447ebd 100644 --- a/Documentation/user/lilypond-book.itely +++ b/Documentation/user/lilypond-book.itely @@ -1,29 +1,53 @@ - -@tex -\def\preLilypondExample{\vspace{0.5cm}} -@end tex - @node lilypond-book @chapter lilypond-book -[TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.] +@command{lilypond-book} runs Lilypond on fragments of lilypond in a +La@TeX{} or texinfo file, and includes the results into a document that +can be processed with La@TeX{}, @command{makeinfo} or +@command{texi2dvi}. The result is a text document containing formatted +music integrated. -@command{lilypond-book} is a script that helps integrating lilypond with -La@TeX{} or texinfo. @command{lilypond-book} runs Lilypond on fragments -of lilypond in your source file, and includes the results into a -document that can be processed with La@TeX{}, @command{makeinfo} or -@command{texi2dvi}. The result is a text document with formatted music -integrated. +More precisely, if a La@TeX{} file contains +@example -@command{lilypond-book} will do its best to try to align the music to -the left and right margins. Currently all papersizes, one- and -twocolumn mode and the @code{geometry} package is supported. -The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4. -But changing the linewidth in other ways will not give you a straight -right margin. + \begin@{lilypond@} + CONTENTS + \end@{lilypond@} + +@end example +or +@example + \lilypond@{CONTENTS@} +@end example +then LilyPond is run on CONTENTS. @command{lilypond-book} puts the +result back into the latex file. When you run the result through latex, +you get a document that mixes text and music. lilypond-book will insert +line width and font size definitions before @code{CONTENTS}, so the +music samples will match the layout of your document. + +Very often, if you mix music and text, the music is often only a few +notes or at most a few bars. This music should be as short as possible +and not stretched to be aligned to the right margin. lilypond-book does +this automatically if you don't use a @code{\score} block in +@code{CONTENTS}. For example: @code{\lilypond@{\context Voice +@}}. + +You can also use @code{lilypondfile} to include another file: +@example + \lilypondfile@{foo.ly@} +@end example + +All three forms can take several options. They are specified in brackets +as follows: +@example + \lilypondfile[options, go, here]@{ .. @} + \begin[options, go, here]@{lilypond@} .. \end@{lilypond@} + \lilypond[options, go,here]@{ .. @} +@end example + +In the texinfo version, bitmaps of the music are also generated, so you +can also make a HTML document with embedded music. -This document assumes you have basic knowledge of GNU LilyPond and -La@TeX{} or texinfo. @section TeXinfo reference @@ -32,14 +56,11 @@ Your markup the lilypond code like this: @@lilypond[options, go, here] YOUR LILYPOND CODE @@end lilypond -@end example - -or - -@example @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @} +@@lilypondfile[options, go,here]@{@var{filename}@} @end example + @command{lilypond-book} knows the default margins, and a few papersizes. These commands should be in the beginning of the document: @itemize @bullet @@ -74,51 +95,6 @@ and its music: @lilypond[11pt]{} - -@subsection @@example and @@code - -I'm not sure if this will go into the final documentation, this is -here mostly to remember me on why things are the way they are. - -@command{lilypond-book} will do nothing with special with @code{@@code} and -@code{@@example} environments. The 'code' and 'example' commands -should work just as normal. People looking at document that should be -processed by @command{lilypond-book}, should notice nothing special, except from -some block like this: -@example -@@lilypond -BLABLA -@@end lilypond -@end example - -or this: - -@code{@@lilypond@{ BLABLA @}} - -Anything other is a bug in @command{lilypond-book}. - -So to get this in the printed manual: - -@example -@@lilypond[26pt] -\relative c'@{c d e f g2 g@} -@@end lilypond -@end example - -you have to write this: - -@example -@@example -@@@@lilypond[26pt] -\relative c'@@@{c d e f g2 g@@@} -@@@@end lilypond -@@end example -@end example - -Simply explained, every '@{', '@}' and '@@' has to be written as '@@@{', -'@@@}' and '@@@@'. This is how it works in plain texinfo too. - - @section La@TeX{} reference Your markup the lilypond code like this: @@ -142,8 +118,6 @@ The music will be surrounded by @code{\preLilypondExample} and @code{\postLilypondExample}. The variables are defined to nothing by default, and the user can redefine them to whatever he wants. -@strong{[UGH: THIS DOES NOT HAPPEN WHEN -YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]} @subsection Examples @@ -169,17 +143,21 @@ and its music: @lilypond[11pt]{} -@subsection \begin@{verbatim@} and \verb|\verb| - -There work just as expected. Look at @file{mb-latex.tex} for details. - @section Options @table @code @item eps - the music is created as eps graphics that can be inserted in - the middle of a text line, not only as a separate paragraph. - (La@TeX{} only) +This will create the music as eps graphics and include it into the +document with the @code{\includegraphics} command. It works in Latex +only. + +This enables you to place music examples in the running text (and not in +a separate paragraph). To avoid that La@TeX{} places the music on a line +of its one, there should be no empty lines between the normal text and +the lilypond environment. For inline music, you probably also need a +smaller music font size (eg. 11 pt or 13 pt) + + @item verbatim CONTENTS is copied into the source enclosed in a verbatim block, followed by any text given with the @code{intertext} option, then @@ -188,21 +166,59 @@ There work just as expected. Look at @file{mb-latex.tex} for details. @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} } -@item intertext="text inside apostrophs" - Used in conjunction with @code{verbatim} option. -@item filename=FILENAME - Save the lilypond code to FILENAME instead of using a hash value - of CONTENTS. -@item 11pt, 13pt, 16pt, 20pt, 26pt - set the fontsize to use for the music +@item intertext="@var{text}" + Used in conjunction with @code{verbatim} option: this puts +@var{text} between the code and the music. +@item filename=@var{FILENAME} + Save the lilypond code to @var{FILENAME}. By default, a hash value +of the code is used. + +@item @code{11pt} +@lilypond[11pt, eps] + \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 +@item @code{13pt} +@lilypond[13pt, eps] + \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 +@item @code{16pt} +@lilypond[16pt, eps] + \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 +@item @code{20pt} +@lilypond[20pt, eps] + \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 +@item @code{26pt} +@lilypond[26pt, eps] + \relative c'{ + r16 [c d e][f d e c] [g'8 c][b-\prall c] | + } +@end lilypond + @item singleline - linewidth = -1. + Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1). @item multiline - linewidth = textwidth + The opposite of @code{singleline}: justify and break lines. @item fragment @item nofragment Override @command{lilypond-book} autodetection of what type of code is in the lilypond block, voice contents or complete code. +@item printfilename + Prints the file name before the music example. Useful in conjunction +with @code{\lilypondfile}. @end table @section Invocation @@ -217,10 +233,8 @@ directory, or use the @code{--outdir} commandline options: @code{lilypond-book --outdir=out yourfile.tex} -For latex input, the file to give to latex has ext @file{.latex}. -TeXinfo input will be written to a file with ext @file{.texi}. So be -careful, don't give the source file that ext, or the file will be -overwritten. +For latex input, the file to give to latex has extension @file{.latex}. +TeXinfo input will be written to a file with extension @file{.texi}. If you use @code{--outdir}, you should also @code{cd} to that directory before running LaTeX or makeinfo. This may seem a little kludgy, but @@ -228,24 +242,6 @@ both Latex and makeinfo expect picture files (the music) to be in the current working directory. Moreover, if you do this, LaTeX will not clutter you normal working directory with output files. -@strong{About the input} - -If the file contains the ``block'' - -@example - - \begin@{lilypond@} - CONTENTS - \end@{lilypond@} - -@end example - -then LilyPond is run on CONTENTS. @command{lilypond-book} puts the result back, -surrounded by @code{\preLilypondExample} and @code{\postLilypondExample} -commands. @code{\preLilypondExample} and @code{posLilypondExample} is -defined to nothing by default, and the user can redefine them -to whatever he wants. - @cindex titling and lilypond-book @cindex lilypond-book and titling @cindex \header in LaTeX documents @@ -266,34 +262,37 @@ files, you should add the following to the top of your LaTeX @item @option{-f}, @option{--format=} Specify the document type to process, @code{latex} or @code{texi}. @command{lilypond-book} usually figure out this automatically. -@item --default-music-fontsize=??pt +@item --default-music-fontsize=@var{sz}pt Set the fontsize to use for lilypond if no fontsize is given as option. -@item --force-music-fontsize=??pt +@item --force-music-fontsize=@var{sz}pt Force all lilypond to use this fontsize, overriding options - given to \begin@{lilypond@} -@item -I DIR, --include=DIR - include path + given to @code{\begin@{lilypond@}} +@item -I @var{DIR}, --include=@var{DIR} + Add @var{DIR} to the include path. @item -M, --dependencies - Write dependencies to out-www/filename.dep -@item --dep-prefix=PREF - prepend PREF before each -M dependency + Write dependencies to @file{filename.dep} +@item --dep-prefix=@code{PREF} + prepend @code{PREF} before each @code{-M} dependency @item -n, --no-lily - don't run lilypond + don't run lilypond, but do generate the @code{.ly} files @item --no-pictures - don't generate pictures + don't generate pictures when processing texinfo. @item --read-lys don't write ly files. This way you can do - @example - lilypond-book file.tely - convert-ly - lilypond-book --read-lys - @end example -@item --outname=FILE +@example + lilypond-book file.tely + convert-ly + lilypond-book --read-lys +@end example + +[TODO not a useful option unless you can undump the input file] + +@item --outname=@var{FILE} The name of La@TeX{} file to output. If this option is not given, the output name derived from the input name. -@item --outdir= - where to place generated files +@item --outdir=@var{DIR} + place generated files in @var{DIR}. @item --version print version information @item --help @@ -311,8 +310,17 @@ files, you should add the following to the top of your LaTeX The La@TeX{} \includeonly@{...@} command is ignored. +The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4. +But changing the linewidth in other ways will not give you a straight +right margin. + Ignores almost all La@TeX{} commands that changes margins and linewidths. +Since there is no finder's fee which doubles every year, there is no +need to wait for the prize money to grow. So send a bug report today if +you need this one of these options. + + @section Authors @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/people/hanwen} diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 2bfd92808a..fd99c88485 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -2367,7 +2367,7 @@ names: \score { \notes { \property Staff.instrument = #`((kern . 0.5) (lines - "2 Clarinetti" (rows " (B" ,text-flat ")"))) + "2 Clarinetti" (columns " (B" ,text-flat ")"))) c'' 4 } } @end lilypond @@ -3009,7 +3009,8 @@ text: string | (head? text+) head: markup | (markup+) markup-item: property | abbrev property: (@var{key} . @var{value}) -abbrev: @code{rows lines roman music bold italic named super sub text} +abbrev: @code{columns lines roman music bold italic named super sub +overstrike text} @code{finger volta timesig mmrest mark script large Large dynamic} @end example @@ -3020,8 +3021,8 @@ the generated documentation for @code{text-interface} The following abbreviations are currently defined: @table @code -@item rows -horizontal mode: set all text on one line (default) +@item columns + horizontal mode: set all text on one line (default) @item lines vertical mode: set every text on a new line @item roman @@ -3042,6 +3043,8 @@ and uses named lookup superscript @item sub subscript +@item overstrike + the next text or character overstrikes this one @item finger select fingering number fontstyle @item volta @@ -3069,16 +3072,16 @@ One practical application of complicated markup is to fake a metronome marking: @lilypond[verbatim] -#(define note '(rows +#(define note '(columns (music "noteheads-2" ((kern . -0.1) "flags-stem")))) -#(define eight-note `(rows ,note ((kern . -0.1) +#(define eight-note `(columns ,note ((kern . -0.1) (music ((raise . 3.5) "flags-u3"))))) #(define dotted-eight-note - `(rows ,eight-note (music "dots-dot"))) + `(columns ,eight-note (music "dots-dot"))) \score { \notes\relative c'' { - a1^#`((rows (font-relative-size . -1)) ,dotted-eight-note " = 64") + a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64") } \paper { linewidth = -1. @@ -3432,6 +3435,10 @@ LilyPond produce @TeX{} first. The .tex output must be processed by is used to generate PostScript. Alternatively, @file{ly2dvi} can be used to generate the .dvi for you. +@refbugs + +Titling is not generated. + @node PostScript output @subsection PostScript output @@ -3465,7 +3472,16 @@ created through direct postscript output, you should prepend the necessary .pfa files to LilyPond's .ps output, or upload them to the printer before printing. -Titling is not generated. +The line height calculation is broken, you must set @var{lineheight} in +the paperblock if you have more than one staff in your score, e.g. + +@example + ... + \paper @{ + % Set line height to 40 staff spaces + lineheight = 40 + @} +@end example @node Scheme output @subsection Scheme output -- 2.39.5