Exemple commenté

Nous allons, dans cet exemple, nous attacher à encadrer du texte avec un double liseré.

Commençons par construire quelque chose d’approximatif à l’aide d’un simple markup. La lecture de Commandes pour markup nous indique la commande \box, qui semble ici appropriée.

\markup \box \box HELLO

Dans un souci d’esthétique, nous aimerions que le texte et les encadrements ne soient pas autant accolés. Selon la documentation de \box, cette commande utilise la propriété box-padding, fixée par défaut à 0,2. Cette même documentation nous indique aussi comment la modifier :

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

L’espacement des deux liserés est cependant toujours trop réduit ; modifions le à son tour :

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

Vous conviendrez que recopier une telle définition de markup deviendra vite fastidieux. C’est pourquoi nous écrivons la commande de markup double-box qui prendra un seul argument – le texte. Cette commande se chargera de dessiner les encadrements, en tenant compte des espacements.

#(define-markup-command (double-box layout props text) (markup?)
  "Dessine un double encadrement autour du texte."
  (interpret-markup layout props
    #{\markup \override #'(box-padding . 0.4) \box
            \override #'(box-padding . 0.6) \box { #text }#}))

ou bien son équivalent

#(define-markup-command (double-box layout props text) (markup?)
  "Dessine un double encadrement autour du texte."
  (interpret-markup layout props
    (markup #:override '(box-padding . 0.4) #:box
            #:override '(box-padding . 0.6) #:box text)))

text est le nom de l’argument de notre commande, et markup? son type – l’argument sera identifié comme étant un markup. La fonction interpret-markup, utilisée dans la plupart des commandes de markup, construira un stencil à partir de layout, props et un markup. Dans la seconde variante, ce markup sera construit à l’aide de la macro Scheme markup – voir Construction d’un markup en Scheme. La transformation d’une expression \markup en expression Scheme est des plus triviales.

Notre commande personnalisée s’utilise ainsi :

\markup \double-box A

Il serait intéressant de rendre cette commande double-box plus souple : les valeurs de box-padding sont figées et ne peuvent être modifiées à l’envie. Pareillement, il serait bien de distinguer l’espacement entre les encadrements de l’espacement entre le texte et ses encadrements. Nous allons donc introduire une propriété supplémentaire, que nous appellerons inter-box-padding, chargée de gérer l’espacement des encadrements ; box-padding ne servira alors que pour l’espacement intérieur. Voici le code adapté à ces évolutions :

#(define-markup-command (double-box layout props text) (markup?)
  #:properties ((inter-box-padding 0.4)
                (box-padding 0.6))
  "Dessine un double encadrement autour du texte."
  (interpret-markup layout props
    #{\markup \override #`(box-padding . ,inter-box-padding) \box
               \override #`(box-padding . ,box-padding) \box
               { #text } #}))

Ainsi que son équivalent à partir de la macro markup :

#(define-markup-command (double-box layout props text) (markup?)
  #:properties ((inter-box-padding 0.4)
                (box-padding 0.6))
  "Dessine un double encadrement autour du texte."
  (interpret-markup layout props
    (markup #:override `(box-padding . ,inter-box-padding) #:box
            #:override `(box-padding . ,box-padding) #:box text)))

C’est ici le mot-clé #:properties qui permet de lire les propriétés inter-box-padding et box-padding à partir de l’argumenet props ; on leur a d’ailleurs fourni des valeurs par défaut au cas où elles ne seraient pas définies.

Ces valeurs permettront alors d’adapter les propriétés de box-padding utilisées par les deux commandes \box. Vous aurez remarqué, dans l’argument \override, la présence de l’apostrophe inversée (`) et de la virgule ; elles vous permettent d’insérer une valeur variable au sein d’une expression littérale.

Notre commande est maintenant prête à servir dans un markup, et les encadrements sont repositionnables.

#(define-markup-command (double-box layout props text) (markup?)
  #:properties ((inter-box-padding 0.4)
                (box-padding 0.6))
  "Draw a double box around 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