From: fred Date: Wed, 27 Mar 2002 01:02:49 +0000 (+0000) Subject: lilypond-1.3.149 X-Git-Tag: release/1.5.59~715 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=b8676b4aef4ca5e76602a25fb8261921e34f2697;p=lilypond.git lilypond-1.3.149 --- diff --git a/Documentation/user/convert-ly.itexi b/Documentation/user/convert-ly.itexi index f8af4c7df8..255b30fbfd 100644 --- a/Documentation/user/convert-ly.itexi +++ b/Documentation/user/convert-ly.itexi @@ -8,7 +8,7 @@ Convert-ly sequentially applies different conversions to upgrade a Lilypond input file. It uses @code{\version} statements in the file to detect the old version number. -@subsection Invoking convert-ly +@unnumberedsubsec Invoking convert-ly @example convert-ly [OPTION]... [FILE]... @@ -20,28 +20,38 @@ detect the old version number. If version number cannot be determined, apply all conversions. @item -e,--edit Do an inline edit of the input file. override @code{--output} -@item -f,--from=@var{FROM_PATCHLEVEL} +@item -f,--from=@var{from-patchlevel} Set the level to convert from. If this is not set, convert-ly will guess this, on the basis of @code{\version} strings in the file -@item -o,--output - The output file to write. +@item -o,--output=@var{file} + Set the output file to write. @item -n,--no-version Normally, convert-ly adds a @code{\version} indicator to the output. Specifying this option suppresses this. @item --show-rules - shows all known conversions, and exit -@item --to=@var{TO_PATCHLEVEL} + 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. @end table +@unnumberedsubsec Example + +Upgrade all lilypond files to 1.3.150: +@example + convert-ly -e --to=1.3.150 `find -name '*.ly'` +@end example + +@unnumberedsubsec Bugs + Not all language changes are handled. Multiple output options won't work. +@unnumberedsubsec Authors + @code{convert-ly} is written in @uref{http://www.python.org,Python}. It was written by @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}. Report bugs to @code{bug-gnu-music@@gnu.org} - diff --git a/Documentation/user/converters.itely b/Documentation/user/converters.itely index 9522f50cd6..bfedd23c62 100644 --- a/Documentation/user/converters.itely +++ b/Documentation/user/converters.itely @@ -26,8 +26,8 @@ to import files from a program that has no converter for its native format. It is possible to record a MIDI file using a digital keyboard, and then -convert it to @file{.ly}. However, human players can not rhythmically -exact enough to make a MIDI to .ly conversion trivial. midi2ly tries to +convert it to @file{.ly}. However, human players are not rhythmically +exact enough to make a MIDI to LY conversion trivial. midi2ly tries to compensate for these timing errors, but is not very good at this. It is therefore not recommended to use midi2ly for human-generated midi files. Correcting the quantization mistakes of the human player takes a diff --git a/Documentation/user/internals.itely b/Documentation/user/internals.itely index cc485a3ae3..84b0429334 100644 --- a/Documentation/user/internals.itely +++ b/Documentation/user/internals.itely @@ -10,32 +10,17 @@ @node Internals @chapter Internals -@menu -* Conversion stages:: Lilypond is a multi-pass program. -* Moment:: -* Grobs:: Graphical object -* Duration:: -* Pitch data type:: -* Engraver:: -* Music_iterator:: -* Music:: -* Molecules:: Molecules are stand-alone descriptions of output -* Font metrics:: Font metrics -* Miscellaneous Scheme functions:: -@end menu - -@node Conversion stages -@section Conversion stages When translating the input to notation, there are number of distinct phases. We list them here: -@table @code +@table @b @item Parsing: -The .ly file is read, and converted to a list of @code{Scores}, which -each contain @code{Music} and paper/midi-definitions. +The LY file is read, and converted to a list of @code{Scores}, which +each contain @code{Music} and paper/midi-definitions. Here @code{Music}, +@code{Pitch} and @code{Duration} objects are created. @item Interpreting music @cindex interpreting music @@ -45,7 +30,13 @@ All music events are "read" in the same order as they would be played events are delivered to interpretation contexts, @cindex engraver -which use them to build grobs (or MIDI objects, for MIDI output). +which use them to build @code{Grob}s (or MIDI objects, for MIDI output). + +In this stage @code{Music_iterators} do a traversal of the @code{Music} +structure. The music events thus encountered are reported to +@code{Translator}s, a set objects that collectively form interpretation +contexts. + @item Prebreaking @@ -76,10 +67,44 @@ spanner grob will only reference other grobs in the same line. @item Outputting: All vertical dimensions and spanning objects are computed, and all grobs -are output, line by line. +are output, line by line. The output is encoded in the form of +@code{Molecule}s @end table +The data types that are mentioned here are all discussed in this +section. + +@menu +* Input location:: +* Moment:: +* Duration:: +* Pitch data type:: +* Music:: +* Music_iterator:: +* Translator:: +* Grobs:: Graphical object +* Molecules:: Molecules are stand-alone descriptions of output +* Font metrics:: Font metrics +* Miscellaneous Scheme functions:: +@end menu + +@node Input location +@section input location + +The parser generates + +Input location objects point to a lcoation in the input file. This +location is used to generate error messages and to enable the point and +click output. + +@defun ly-input-location? +Type predicate +@end defun + + + + @node Moment @section Moment @@ -93,6 +118,116 @@ so we created our own rational data type. create the rational number @var{num}/@var{den}. @end defun +@node Duration +@section Duration + +A duration is a musical duration, i.e. a length of time described by a +power of two (whole, half, quarter, etc.) and a number of augmentation +dots. + +@defun make-duration length dotcount + +@var{length} is the negative logarithm (base 2) of the duration: +1 is a half note, 2 is a quarter note, 3 is an eighth +note, etc. The number of dots after the note is given by +@var{dotcount}. +@end defun + + +@defun duration? d +type predicate for Duration +@end defun + +@node Pitch data type +@section Pitch data type + + + +@defun make-pitch octave note shift + +@var{octave} is specified by an integer, zero for the octave containing +middle C. @var{note} is a number from 0 to 6, with 0 corresponding to C +and 6 corresponding to B. The shift is zero for a natural, negative for +flats, or positive for sharps. +@end defun + +@defun pitch-octave p +extract the octave from pitch @var{p}. +@end defun + +@defun pitch-notename p +extract the note name from pitch @var{p}. +@end defun + +@defun pitch-alteration p +extract the alteration from pitch @var{p}. +@end defun + +@defun pitch-semitones p +calculate the number of semitones of @var{p} from central C. +@end defun + +@defun Pitch::transpose t p +Transpose @var{p} by the amount @var{t}, where @var{t} is the pitch that +central C is transposed to. +@end defun + + +@node Music +@section Music + +Music is the data type that music expressions are stored in. The data +type does not yet offer many manipulations. + +@defun ly-get-mus-property m sym +Get the property @var{sym} of music expression @var{m}. +@end defun + +@defun ly-set-mus-property m sym val +Set property @var{sym} in music expression @var{m} to @var{val}. +@end defun + +@defun ly-make-music name +Make a music object/expression of type @var{name}. Warning: this +interface will likely change in the near future. +@end defun + +@defun music? obj +A type predicate, return true if @var{obj} is a music object. +@end defun + +@defun ly-music-name music +Print the name of @var{music}. +@end defun + + +@node Music_iterator +@section Music_iterator + +Music_iterator is an object type that traverses the Music structure and +reports the events it finds to interpretation contexts. It is not yet +user-serviceable. + +@defun c++-function? +type predicate for c++-function. Music_iterator are created from +schemified C++ constructors. Such a constructor is a @code{c++-function}. +@end defun + +@node Translator +@section Translator + +Translators are the building blocks of contexts. They are not yet user +accessible. + +@defun ly-get-trans-property tr sym +retrieve the value of @var{sym} from context @var{tr} +@end defun + +@defun ly-set-trans-property tr sym val +set value of property @var{sym} in context @var{tr} to @var{val}. +@end defun + + @node Grobs @section Grobs @@ -109,11 +244,8 @@ The most simple interaction with Grobs are when you use @end example This piece of lily input causes all stem objects to be stem-up -henceforth. In effect, you are telling lilypond to extend the defintion -of the "Stem" grob with the setting @code{direction := 1}. Of course -there are many more ways of customizing Lily output, and since most of -them involve Grobs in some form, this section explains some details of -how grobs work. +henceforth. In effect, you are telling lilypond to extend the definition +of the `Stem' grob with the setting @code{direction := 1}. @menu * What is a grob?:: @@ -131,28 +263,27 @@ how grobs work. In music notation, lots of symbols are related in some way. You can think of music notation as a graph where nodes are formed by the -symbols, and the arcs by their relations. A grob is node in that -graph. A grob stores references to other grobs, the directed edges in -the graph. +symbols, and the arcs by their relations. A grob is node in that graph. +The directed edges in the graph are formed by references to other grobs +(i.e. pointers). -The objective of this big graph of grobs, is to specify the notation -problem. The solution of this problem is a description of the printout -that is in closed form, i.e. but a list of values. These values are -Molecules. (see @ref{Molecules}) +This big graph of grobs specifies the notation problem. The solution of +this problem is a description of the printout in closed form, i.e. a +list of values. These values are Molecules. (see @ref{Molecules}) All grobs have an X and Y-position on the page. These X and Y positions are stored in a relative format, so they can easily be combined by stacking them, hanging one grob to the side of another, and coupling them into a grouping-grob. -Each grob has a reference point, or parent: the position of a grob is -stored relative to that reference point. For example the X-reference +Each grob has a reference point (a.k.a. parent): the position of a grob +is stored relative to that reference point. For example the X-reference point of a staccato dot usually is the note head that it applies -to. Whenever the note head is moved, the staccato dot moves along +to. When the note head is moved, the staccato dot moves along automatically. If you keep following offset reference points, you will always end up at -the root-object. This root object is called @code{Line_of_score}, and it +the root object. This root object is called @code{Line_of_score}, and it represents a system (ie. a line of music). All grobs carry a set of grob-properties. In the Stem example above, @@ -162,24 +293,14 @@ that draws the symbol (@code{Stem::brew_molecule}) uses the value of appearance of a grob is determined solely by the values of its properties. -Often, a grob also is associated with a symbol. However, some -grobs do not print any symbols, but take care of grouping objects. For -example, there is a separate grob that stacks staffs vertically, so they -are not printed in overstrike. The @code{NoteCollision} is another -example of an abstract grob. It only moves around chords, but doesn't -print anything. - -A complete list of grob types is found in -@ref{(lilypond-internals)LilyPond backend} - -Grobs are created in the "Interpreting music" phase, by objects in -LilyPond called engravers. In this phase of the translation, a load of -grobs are created, and they are linked into a giant network of objects. -This network of grobs forms the "specification" of the print -problem. This problem is then solved: configurations, directions, -dimensions, line breaks, etc. are calculated. Finally, the printing -description in the form of Molecules (@ref{Molecules}) is extracted from -the network. These are then dumped into the output file +A grob is often associated with a symbol, but some grobs do not print +any symbols. They take care of grouping objects. For example, there is a +separate grob that stacks staffs vertically. The @code{NoteCollision} +also is an abstract grob: it only moves around chords, but doesn't print +anything. + +A complete list of grob types is found in the generated documentation. + @node Callbacks @subsection Callbacks @@ -206,7 +327,8 @@ automatically execute all callbacks for that object. In this case, it will find @code{my-callback}, and execute that. The result is that the stem is translated by two staff spaces in its direction. -(note: Y-offset-callbacks is also a property) +(note: @code{Y-offset-callbacks} is also a property) + Offset callbacks can be stacked, ie. @@ -217,12 +339,12 @@ Offset callbacks can be stacked, ie. @end example -The callbacks will be executed in the order callback3 callback2 -callback1. This is used for quantized positioning: the staccato dot is +The callbacks will be executed in the order @code{callback3 callback2 +callback1}. This is used for quantized positioning: the staccato dot is above or below a note head, and it must not be on a staff-line. To -achieve this, for the staccato there are two callbacks: one callback -that positions the grob above or below the note head, and one callback -that rounds the Y-position of the grob to the nearest open space. +achieve this, the staccato dot has two callbacks: one that positions the +grob above or below the note head, and one that rounds the Y-position of +the grob to the nearest open space. Similarly, the size of a grob are determined through callbacks, settable with grob properties @code{X-extent-callback} and @@ -236,7 +358,9 @@ extent in that coordinate. @subsection Setting grob properties Grob properties are stored as GUILE association lists, with symbols as -keys. From C++, element properties can be accessed using the functions +keys. In GUILE you can access these using functions described @ref{Grob +Scheme functions}. From C++, grob properties can be accessed using +these functions: @example SCM get_grob_property (SCM) const; @@ -248,34 +372,24 @@ keys. From C++, element properties can be accessed using the functions SCM remove_grob_property (const char* nm); @end example -In GUILE, LilyPond provides - -@example - ly-get-grob-property GROB SYMBOL - ly-set-grob-property GROB SYMBOL VALUE -@end example - -All lookup functions identify undefined properties with -end-of-list (ie. @code{'()} in Scheme or @code{SCM_EOL} in C) +All lookup functions identify undefined properties with end-of-list +(ie. @code{'()} in Scheme or @code{SCM_EOL} in C) Properties are stored in two ways: @itemize @bullet -@item mutable properties: -element properties that change from object to object. The storage of -these are private to a grob. Typically this is used to store lists of -pointers to other grobs +@item mutable properties. +grob properties that change from object to object. The storage of +these are private to a grob. For example pointers to other grobs are +always stored in the mutable properties. -@item immutable properties: -element properties that are shared across different grobs of the same +@item immutable properties. +Grob properties that are shared across different grobs of the same type. The storage is shared, and hence it is read-only. Typically, this -is used to store function callbacks, and values for shared element -properties are read from @file{scm/element-description.scm}. +is used to store function callbacks, and default settings. They are +initially read from from @file{scm/grob-description.scm}. @end itemize -There are two ways to manually set grob properties. - -You can change immutable grob properties. This is done with the -\override syntax: +You can change immutable grob properties with the \override syntax: @example \property Voice.Stem \override #'direction = #1 @@ -283,7 +397,7 @@ You can change immutable grob properties. This is done with the This will push the entry @code{'(direction . 1)} on the immutable property list for stems, in effect overriding the setting from -@file{scm/element-description.scm}. This can be undone by +@file{scm/grob-description.scm}. This can be undone by @example \property Voice.stem \revert #'direction @@ -298,14 +412,15 @@ shorthand, this does a @code{\revert} followed by a @code{\override} -The second way is \outputproperty. This construct looks like +You can change mutable properties with \outputproperty. This construct +looks like @example \context ContextName \outputproperty @var{pred} #@var{sym} = #@var{val} @end example -In this case, in every grob that satisfies @var{pred}, the property -assignment @var{sym} = @var{val} is done. For example +In this case, in every grob that satisfies @var{pred}, the grob property + @var{sym} is set to @var{val} is done. For example @example \outputproperty @@ -314,7 +429,7 @@ assignment @var{sym} = @var{val} is done. For example #'extra-offset = #'(-1.0 . 0.0) @end example -This shifts all elements that have a @code{text} property one staff +This shifts all grobs that have a @code{text} property one staff space to the left. This mechanism is rather clumsy to use, but it allows you tweak any setting of any grob. @@ -366,7 +481,7 @@ Other grobs have a shape that depends on the horizontal spacing. For example, slur, beam, tie, etc. These grobs form a subtype called @code{Spanner}. All spanners have two span-points (these must be @code{Item}s), one on the left and one on the right. The left bound is -also the X-reference point. +also the X-reference point of the spanner. Some items need special treatment for line breaking. For example, a clef is normally only printed at the start of a line (ie. after a line @@ -377,14 +492,16 @@ before the line break (at the end of a system), one version that is printed after the line break. Whether these versions are visible and take up space, is determined by -the outcome of the visibility-lambda. This is a function taking a -direction (-1, 0 or 1) and returns a cons of booleans, signifying wether -this grob should be transparent and have no extent. - +the outcome of the @code{visibility-lambda}. This grob property is a +function taking a direction (-1, 0 or 1) as argument. It returns a cons +of booleans, signifying whether this grob should be transparent and have +no extent. @node Grob Scheme functions @unnumberedsubsec Grob Scheme functions +Grob properties can be manipulated from Scheme. In practice, most +manipulations are coded in C++ because of tradition. @defun ly-get-grob-property g sym Get the value of a value in grob @var{g} of property @var{sym}. It @@ -404,97 +521,8 @@ left, and @code{1} for right. Typecheck: is @var{g} a grob? @end defun -@node Duration -@section Duration - -@defun make-duration length dotcount - -@var{length} is the negative logarithm (base 2) of the duration: -1 is a half note, 2 is a quarter note, 3 is an eighth -note, etc. The number of dots after the note is given by -@var{dotcount}. -@end defun - - -@defun duration? d -type predicate for Duration -@end defun - -@node Pitch data type -@section Pitch data type - - - -@defun make-pitch octave note shift - -@var{octave} is specified by an integer, zero for the octave -containing middle C. @var{note} is a number from 0 to 7, with 0 -corresponding to C and 7 corresponding to B. The shift is zero for a -natural, negative to add flats, or positive to add sharps. -@end defun - -@defun pitch-octave p -extract the octave from pitch @var{p}. -@end defun - -@defun pitch-notename -extract the note name from pitch @var{p}. -@end defun - -@defun pitch-alteration -extract the alteration from pitch @var{p}. -@end defun - -@defun pitch-semitones -calculate the number of semitones of @var{p} from central C. -@end defun - -@defun Pitch::transpose t p -Transpose @var{p} by the amount @var{t}, where @var{t} is the pitch that -central C is transposed to. -@end defun - -@node Engraver -@section Engraver - -Engravers are building blocks of contexts. They are not yet user accessible. - -@defun ly-get-trans-property tr sym -retrieve the value of @var{sym} from context @var{tr} -@end defun - -@defun ly-set-trans-property tr sym val -set value of property @var{sym} in context @var{tr} to @var{val}. -@end defun - -@node Music_iterator -@section Music_iterator - -This data-type is a direct hook into some C++ constructor functions. It -is not yet user-serviceable. -@defun c++-function? -type predicate for c++-function. -@end defun - -@node Music -@section Music - -Music is the data type that music expressions are stored in. The data -type does not yet offer many manipulations. -@defun ly-get-mus-property m sym -Get the property @var{sym} of music expression @var{m}. -@end defun - -@defun ly-set-mus-property m sym val -Set property @var{sym} in music expression @var{m} to @var{val}. -@end defun - -@defun ly-make-music name -Make a music object/expression of type @var{name}. Warning: this -interface will likely change in the near future. -@end defun @node Molecules @section Molecules @@ -504,8 +532,8 @@ interface will likely change in the near future. @cindex Output description The objective of any typesetting system is to put ink on paper in the -right places. For LilyPond, this final stage is left to the TeX and the -printer subsystem. For lily, the last stage in processing a score is +right places. For LilyPond, this final stage is left to the @TeX{} and +the printer subsystem. For lily, the last stage in processing a score is outputting a description of what to put where. This description roughly looks like @@ -516,18 +544,18 @@ looks like @end example you merely have to look at the tex output of lily to see this. -Internally these instructions are encoded in Molecules:@footnote{At some +Internally these instructions are encoded in Molecules.@footnote{At some point LilyPond also contained Atom-objects, but they have been replaced -by Scheme expressions, making the name outdated.}. A molecule is an -object that combines dimension information (how large is this glyph ?) -with what-to-print-where. +by Scheme expressions, making the name outdated.} A molecule is +what-to-print-where information that also contains dimension information +(how large is this glyph?). Conceptually, Molecules can be constructed from Scheme code, by translating a Molecule and by combining two molecules. In BNF notation: @example - Molecule = COMBINE Molecule Molecule +Molecule :: COMBINE Molecule Molecule | TRANSLATE Offset Molecule | GLYPH-DESCRIPTION ; @@ -535,7 +563,7 @@ notation: If you are interested in seeing how this information is stored, you can run with the @code{-f scm} option. The scheme expressions are then -dumped onto the output file. +dumped in the output file. All visible, i.e. non-transparant, grobs have a callback to create a Molecule. The name of the property is @code{molecule-callback}, and its @@ -553,7 +581,7 @@ type predicate. Construct a molecule by putting @var{mol2} next to @var{mol1}. @var{axis} can be 0 (x-axis) or 1 (y-axis), @var{dir} can be -1 (left or down) or 1 (right or up). @var{padding} specifies extra -space to add in between. The unit is global staff space. is the +space to add in between measured in global staff space. @end defun @defun ly-get-molecule-extent! mol axis @@ -563,7 +591,11 @@ Return a pair of numbers signifying the extent of @var{mol} in @defun ly-set-molecule-extent! mol axis extent Set the extent (@var{extent} must be a pair of numbers) of @var{mol} in -@var{axis} direction (0 or 1 for x and y axis respectively). +@var{axis} direction (0 or 1 for x- and y-axis respectively). + +Note that an extent @code{(A . B)} is an interval and hence @code{A} is +smaller than @code{B}, and is often negative. + @end defun @node Font metrics @@ -573,10 +605,10 @@ The font object represents the metric information of a font. Every font that is loaded into LilyPond can be accessed via Scheme. LilyPond only needs to know the dimension of glyph to be able to process -them. This information is stored in font metric files. LilyPond can -read two types of font-metrics: @TeX{} Font Metric files (tfm files) and -Adobe Font Metric files (@file{.afm} files). LilyPond will always try -to load afm files first since @file{.afm} files are more versatile. +them. This information is stored in font metric files. LilyPond can read +two types of font-metrics: @TeX{} Font Metric files (TFM files) and +Adobe Font Metric files (AFM files). LilyPond will always try to load +AFM files first they files are more versatile. @defun ly-get-default-font gr This returns the default font for grob @var{gr}. @@ -584,7 +616,7 @@ This returns the default font for grob @var{gr}. @defun ly-find-glyph-by-name font name This function retrieves a Molecule for the glyph named @var{name} in -@var{font}. The font must be available as a afm file. +@var{font}. The font must be available as an AFM file. @cindex afm file @end defun @@ -592,9 +624,6 @@ This function retrieves a Molecule for the glyph named @var{name} in @node Miscellaneous Scheme functions @section Miscellaneous Scheme functions -@defun ly-input-location? -type predicate -@end defun @defun ly-warn msg Scheme callable function to issue the warning @code{msg}. @@ -606,8 +635,8 @@ Return the current lilypond version as a list, e.g. @end defun @defun ly-gulp-file name -read file named @var{name}, and return its contents in a string. This -uses the lilypond search path. +Read the file named @var{name}, and return its contents in a string. The +file is looked up using the lilypond search path. @end defun @@ -616,13 +645,18 @@ type predicate. A direction is a -1, 0 or 1. @end defun @defun ly-number->string num - converts @var{num} without generating many decimals. It leaves a space -at the end. + converts @var{num} to a string without generating many decimals. It +leaves a space at the end. @end defun @defun set-lily-option sym val - Set a global option for the program. + Set a global option for the program. Supported options include +@table @code +@item midi-debug +If set to true, generate human readable MIDI +@end table -[todo: document interesting sym/val pairs ] +This function is useful to call from the command line: @code{lilypond -e +"(set-lily-option 'midi-debug #t)"} @end defun diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi index 9556542c6a..d1779bdbbb 100644 --- a/Documentation/user/invoking.itexi +++ b/Documentation/user/invoking.itexi @@ -6,9 +6,10 @@ @cindex options, command line @cindex switches +Usage: @example - lilypond [OPTION]... [FILE]... + lilypond @var{[OPTION]} ... @var{[file]}... @end example @unnumberedsec Options @@ -21,18 +22,18 @@ files. Multiple @code{-e} options may be given. They will be evaluated sequentially. @item -f,--format=@var{format} -Output format for sheet music. Choices are tex (for @TeX{} -output), ps (for PostScript), scm (for a Scheme -dump), and as (for ASCIIScript). +Output format for sheet music. Choices are @code{tex} (for @TeX{} +output), @code{ps} (for PostScript), @code{scm} (for a Scheme +dump), and @code{as} (for ASCII-art). @c TODO: TFMFONTS -For processing both the @TeX{} and the PostScript output, you must -have appropriate environment variables set. For @TeX{}, you have to -set @code{MFINPUTS} and @code{TEXINPUTS} to point to the directory -containing LilyPond metafont and .tex files. For processing the -PostScript with Ghostscript, you have to set @code{GS_FONTPATH} to -point to the directory containing LilyPond @file{pfa} files. +For processing both the @TeX{} and the PostScript output, you must have +appropriate environment variables set. For @TeX{}, you have to set +@code{MFINPUTS} and @code{TEXINPUTS} to point to the directory +containing LilyPond metafont and .tex files. For processing PostScript +output with Ghostscript you have to set @code{GS_FONTPATH} to point to +the directory containing LilyPond PFA files. Scripts to do this are included in @file{buildscripts/out/lilypond-profile} (for sh shells) and @@ -42,20 +43,20 @@ normally be run as part of your login process. @item -h,--help Show a summary of usage. -@item --include, -I=DIRECTORY -Add @file{DIRECTORY} to the search path for input files. +@item --include, -I=@var{directory} +Add @var{directory} to the search path for input files. @cindex file searching @cindex search path -@item -i,--init=FILE -Set init file to @file{FILE} (default: @file{init.ly}). +@item -i,--init=@var{file} +Set init file to @var{file} (default: @file{init.ly}). @item -m,--no-paper @cindex MIDI -Disable @TeX{} output. If you have a @code{\midi} definition, it will do the -midi output only. +Disable @TeX{} output. If you have a @code{\midi} definition midi output +will be generated. @item -M,--dependencies Output rules to be included in Makefile. -@item -o,--output=FILE -Set the default output file to @file{FILE}. +@item -o,--output=@var{FILE} +Set the default output file to @var{FILE}. @item -s,--safe Disallow untrusted @code{\include} directives, in-line Scheme evaluation, backslashes in @TeX{}, code. @@ -67,15 +68,17 @@ web). Volunteers are welcome to do a new audit. @item -v,--version Show version information @item -V,--verbose -Be 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 -When invoked with a filename that has no extension, LilyPond will try -adding `@file{.ly}' as an extension first. +When invoked with a filename that has no extension, LilyPond will try to +add @file{.ly} as an extension first. When LilyPond processes @file{filename.ly} it will produce @file{filename.tex} as output (or @file{filename.ps} for PostScript diff --git a/Documentation/user/ly2dvi.itexi b/Documentation/user/ly2dvi.itexi index fb08e7be11..653cf2a6ae 100644 --- a/Documentation/user/ly2dvi.itexi +++ b/Documentation/user/ly2dvi.itexi @@ -3,19 +3,16 @@ @node ly2dvi @chapter ly2dvi -@file{ly2dvi} is a Python script which creates input file for La@TeX{}, -based on information from the output files from LilyPond. -The script handles multiple files. If a LilyPond file name is -specified LilyPond is run to make an output (@TeX{}) file. +@file{ly2dvi} is a Python script that creates a nicely title output file +from an input file for La@TeX{}. It can create a DVI or PS file. It +works by running LilyPond on the input files, creating a La@TeX{} +wrapper around the output, and running La@TeX{} (and optionally +@code{dvips}). -One or more La@TeX{} files are created, based on information found -in the output (@TeX{}) files, and latex is finally run to create -one or more DVI files. - -@subsection Invoking ly2dvi +@unnumberedsubsec Invoking ly2dvi @example -ly2dvi [OPTION]... [FILE]... +ly2dvi @var{[OPTIONS]} ... @var{[FILE]}... @end example @unnumberedsec Options @@ -39,9 +36,11 @@ files. The temporary directory is created in the current directory as @code{ly2d @item -P,--postscript Also generate PostScript output. @item -s,--set=@var{KEY}=@var{VAL} - Add @var{key}= @var{val} to the settings, overriding those specified -in the files. Possible keys: language, latexheaders, latexpackages, latexoptions, -papersize, pagenumber, linewidth, orientation, textheight. + Add @var{KEY}= @var{VAL} to the settings, overriding those specified +in the files. Possible keys: @code{language}, @code{latexheaders}, +@code{latexpackages}, @code{latexoptions}, @code{papersize}, +@code{pagenumber}, @code{linewidth}, @code{orientation}, +@code{textheight}. @item -v,--version Show version information @item -V,--verbose @@ -51,9 +50,9 @@ Show the warranty with which GNU LilyPond comes. (It comes with @strong{NO WARRANTY}!) @end table -@subsection Titling layout +@unnumberedsubsec Titling layout -Ly2dvi extracts the following header fields from the .ly files to +Ly2dvi extracts the following header fields from the LY files to generate titling: @table @code @@ -62,29 +61,41 @@ generate titling: @item subtitle Subtitle, centered below the title. @item poet - Name of the poet, leftflushed below the below subtitle. + Name of the poet, left flushed below the below subtitle. @item composer - Name of the composer, rightflushed below the subtitle. + Name of the composer, right flushed below the subtitle. @item metre - Meter string, leftflushed below the below poet. + Meter string, left flushed below the below poet. @item opus - Name of the opus, rightflushed below the below composer. + Name of the opus, right flushed below the below composer. @item arranger - Name of the arranger, rightflushed below the opus. + Name of the arranger, right flushed below the opus. @item instrument Name of the instrument, centered below the arranger @item piece - Name of the piece, leftflushed below the instrument + Name of the piece, left flushed below the instrument +@item head + A text to print in the header of all pages. It is not called +@code{header}, because @code{\header} is a reserved word in LilyPond. +@item footer + A text to print in the footer of all pages @item tagline - Line to print at the bottom of last page. Default: ``Lily was here, -@var{version-number}''. + Line to print at the bottom of last page. The default text is ``Lily +was here, @var{version-number}''. @end table -@subsection Additional parameters +@cindex header +@cindex footer +@cindex page layout +@cindex titles + + + +@unnumberedsubsec Additional parameters Ly2dvi responds to several parameters specified in the LilyPond -file. They can be overridden by supplying the @code{--set} command line +file. They can be overridden by supplying a @code{--set} command line option. @table @code @@ -113,29 +124,27 @@ so you can add multiple packages using multiple @code{-s=latexpackages} options. read from the @code{\paper} block, if set. @item linewidth - Is read from the @code{\paper} block. + The music line width. It is normally read from the @code{\paper} +block. @item papersize - Specify the papersize. Is read from the @code{\paper} block. + The paper size (as a name, e.g. @code{a4}). It is normally read from +the @code{\paper} block. @end table -@subsection Environment variables +@unnumberedsubsec Environment variables @table @code @item LANG selects the language for the warning messages of Ly2dvi and LilyPond. @end table -@subsection Bugs - -Assumes that @code{cp} and @code{rm} are in the path. - -Cannot generate @TeX{} or @code{PostScript} only. +@unnumberedsubsec Bugs -If find something that you consider a bug, please send a bugreport (See -@ref{Bug reports}) to @email{bug-gnu-music@@gnu.org}. +Cannot generate @TeX{} or @code{PostScript} only. Send bugreports to to +@email{bug-gnu-music@@gnu.org}. -@subsection Authors +@unnumberedsubsec Authors @email{hanwen@@cs.uu.nl,Han-Wen Nienhuys}. diff --git a/lily/scm-option.cc b/lily/scm-option.cc index 666f08c575..8b26f5ece0 100644 --- a/lily/scm-option.cc +++ b/lily/scm-option.cc @@ -12,25 +12,29 @@ #include "lily-guile.hh" #include "scm-option.hh" -/* - TODO: mooie onschuldige test, en koel om allerleide dingen te kunnen zetten, - maar is dit nou wel handig voor gebruikert? - - -X, of -fps is hendiger dan - -e "(set-lily-option 'midi-debug #t)' +/* + This interface to option setting is meant for setting options are + useful to a limited audience. The reason for this interface is that + making command line options clutters up the command-line option name + space. - [niet voor niets tiepo in 139 announs..] -*/ + preferably, also dont use TESTING_LEVEL_GLOBAL, since it defeats + another purpose of this very versatile interface, which is to + support multiple debug/testing options concurrently. + + */ /* Write midi as formatted ascii stream? */ bool midi_debug_global_b; + /* General purpose testing flag */ int testing_level_global; + /* TODO: verzin iets tegen optie code bloot