Un exemple complet (Extender LilyPond)

#### Un exemple complet

L’exemple següent defineix una ordre de marcatge per traçar un rectangle doble al voltant d’un fragment de text.

En primer lloc, ens cal construir un resultat aproximat utilitzant marcatges. Una consulta a Ordres de marcatge de text ens mostra que és útil l’odre `\box`:

>     \markup \box \box HOLA

Ara, considerem que és preferible tenir més separació entre el text i els rectangles. Segons la documentació de `\box`, aquesta ordre usa una propietat `box-padding`, el valor predeterminat de la qual és 0.2. La documentació també menciona com sobreescriure aquest valor:

>     \markup \box \override #'(box-padding . 0.6) \box A

Després, l’emplenament o separació entre els dos rectangles ens sembla molt petit, així que també el sobreescriurem:

>     \markup \override #'(box-padding . 0.4) \box
>          \override #'(box-padding . 0.6) \box A

Repetir aquesta extensa ordre de marcatge un i un altre cop seria un maldecap. Aquí és on cal una ordre de marcatge. Així doncs, escrivim una ordre de marcatge `double-box`, que agafa un argument (el text). Dibuixa els dos rectangles i afegeix una separació.

    #(define-markup-command (double-box layout props text) (markup?)
      "Trazar un rectángulo doble rodeando el texto."
      (interpret-markup layout props
        #{\markup \override #'(box-padding . 0.4) \box
                \override #'(box-padding . 0.6) \box { #text }#}))

o, de forma equivalent,

    #(define-markup-command (double-box layout props text) (markup?)
      "Trazar un rectángulo doble rodeando el texto."
      (interpret-markup layout props
        (markup #:override '(box-padding . 0.4) #:box
                #:override '(box-padding . 0.6) #:box text)))

`text` és el nom de l’argument de l’ordre, i `markup?` és el tipus: l’identifica com un element de marcatge. La funció `interpret-markup` s’usa en gairebé totes les ordres de marcatge: construeix un segell, usant `layout`, `props`, i un element de marcatge. En el segon cas, la marca es construeix usant el macro de l’Scheme `markup`, vegeu Construcció d’elements de marcatge a l’Scheme. La transformació d’una expressió `\markup` en una expressió de marcatge de l’Scheme és directa.

L’ordre nova es pot usar com segueix:

    \markup \double-box A

Fora bo fer una l’ordre `double-box` que es pogués personalitzar aquí, els valors d’emplenament `box-padding` són fixos i no es poden canviar per part d l’usuari. A més a més, fora millor distingir la separació entre els dos rectangles, de l’emplenament entre el rectangle intern i el text. Així docs, introduïm una nova propietat, `inter-box-padding`, per a l’emplenament entre els rectangles. El `box-padding` s’usarà per a l’emplenament intern. Ara el codi nou és com es veu a continuació:

    #(define-markup-command (double-box layout props text) (markup?)
      #:properties ((inter-box-padding 0.4)
                    (box-padding 0.6))
      "Trazar un rectángulo doble rodeando el texto."
      (interpret-markup layout props
        #{\markup \override #`(box-padding . ,inter-box-padding) \box
                   \override #`(box-padding . ,box-padding) \box
                   { #text } #}))

De nou, la versió equivalent que utilitza la macro de marcatge seria:

    #(define-markup-command (double-box layout props text) (markup?)
      #:properties ((inter-box-padding 0.4)
                    (box-padding 0.6))
      "Traç d'un rectangle doble rodejant el test."
      (interpret-markup layout props
        (markup #:override `(box-padding . ,inter-box-padding) #:box
                #:override `(box-padding . ,box-padding) #:box text)))

Aquí la paraula clau `#:properties` s’usa de manera que les propietats `inter-box-padding` i `box-padding` es llegeixen a partir de l’argument `props`, i se’ls proporcionen uns valors predeterminats si les propietats no estan definides.

Després, aquests valors s’usen per sobreescriure les propietats `box-padding` usades per les dues instruccions `\box`. Observeu l’apòstrof invertit i la coma a l’argument de `\override`: ens permeten introduir un valor de variable dins d’una expressió literal.

Ara, l’ordre es pot usar dins d’un element de marcatge, i l’emplenament dels rectangles es pot personalitzar:

>     #(define-markup-command (double-box layout props text) (markup?)
>       #:properties ((inter-box-padding 0.4)
>                     (box-padding 0.6))
>       "Traç d'un rectangle doble rodejant el text."
>       (interpret-markup layout props
>         #{\markup \override #`(box-padding . ,inter-box-padding) \box
>                   \override #`(box-padding . ,box-padding) \box
>                   { #text } #}))

>     \markup \double-box A
>     \markup \override #'(inter-box-padding . 0.8) \double-box A
>     \markup \override #'(box-padding . 1.0) \double-box A

#### Extender LilyPond v2.26.0 (stable-branch).

- Appendix A Tutorial de l’Scheme
  - A.1 Introducció a l’Scheme
    - A.1.1 Banc de sorra de l’Scheme
    - A.1.2 Variables de l’Scheme
    - A.1.3 Tipus de dades simples de l’Scheme
    - A.1.4 Tipus de dades compostes de l’Scheme
      - Parelles
      - Llistes
      - Llistes associatives (llistes-A)
      - Taules de hash
    - A.1.5 Càlculs a l’Scheme
    - A.1.6 Procediments de l’Scheme
      - Definició de procediments
      - Predicats
      - Valors de retorn
    - A.1.7 Condicionals de l’Scheme
      - if
      - cond
  - A.2 Scheme dins del LilyPond
    - A.2.1 Sintaxi de l’Scheme del LilyPond
    - A.2.2 Variables del LilyPond
    - A.2.3 Variables d’entrada i l’Scheme
    - A.2.4 Importació de l’Scheme dins del LilyPond
    - A.2.5 Propietats dels objectes
    - A.2.6 Variables del LilyPond compostes
      - Desplaçaments
      - Fraccions
      - Dimensions
      - Llistes-A de propietats
      - Cadenes de llistes-A
    - A.2.7 Representació interna de la música
  - A.3 Construcció de funcions complicades
    - A.3.1 Presentació de les expressions musicals
    - A.3.2 Propietats musicals
    - A.3.3 Duplicació una nota amb lligadures (exemple)
    - A.3.4 Afegir articulacions a les notes (exemple)
- B Interfícies per a programadors
  - B.1 Blocs de codi del LilyPond
  - B.2 Funcions de l’Scheme
    - B.2.1 Definició de funcions de l’Scheme
    - B.2.2 Ús de les funcions de l’Scheme
    - B.2.3 Funcions de l’Scheme buides
  - B.3 Funcions musicals
    - B.3.1 Definicions de funcions musicals
    - B.3.2 Ús de les funcions musicals
    - B.3.3 Funcions de substitució senzilles
    - B.3.4 Funcions de substitució intermèdies
    - B.3.5 Matemàtiques dins de les funcions
    - B.3.6 Funcions sense arguments
    - B.3.7 Funcions musicals buides
  - B.4 Funcions d’esdeveniments
  - B.5 Funcions de marcatge
    - B.5.1 Construcció d’elements de marcatge a l’Scheme
    - B.5.2 Com funcionen internament els elements de marcatge
    - B.5.3 Definició d’una ordre nova de marcatge
      - Sintaxi de la definició d’ordre de marcatge
      - Quant a les propietats
      - Un exemple complet
      - Adaptació d’ordres incorporades
    - B.5.4 Definició de noves ordres de llista de marcatge
  - B.6 Contextos per a programadors
    - B.6.1 Avaluació de contextos
    - B.6.2 Execució d’una funció sobre tots els objectes de la presentació
  - B.7 Funcions de callback
  - B.8 Ajustaments difícils
- C Interfícies de l’Scheme del LilyPond
- Appendix D GNU Free Documentation License
- Appendix E Índex del LilyPond