5.2 Explaining the Internals Reference

5.2.1 Navigating the program reference

Suppose we want to move the fingering indication in the fragment below:

c''-2

If you visit the documentation on fingering instructions (in Fingering instructions), you will notice:

See also

Internals Reference: (internals)Fingering section ‘Fingering’ in Internals Reference.

Follow the link to (internals)Fingering section ‘Fingering’ in Internals Reference. At the top of the page, you will see

Fingering objects are created by: (internals)Fingering_engraver section ‘Fingering_engraver’ in Internals Reference and (internals)New_fingering_engraver section ‘New_fingering_engraver’ in Internals Reference.

By following related links inside the program reference, we can follow the flow of information within the program:

• (internals)Fingering section ‘Fingering’ in Internals Reference: (internals)Fingering section ‘Fingering’ in Internals Reference objects are created by: (internals)Fingering_engraver section ‘Fingering_engraver’ in Internals Reference
• (internals)Fingering_engraver section ‘Fingering_engraver’ in Internals Reference: Music types accepted: (internals)fingering-event section ‘fingering-event’ in Internals Reference
• (internals)fingering-event section ‘fingering-event’ in Internals Reference: Music event type fingering-event is in Music expressions named (internals)FingeringEvent section ‘FingeringEvent’ in Internals Reference

This path goes against the flow of information in the program: it starts from the output, and ends at the input event. You could also start at an input event, and read with the flow of information, eventually ending up at the output object(s).

The program reference can also be browsed like a normal document. It contains chapters on (internals)Music definitions section ‘Music definitions’ in Internals Reference, on (internals)Translation section ‘Translation’ in Internals Reference, and the (internals)Backend section ‘Backend’ in Internals Reference. Every chapter lists all the definitions used and all properties that may be tuned.

5.2.2 Layout interfaces

The HTML page that we found in the previous section describes the layout object called (internals)Fingering section ‘Fingering’ in Internals Reference. Such an object is a symbol within the score. It has properties that store numbers (like thicknesses and directions), but also pointers to related objects. A layout object is also called a Grob, which is short for Graphical Object. For more details about Grobs, see (internals)grob-interface section ‘grob-interface’ in Internals Reference.

The page for Fingering lists the definitions for the Fingering object. For example, the page says

padding (dimension, in staff space):

0.5

which means that the number will be kept at a distance of at least 0.5 of the note head.

Each layout object may have several functions as a notational or typographical element. For example, the Fingering object has the following aspects

• Its size is independent of the horizontal spacing, unlike slurs or beams.
• It is a piece of text. Granted, it is usually a very short text.
• That piece of text is typeset with a font, unlike slurs or beams.
• Horizontally, the center of the symbol should be aligned to the center of the note head.
• Vertically, the symbol is placed next to the note and the staff.
• The vertical position is also coordinated with other superscript and subscript symbols.

Each of these aspects is captured in so-called interfaces, which are listed on the (internals)Fingering section ‘Fingering’ in Internals Reference page at the bottom

This object supports the following interfaces: (internals)item-interface section ‘item-interface’ in Internals Reference, (internals)self-alignment-interface section ‘self-alignment-interface’ in Internals Reference, (internals)side-position-interface section ‘side-position-interface’ in Internals Reference, (internals)text-interface section ‘text-interface’ in Internals Reference, (internals)text-script-interface section ‘text-script-interface’ in Internals Reference, (internals)font-interface section ‘font-interface’ in Internals Reference, (internals)finger-interface section ‘finger-interface’ in Internals Reference, and (internals)grob-interface section ‘grob-interface’ in Internals Reference.

Clicking any of the links will take you to the page of the respective object interface. Each interface has a number of properties. Some of them are not user-serviceable (‘Internal properties’), but others can be modified.

We have been talking of the Fingering object, but actually it does not amount to much. The initialization file (see (learning)Other sources of information section ‘Other sources of information’ in Learning Manual) ‘scm/define-grobs.scm’ shows the soul of the ‘object’,

(Fingering
  . ((padding . 0.5)
     (avoid-slur . around)
     (slur-padding . 0.2)
     (staff-padding . 0.5)
     (self-alignment-X . 0)
     (self-alignment-Y . 0)
     (script-priority . 100)
     (stencil . ,ly:text-interface::print)
     (direction . ,ly:script-interface::calc-direction)
     (font-encoding . fetaText)
     (font-size . -5) 		; don't overlap when next to heads.
     (meta . ((class . Item)
     (interfaces . (finger-interface
                    font-interface
                    text-script-interface
                    text-interface
                    side-position-interface
                    self-alignment-interface
                    item-interface))))))

As you can see, the Fingering object is nothing more than a bunch of variable settings, and the webpage in the Internals Reference is directly generated from this definition.

5.2.3 Determining the grob property

Recall that we wanted to change the position of the 2 in

c''-2

Since the 2 is vertically positioned next to its note, we have to meddle with the interface associated with this positioning. This is done using side-position-interface. The page for this interface says

side-position-interface

Position a victim object (this one) next to other objects (the support). The property direction signifies where to put the victim object relative to the support (left or right, up or down?)

Below this description, the variable padding is described as

padding

(dimension, in staff space)

Add this much extra space between objects that are next to each other.

By increasing the value of padding, we can move the fingering away from the note head. The following command will insert “three staff spaces” worth of distance between the note and a fingering mark:

\once \override Voice.Fingering.padding = #3

Inserting the padding before the fingering object is created results in the following:

\once \override Voice.Fingering.padding = #3 c''-2

In this case, the context for this tweak is Voice. See (internals)Fingering_engraver section ‘Fingering_engraver’ in Internals Reference plug-in, which says:

Fingering_engraver is part of contexts: … (internals)Voice section ‘Voice’ in Internals Reference

5.2.4 Naming conventions

Another thing that is needed, is an overview of the various naming conventions:

• scheme functions: lowercase-with-hyphens (also includes one-word names)
• LilyPond-specific scheme functions: ly:plus-scheme-style
• music events, music classes and music properties: as-scheme-functions
• Grob interfaces: scheme-style
• backend properties: scheme-style (but X and Y!)
• contexts (and MusicExpressions and grobs): Capitalized or CamelCase
• context properties: lowercaseFollowedByCamelCase
• engravers: Capitalized_followed_by_lowercase_and_with_underscores

Questions to be answered:

• Which of these are conventions and which are rules?
• Which are rules of the underlying language, and which are LilyPond-specific?

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Más nyelvek: català, deutsch, español, français, italiano, 日本語.
Az automatikus nyelvválasztásról.