From 418f2ce9a7628b97038f947d77c7837dc88a2e8a Mon Sep 17 00:00:00 2001 From: Han-Wen Nienhuys Date: Fri, 28 Jun 2002 23:50:58 +0000 Subject: [PATCH] '' --- ChangeLog | 6 ++ Documentation/user/macros.itexi | 10 ++ Documentation/user/refman.itely | 16 +-- Documentation/user/tutorial.itely | 164 ++++++++++++++++++++++++++---- input/tutorial/brahms-original.ly | 3 +- scm/generate-documentation.scm | 4 +- scm/grob-description.scm | 23 +++-- scm/grob-property-description.scm | 7 +- 8 files changed, 185 insertions(+), 48 deletions(-) diff --git a/ChangeLog b/ChangeLog index 25548ba528..6bcbc56977 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2002-06-29 Han-Wen + + * Documentation/user/tutorial.itely (Fine tuning a piece): more tut. + + * scm/grob-description.scm (all-grob-descriptions): sort list + 2002-06-27 Jan Nieuwenhuizen * Documentation/topdocs/FAQ.texi (Installation): Add diff --git a/Documentation/user/macros.itexi b/Documentation/user/macros.itexi index 96c445838a..7902ad02d6 100644 --- a/Documentation/user/macros.itexi +++ b/Documentation/user/macros.itexi @@ -131,3 +131,13 @@ $\\flat$ @end ignore + +@ifhtml +@macro internalsref{NAME} +@uref{../lilypond-internals/\NAME\.html,\NAME\} +@cindex \NAME\ +@end macro +@macro seeinternals{NAME} +See @internalsref{\NAME\} +@end macro +@end ifhtml diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 0557af6f1a..38c8e1e3e6 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -12,15 +12,6 @@ @end macro -@ifhtml -@macro internalsref{NAME} -@uref{../lilypond-internals/\NAME\.html,\NAME\} -@cindex \NAME\ -@end macro -@macro seeinternals{NAME} -See @internalsref{\NAME\} -@end macro -@end ifhtml @ifnothtml @@ -1144,15 +1135,16 @@ automatic beaming in irregular meters such as @code{5/8}. @node Slurs @subsection Slurs -@cindex slurs +@cindex Slurs A slur indicates that notes are to be played bound or @emph{legato}. They are entered using parentheses: - @lilypond[fragment,verbatim,center] f'()g'()a' [a'8 b'(] a'4 g'2 )f'4 @end lilypond +The grob for this object is @internalsref{Slur}, generally in +@internalsref{Voice} context. Slurs avoid crossing stems, and are generally attached to note heads. However, in some situations with beams, slurs may be attached to stem @@ -2584,7 +2576,7 @@ so it becomes the lowest note in the chord. @refbugs -Implementation details are quite gory. For example @code{c:4} not only +Implementation details are gory. For example @code{c:4} not only adds a fourth, but also removes the third. diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely index 98c3119231..af7652de80 100644 --- a/Documentation/user/tutorial.itely +++ b/Documentation/user/tutorial.itely @@ -365,7 +365,7 @@ automatically. Thirdly, LilyPond calculates line breaks for you; it doesn't matter where you make new lines in the source file. The example also indicates that a piece of music written in a high -register needs lots of quotes. This makes the input a bit unreadable, +register needs lots of quotes. This makes the input less readable, and is therefore also a potential source of errors. @separate @@ -1826,7 +1826,7 @@ This piece of Scheme code sets the Scheme variable @code{point-and-click} to the value @var{line-column-location} (which itself is a Scheme procedure). -Editing input files can be quite complicated if you're working with +Editing input files can be complicated if you're working with large files: if you're digitizing existing music, you have to synchronize the .ly file, the sheet music on your lap and the sheet music on the screen. The point-and-click mechanism makes it easy to @@ -2178,18 +2178,21 @@ decrescendo, and @code{\!} to end one. The crescendo is started using @code{\<} and also ended using @code{\!}. Absolute dynamics can be entered using @code{\p}, @code{\mf}, etc. -Fingering indications are entered quite simply using @code{-@var{N}}, -where @var{N} is a digit. +Fingering indications are entered simply using @code{-@var{N}}, where +@var{N} is a digit. Now that we have the basic piece of music entered, we want to fine tune it, so we get something that resembles the original printed -edition by Schott/Universal Edition. The basic process that we follow -is that we override defaults in the printing system. We do this by -setting variables in so-called grobs. Printed symbols are internally -represented by Graphical Objects (Grobs). Each grob is described by a -bunch of settings. These setting determine the fonts, offsets, -sub-routines to be called on the grob, etc. The initial values of -these settings are set in the Scheme file +edition by Schott/Universal Edition: + +@lilypondfile{brahms-tweaked.ly} + +The basic process that we follow is that we override defaults in the +printing system. We do this by setting variables in so-called grobs. +Printed symbols are internally represented by Graphical Objects +(Grobs). Each grob is described by a bunch of settings. These setting +determine the fonts, offsets, sub-routines to be called on the grob, +etc. The initial values of these settings are set in the Scheme file @file{scm/grob-description.scm}. We start with the slur: the slur in the upper part, running from the F @@ -2203,10 +2206,130 @@ note head) @end example More precisely, this command extends the definition of the @code{Slur} -object in the current @code{Voice}. In this, the variable -@code{attacment} is set to the pair of symbols @code{'(stem . stem)}. +object in the current @code{Voice}. The variable @code{attachment} is +set to the pair of symbols @code{'(stem . stem)}. + +Although this is useful information, it is not very helpful: the +lilypond backend supports approximately 240 variables like +@code{attachment}, each with their own meaning and own type +(eg. number, symbol, list, etc). Besides slur, LilyPond has 80 +different types of Grobs, that may be created in 14 different context +types besides Voice. + +The interesting information is how you can figure out which properties +to tune for your own scores. To discover this, you must have a copy of +the internals document. This is a set of HTML pages, which should be +included if you run a binary distribution@footnote{You can also +compile them by executing @code{make -C Documentation/user/ +out/lilypond-internals.html} in the source package.}. This document is +also available on the web: go to the lilypond website, click +``Documentation: other'' on the side bar, click +``lilypond-internals'', under information for users. + +Suppose that you wanted to tune the behavior of the slur. The first +step is to get some general info on slurs in lilypond. Turn to the +index, and look up slur. The text says +@quotation +The grob for this object is @internalsref{Slur}, generally in +@internalsref{Voice} context. +@end quotation + +So the grob for this object is called @code{Slur}, and slurs are +created in the @code{Voice} context. If you are reading this tutorial +in the HTML version, then you can simply click Slur, otherwise, you +must look it up the internal documentation: click ``grob overview'' , +and select ``slur'' (the list is alphabetical.) + +Now you get a list of all the properties that the slur object +supports, along with their default values. + + +We also want to move around the fingering `3'. In the printed edition +it is not above the stem, but a little lower, slightly left of the +stem. From the user manual, we find that the associated grob is called +@code{Fingering}, but how do we know if we should use @code{Voice} or +@code{Staff}. In many cases, @code{Voice} is a safe bet, but you can +also deduce this information from the internals documentation: if you +visit the documentation of @code{Fingering}, you will notice +@example +Fingering grobs are created by: Fingering_engraver +@end example + + + +Clicking @code{Fingering_engraver} will show you the documentation of +the module responsible for interpreting the fingering instructions and +translating them to a @code{Fingering} grob. Such a module is called +an @emph{engraver}. The documentation of the @code{Fingering_engraver} +says, +@example +Fingering_engraver is part of contexts: Voice and TabVoice +@end example +so tuning the settings for Fingering should be done using either +@example + \property Voice.Fingering \set @dots{} +@end example +or +@example + \property TabVoice.Fingering \set @dots{} +@end example + +Since the @code{TabVoice} is only used for tab notation, we see that +the first guess @code{Voice} was indeed correct. + +@cindex setting grob properties +@cindex @code{extra-offset} + +For shifting the fingering, we use the grob property +@code{extra-offset}. The following command manually adds an offset to +the object. We move it a little to the left, and 1.8 staff space +downwards. +@example + \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8) +@end example +The @code{extra-offset} is a low-level feature: it moves around +objects in the printout; the formatting engine is completely oblivious +to these offsets. + +@cindex reverting grob properties +@cindex undoing grob properties + +We only want to offset a single grob, so after the F-sharp, we must +undo the setting. The technical term is to revert the grob property. +@example + \property Voice.Fingering \revert #'extra-offset +@end example + +@cindex property types +@cindex translator properties +@cindex grob properties +@cindex music properties + + +There is three different types of variables in LilyPond, something +which is confusing at first (and for some, it stays like that). +Variables such as @code{extra-offset} and @code{attachment} are called +grob properties. They are something different from the translator +properties, like @code{autoBeaming} and +@code{automaticMelismata}. Finally, music expressions are internally +also stored using properties, so-called music properties. You will +encounter the latter type if you run Scheme functions on music using +@code{\apply}. + +The second fingering instruction should be moved up a little, to avoid +a collision with the slur. This could be achieved with +@code{extra-offset}, but in this case, a simpler mechanism also +works. We insert an empty text between the 5 and note. The empty text +pushes the fingering instruction away: +@example + a^" "^#'(finger "5") +@end example + +Lilypond tries to put fingering instructions closer to the notes as +text instructions. To insert an empty text (@code{^" "}) between the +finger and the note, we have disguised the fingering instruction as a +text: @code{(finger "5")}. -@lilypondfile{brahms-tweaked.ly} @separate @@ -2467,12 +2590,13 @@ Of course, all staves are simultaneous and use the same global settings. \property Score.BarNumber \override #'padding = #3 @end example LilyPond prints bar numbers at the start of each line, but -unfortunately, they end up a bit too close to the staff in this example. -A bar number internally is a Grob called @var{BarNumber}. BarNumber -Grobs can be manipulated through their @var{side-position-interface}. One -of the properties of a @var{side-position-interface} that can be tweaked -is the @var{padding}: the amount of extra space that is put between this -Grob and other Grobs. We set the padding to three staff spaces. +unfortunately, they end up a bit too close to the staff in this +example. A bar number internally is a Grob called @var{BarNumber}. +BarNumber Grobs can be manipulated through their +@var{side-position-interface}. One of the properties of a +@var{side-position-interface} that can be tweaked is the +@var{padding}: the amount of extra space that is put between this Grob +and other Grobs. We set the padding to three staff spaces. You can find information on all these kind of properties in LilyPond's automatically generated documentation in diff --git a/input/tutorial/brahms-original.ly b/input/tutorial/brahms-original.ly index 38a5328245..d03346271d 100644 --- a/input/tutorial/brahms-original.ly +++ b/input/tutorial/brahms-original.ly @@ -6,7 +6,8 @@ fis4-3_\p ( ~ fis16 )a-5 } \\ { - fis16( \> d \! b \translator Staff = down \clef treble g ~ < g8 )e> } \\ + fis16( \> d \! b \translator Staff = down + \clef treble g ~ < g8 )e> } \\ { s16 d' ~ < d4 b4 > } diff --git a/scm/generate-documentation.scm b/scm/generate-documentation.scm index baa021cbff..420e4f31c0 100644 --- a/scm/generate-documentation.scm +++ b/scm/generate-documentation.scm @@ -40,7 +40,7 @@ (document-paper "interpretation contexts") (document-all-engravers "engravers") (document-all-engraver-properties "context properties") - (document-all-grobs "backend") + (document-all-grobs "grob overview") (document-all-interfaces "interfaces") (node "backend properties") @@ -71,7 +71,7 @@ ("interpretation contexts" . "Hierarchy and grouping of Engravers") ("engravers" . "Engravers create Grobs") ("context properties" . "context properties") - ("backend" . "Detailed description of all Grobs") + ("grob overview" . "Detailed description of all Grobs") ("interfaces" . "Grob Interfaces") ("backend properties" . "Grob properties") ("function documentation" . "Grob properties") diff --git a/scm/grob-description.scm b/scm/grob-description.scm index 825e03a21c..04ad946b57 100644 --- a/scm/grob-description.scm +++ b/scm/grob-description.scm @@ -532,16 +532,6 @@ (meta . ((interfaces . (rhythmic-head-interface font-interface note-head-interface staff-symbol-referencer-interface)))) )) - (TabNoteHead - . ( - (font-family . roman) - (style . default) - (molecule-callback . ,tablature-molecule-callback) - (Y-offset-callbacks . (,Staff_symbol_referencer::callback)) - (stem-attachment-function . ,tablature-stem-attachment-function) - (meta . ((interfaces . (rhythmic-head-interface font-interface note-head-interface staff-symbol-referencer-interface)))) - )) - (Glissando . ( (type . line) @@ -958,6 +948,17 @@ (direction . 1) (meta . ((interfaces . (text-spanner-interface side-position-interface font-interface)))) )) + + (TabNoteHead + . ( + (font-family . roman) + (style . default) + (molecule-callback . ,tablature-molecule-callback) + (Y-offset-callbacks . (,Staff_symbol_referencer::callback)) + (stem-attachment-function . ,tablature-stem-attachment-function) + (meta . ((interfaces . (rhythmic-head-interface font-interface note-head-interface staff-symbol-referencer-interface)))) + )) + (Tie . ( @@ -1105,3 +1106,5 @@ (set-object-property! (car x) 'translation-type? list?)) all-grob-descriptions) + +(set! all-grob-descriptions (sort all-grob-descriptions alist