From 81d90c881d2d3d2a66b333ba31e2aad266fb8ac1 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Sat, 15 Dec 2007 15:49:54 -0800 Subject: [PATCH] More Trevor. --- Documentation/user/tweaks.itely | 217 ++++++++++++++++++++++++++------ 1 file changed, 178 insertions(+), 39 deletions(-) diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely index 8889fb21c7..ff19d1889a 100644 --- a/Documentation/user/tweaks.itely +++ b/Documentation/user/tweaks.itely @@ -1710,7 +1710,7 @@ This may come as a surprise, but LilyPond is not perfect. Some notation elements can overlap. This is unfortunate, but in fact rather rare. Usually the need to move objects is for clarity or aesthetic reasons -- they would look better with a little more -space around them. +or a little less space around them. There are three main main approaches to resolving overlapping notation. They should be considered in the following order: @@ -1724,22 +1724,19 @@ Stems, slurs, beams, ties, dynamics, text and tuplets may be repositioned easily in this way. The limitation is that you have a choice of only two positions, and neither may be suitable. -@smallspace @item The @strong{object properties}, which LilyPond uses -when positioning layout objects, may be modified using +when positioning layout objects, may be modified using @code{\override}. The advantages of making changes to this type of property are (a) that some other objects will be moved automatically if necessary to make room and (b) the single override can apply to all instances of the same type of object. Such properties include: @itemize -@smallspace @item @code{direction} This has already been covered in some detail -- see @ref{Within-staff objects}. -@smallspace @item @code{padding}, @code{left-padding}, @code{right-padding}, @code{staff-padding} @@ -1783,7 +1780,7 @@ All padding values are measured in staff spaces. For most objects, this value is set by default to be around 1.0 or less (it varies with each object). It may be overridden if a larger (or smaller) gap is required. -@smallspace + @item @code{self-alignment-X} @cindex self-alignment-X property @@ -1794,21 +1791,22 @@ It may be used with all objects which support the that contain text. The values are @code{LEFT}, @code{RIGHT} or @code{CENTER}. The movement is limited by the length of the object. Any numerical value between @code{-1} and @code{+1} may -also be specified, where @code{-1} is left-aligned and @code{+1} -is right-aligned. -@smallspace -@item @code{extra-spacing-width} property +also be specified, where @code{-1} is left-aligned, @code{+1} +is right-aligned, and numbers inbetween move the text progressively +from left-aligned to right-aligned. + +@item @code{extra-spacing-width} @cindex extra-spacing-width property This property is available for all objects which support the @code{item-interface}. It takes two numbers, the first is added -to the leftmost extent and the second is added to the rightmost +to the leftmost extent and the second is added to the rightmost extent. Negative numbers move the edge to the left, positive to -the right. Note that not all objects honour both numbers. For -example, the @code{Accidental} object only takes notice of the -first (left edge) number. +the right, so to widen an object the first number must be negative, +the second positive. Note that not all objects honour both +numbers. For example, the @code{Accidental} object only takes +notice of the first (left edge) number. -@smallspace @item @code{staff-position} @cindex staff-position property @@ -1818,17 +1816,42 @@ objects which are positioned relative to the staff. It specifies the vertical position of the object relative to the center line of the staff in half staff-spaces. It is useful in resolving collisions between layout objects like multi-measure rests, ties -and notes in different voices. +and notes in different voices. + +@item @code{force-hshift} + +@cindex force-hshift property + +TODO Move this explanation and add expanation of \shiftOn etc to + Explicitly instantiating voices section in Fundamental concepts + +[Closely spaced notes in a chord, or notes occuring at the same +time in different voices, are arranged in two, occasionally more, +columns to prevent the noteheads overlapping. These are called +note columns, and an object called @code{NoteColumn} is created +to lay out the notes in that column. There are separate columns +for each voice.] +The @code{force-hshift} +property is a property of a @code{NoteColumn} (actually of the +@code{note-column-interface}). Changing it permits a note column +to be moved in units appropriate to a note column, viz. the note +head width of the first voice note. It should be used in +complex situations where the normal @code{\shiftOn} commands (see +@ref{Explicitly instantiating voices}) do +not resolve the note conflict. It is preferable to the +@code{extra-offset} property for this purpose as there is no need +to work out the distance in staff-spaces, and moving the notes +into or out of a @code{NoteColumn} affects other actions such as +merging noteheads. @end itemize Objects do not all have all of these properties in general. It is necessary to go to the IR to look up which properties are available for the object in question. -@smallspace @item -Finally, when all else fails, objects may be repositioned -vertically relative to the staff center line, or by +Finally, when all else fails, objects may be manually repositioned +relative to the staff center line verically, or by displacing them by any distance to a new position. The disadvantages are that the correct values for the repositioning have to be worked out, often by trial and error, for every object @@ -1839,7 +1862,6 @@ approach is that the repositioning values may need to be reworked if the music is later modified. The properties that can be used for this type of manual repositioning are: @itemize -@smallspace @item @code{extra-offset} @cindex extra-offset property @@ -1851,23 +1873,7 @@ the left or down. The units are staff-spaces. The extra displacement is made after the typesetting of objects is finished, so an object may be repositioned anywhere without affecting anything else. -@smallspace -@item @code{force-hshift} -@cindex force-hshift property -Closely spaced notes in a chord, or notes occuring at the same -time in different voices, are arranged in two, occasionally more, -columns to prevent the noteheads overlapping. These are called -note columns, and an object called @code{NoteColumn} is created -to lay out the notes in that column. There are separate columns -for each voice. The @code{force-hshift} -property is a property of a @code{NoteColumn} (actually of the -@code{note-column-interface}). Changing it permits a note column -to be moved in units appropriate to a note column, viz. the note -head width of the first voice note. It is preferable to the -@code{extra-offset} property for this purpose as there is no need -to work out the distance in staff-spaces. -@smallspace @item @code{positions} @cindex positions property @@ -1890,9 +1896,10 @@ involved in collisions, together with the name of the object which should be looked up in the IR in order to discover which properties should be used to move them. -@multitable @columnfractions .4 .6 +@multitable @columnfractions .5 .5 @headitem Object type @tab Object name @item Articulations @tab @code{Script} +@item Beams @tab @code{Beam} @item Dynamics (vertically) @tab @code{DynamicLineSpanner} @item Dynamics (horizontally) @tab @code{DynamicText} @item Fingerings @tab @code{Fingering} @@ -1900,6 +1907,7 @@ should be used to move them. @item Slurs @tab @code{Slur} @item Text e.g. @code{^"text"} @tab @code{TextScript} @item Ties @tab @code{Tie} +@item Tuplets @tab @code{TupletBracket} @end multitable @@ -2165,9 +2173,139 @@ TODO Examples of real music showing collisions and their resolution @section Page layout @menu +* Introduction to layout:: +* Global sizes:: +* Line breaks:: +* Page breaks:: * Fitting music onto fewer pages:: @end menu +@node Introduction to layout +@subsection Introduction to layout + +The global paper layout is determined by three factors: +the page layout, the line breaks, and the spacing. These all +influence each other. The choice of spacing determines how +densely each system of music is set. This influences where line +breaks are chosen, and thus ultimately, how many pages a piece +of music takes. + +Settings which influence layout may be placed in two blocks. +The @code{\paper @{ ... @}} block is placed outside any +@code{\score @{ ... @}} blocks and contains settings that +relate to the entire document. The @code{\layout @{ ... @}} +block is placed within a @code{\score @{ ... @}} block and +contains settings for that particular score. If you have +only one @code{\score @{ ... @}} block the two have the same +effect. In general the commands shown in this section can +be placed in either. + +Much more detail on the options for tweaking the laying out +of music are contained in @ruser{Spacing issues}. + +@node Global sizes +@subsection Global sizes + +The default @strong{paper size} which LilyPond assumes in laying +out the music is A4. This may be changed in two ways: + +@example +#(set-default-paper-size "a6") + +\paper @{ +#(set-paper-size "letter") +@} +@end example + +@noindent +The first command sets the size of all pages. The second command +sets the size of the pages to which the \paper block applies – if +the \paper block is at the top of the file, then it will apply +to all pages. Support for the following paper sizes are included: +a6, a5, a4, a3, legal, letter, 11x17 (also known as tabloid). + +If the symbol @code{landscape} is supplied as an argument to +@code{set-default-paper-size}, the pages will be rotated by 90 +degrees, and wider line widths will be set correspondingly, e.g. + +@example +#(set-default-paper-size "a6" 'landscape) +@end example + +The default @strong{staff size} is set to 20 points. +This may be changed in two ways: + +@example +#(set-global-staff-size 14) + +\paper @{ +#(set-global-staff-size 16) +@} +@end example + +@noindent +The first command sets the size in all pages. The second command +sets the size in the pages to which the \paper block applies – if +the \paper block is at the top of the file, then it will apply +to all pages. All the fonts are automatically scaled to suit +the new value of the staff size. + +@node Line breaks +@subsection Line breaks + +Line breaks are normally computed automatically. They are chosen +so that lines look neither cramped nor loose, and that consecutive +lines have similar density. Occasionally you might want to +override the automatic breaks; you can do this by specifying +@code{\break}. This will force a line break at this point. Line +breaks can only occur at the end of @q{complete} bars, i.e., where +there are no notes or tuplets left @q{hanging} over the bar line. +If you want to have a line break where there is no bar line, you +can force an invisible bar line by entering @code{\bar ""}. +Similarly, @code{\noBreak} forbids a line break at a point. + +The most basic settings influencing line spacing are @code{indent} +and @code{line-width}. They are set in the @code{\layout} block. +They control the indentation of the first line of music, and the +lengths of the lines. + +If @code{ragged-right} is set to true in the @code{\layout} block, +then systems end at their natural horizontal length, instead of +being spread horizontally to fill the whole line. This is useful +for short fragments, and for checking how tight the natural +spacing is. + +The option @code{ragged-last} is similar to @code{ragged-right}, +but only affects the last line of the piece. + +@example +\layout @{ +indent = #0 +line-width = #150 +ragged-last = ##t +@} +@end example + +@node Page breaks +@subsection Page breaks + +The default page breaking may be overriden by inserting +@code{\pageBreak} or @code{\noPageBreak} commands. +These commands are analogous to @code{\break} and @code{\noBreak}. +These commands force and forbid a page-break from happening. +Of course, the @code{\pageBreak} command also forces a line break. +Like @code{\break}, the @code{\pageBreak} command is effective only +at the end of a @q{complete} bar as defined above. For more +details see @ruser{Page breaking} and following sections. + +There are also analogous settings to @code{ragged-right} and +@code{ragged-last} which have the same effect on vertical spacing: +@code{ragged-bottom} and @code{ragged-last-bottom}. If set to +@code{##t} the systems on all pages or just the last page +respectively are not justified vertically. + +For more details see @ruser{Vertical spacing}. + @node Fitting music onto fewer pages @subsection Fitting music onto fewer pages @@ -2232,7 +2370,7 @@ Alter the horizontal spacing via @code{SpacingSpanner}. See @ruser{Changing horizontal spacing}, for more details. Here's an example first showing the default behaviour: -@lilypond[verbatim,quote] +@lilypond[verbatim,quote,ragged-right] \score { \relative c'' { g4 e e2 | @@ -2249,7 +2387,7 @@ and now with @code{common-shortest-duration} increased from the value of @code{1/4} (a quarter note is the most common in this example) to @code{1/2}: -@lilypond[verbatim,quote] +@lilypond[verbatim,quote,ragged-right] \score { \relative c'' { g4 e e2 | @@ -2492,3 +2630,4 @@ In some cases (see issue 246), this must be done before + -- 2.39.5