learning (names of) markup commands in scheme: documentation

[Bernhard Fisseni]

Good morning,

trying to understand the programming a bit better, I managed to 
transform the mixed command definitions to scheme code (see below).

I've learnt the following in the process; should some of it be made more 
explicit in the manual?  (If so, I could try to think of suggestions.)

- In my opinion writing the scheme code is much easier than mixing 
Lilypond and Scheme.

- For every markup command and every markup list command \CMD, there is 
a corresponding scheme function make-CMD-markup.


<http://lilypond.org/doc/v2.22/Documentation/extending/markup-construction-in-scheme> 
uses this implicitly in the last paragraphs, but an explicit remark 
might be helpful.


<http://lilypond.org/doc/v2.22/Documentation/extending/how-markups-work-internally> 
explains the correspondence with one example, but does not mention 
markup list commands; furthermore, the heading and the wording mislead 
me so that I only understood the generality of this paragraph 
afterwards. Maybe "How Markups Work Internally: Lilypond Commands and 
Corresponding Scheme Commands" might be more explicit?

  Consequence: There is no collision between an auxiliary function CMD 
and a homonymous markup command \CMD, as they are (CMD ...) and 
(make-CMD-markup ...), respectively, in scheme.

  Question: Do similar correspondences exist for music functions and 
event functions? It looks as if they might me make-CMD-music and 
make-CMD-event, but I find no dokumentation for this. (May be my fault.)

- A (list ...) of markups is indeed a markup list, and markup lists can 
be treated like just a list (map, length, car, cdr etc.).  (Actually, I 
had expected that there were specialised conversions and accessor 
functions.)

  Given that lists are so fundamental, this might be stated somewhere.

- There is a point in processing when one has to convert every "line" 
(in my example) to markup, although the interpretation happens 
automatically in other places (see interpret-markup-list in 
apply-last-strut).


Sorry if this looks like nitpicking, I am just trying to find my way around.

Best regards,
  Bernhard


For reference, this:

> #(define-markup-command
>     (strut-line layout props line)
>     (markup?)
>     (interpret-markup layout props #{
>       \markup{
>         \combine #line \transparent "Ij"
>       }
>     #}))
>
> #(define-markup-command
>      (stanza-list layout props stanzas)
>      (markup-list?)
>        (interpret-markup layout props #{
>        \markup
>        \column {
>          #stanzas
>        }
>       #}))
>
> #(define-markup-list-command
>     (apply-very-last-strut layout props stanza-lines)
>     (markup-list?)
>     (letrec ((apply-last-strut
>               (lambda (stanza-lines)
>                (if (null? stanza-lines)
>                 stanza-lines
>                 (if (> (length stanza-lines) 1)
>                  (cons (interpret-markup layout props #{
>                         \markup {#(car stanza-lines)}
>                   #})
>                  (apply-last-strut (cdr stanza-lines)))
>      (interpret-markup-list layout props #{
>        \markuplist {
>          \strut-line #stanza-lines
>        }
>       #}))))))
>       (apply-last-strut stanza-lines)))
>
> #(define-markup-command
>     (my-stanza layout props number lines)
>     (markup? markup-list?)
>     #:properties ((extra-space 1))
>     (interpret-markup layout props #{
>      \markup {
>        \combine \null \vspace #extra-space \line {
>          \bold #number
>          \column {
>            \apply-very-last-strut #lines
>          }
>        }
>      }
>     #}))

became this:

#(define-markup-command (strut-line layout props line)
  (markup?)
  "add strut to the end of a line to ensure correct line spacing"
  (interpret-markup layout props
   (markup
    (make-combine-markup
     (make-line-markup (list line))
     (make-transparent-markup "Ij")))))

#(define-markup-command (stanza-list layout props stanzas)
  (markup-list?)
  "make a column of stanzas (just for explicitness' sake)"
  (interpret-markup layout props
   (markup
    (make-column-markup stanzas))))

#(define-markup-list-command
  (apply-last-strut layout props stanza-lines)
  (markup-list?)
  "append a strut to the last of the stanza-lines to ensure proper spacing"
  (letrec ((apply-last-strut
            (lambda (stanza-lines)
             (cond
              ((null? stanza-lines) stanza-lines)
              ((> (length stanza-lines) 1)
               (cons (interpret-markup layout props
                      (car stanza-lines))
                (apply-last-strut (cdr stanza-lines))))
              (else
                (interpret-markup-list
                  layout props
                  (map make-strut-line-markup stanza-lines)))))))
    (apply-last-strut stanza-lines)))

#(define-markup-command
   (numbered-stanza layout props number lines)
   (markup? markup-list?)
   #:properties ((extra-space 1))
   "make a numbered stanza with the number to the left of the lyrics"
   (interpret-markup
     layout props
     (markup
       (make-line-markup
         (list (make-bold-markup number)
               (markup
                 (make-column-markup
                   (make-apply-last-strut-markup-list lines))
                 (make-combine-markup
                   (make-null-markup)
                   (make-vspace-markup extra-space))))))))