Re: learning (names of) markup commands in scheme: documentation

[Jean Abou Samra]

[Berhard]
> Actually, the lilypond.org web server was very insistent that even 
> when I googled English, I should read German whenever it was 
> available; therefore I assumed the versions were on par.  I will think 
> about configuring one browser / profile without language preferences 
> so that I can access the English version directly.
>
> (For documentation with a specialised audience, I always wonder if 
> such divergence between versions would be better avoided with 
> linguistic monoculture, but I really appreciate the effort! [And I 
> hope this does not sound deprecating – it's not meant to be!, it's 
> just a difficult issue.]).



Divergence depends on the state of maintenance of the
respective translation. The Italian and French ones are
completely up-to-date. I started using LilyPond aged
13 or so and barely able to make sense of the English
words like \header in the LilyPond input, let alone to
read the documentation in English. I don't think our
audience, however specialized, is so much more able
to speak English than with other software. The translations
do bring enormous value.

What would be ideal would be translating the documentation
via Gettext-based tools so the maintenance would be
automatic and English text would be displayed in case
the translation is outdated on a certain paragraph.
I dream of that, but the thing is, tools to do that only
emerged after the main body of translation was done,
and there would be an enormous lot of material to
convert by now ...



Le 22/01/2022 à 10:47, Bernhard Fisseni a écrit :
> Good morning, Jean,
>
> thank you very much for your detailed explanation!  This helps me to 
> understands things a bit better.
>
> Jean Abou Samra schrieb am 21.01.22 um 19:30:
> > Le 21/01/2022 à 08:57, Bernhard Fisseni a écrit :
>
>
> > > - 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).
> >
> >
> > I'm not sure what you mean here. Can you clarify?
>
> What I meant was that while in the Lilypond source, one can have a top 
> \markup, which makes more or less all its argument a markup, when 
> writing the markup commands, one occasionally has to apply 
> (interpret-markup) or (interpret-markup-list) to inner arguments to 
> return the right type, e.g. in the recursive function I wrote.  If I 
> understand correctly, one is doing piecewise  evaluation "by hand".  
> It feels rather natural if one understands the general system, I 
> suppose, as there are these different explicit and implicit 
> conversions of syntax into markup.  (If that is too cryptic, I am 
> sorry; it is probably not such an important point.)


Well, the "right type" here is not a markup, but a
stencil, namely a device-independent representation of
graphical output. A markup is not a stencil, but merely
the promise of a stencil that will be parameterized by
properties. So when you do interpret-markup, this is not
converting some kind of syntax into a markup, but a markup
into a stencil. When you write \markup in your source file,
you enter markup mode. You can then compose your markup
using commands. The application of a command as
\command [first-arg] [second-arg] [etc.] yields a markup.
Many markup commands take one or several markup arguments,
so when you write \markup \bold \italic a, this ends
up as a markup made from the command \bold, with an argument
that is \markup \italic a (no need to repeat \markup within
the nested construction as you are already in markup mode).
At this point, the compound \markup gets interpreted. That's
the entry point. Then, it is up to the markup command
of that top-level markup to interpret the markup sub-arguments.
Usually it will interpret them (it doesn't have to), but
it is intentional to leave it to the command to do it and
not to do it automatically. Because the command may want to
interpret its markup subarguments with different parameters.
A typical example: \bold is defined as

(define-markup-command (bold layout props arg)
  (markup?)
  (interpret-markup layout (prepend-alist-chain 'font-series 'bold 
props) arg))

which interprets the markup argument with a modified
"props" alist chain (list of alists) that adds settings
so that any string inside "arg" gets interpreted in
a bold font.

Is it clearer to you now?



[David]
> > Yes, and not only make-CMD-markup, but more importantly
> > CMD-markup
>
>
> CMD-markup-function 


Hm?

#(write #{ \markup \bold a #})
=> (#<procedure bold-markup (layout props arg)> "a")



[Me]
> Homework for me: figure out why this does not result
> in constant spacing regardless of the heights of
> the markups (that part of the code is rather complicated).


Cough. It does. The default baseline-skip just turns
out to be about what you want. If you add more lines,
it starts colliding. How could that have worked? Silly me.

That suggestion is moot: at best it helps you reduce
the minimum distance (baseline-skip) without padding
interfering. You still need manual adjustments.

I have no better suggestion than

\version "2.22.1"

%% This is frequently defined and maybe we should add it to
%% LilyPond proper ...
#(define-markup-command (with-dimensions-from-on-axis layout props axis 
dims-markup arg) (index? markup? markup?)
   (let* ((from (interpret-markup layout props dims-markup))
          (dims (ly:stencil-extent from axis))
          (stil (interpret-markup layout props arg))
          (expr (ly:stencil-expr stil)))
     (if (eqv? axis X)
         (ly:make-stencil expr
                          dims
                          (ly:stencil-extent stil Y))
         (ly:make-stencil expr
                          (ly:stencil-extent stil X)
                          dims))))

%% The main definition
#(define-markup-command (text-column layout props args) (markup-list?)
   (interpret-markup layout props
     #{ \markup \column \with-dimensions-from-on-axis #Y "Ij" #args #}))

\markup {
  \fill-line {
    \hspace #0.1 % moves the column off the left margin;
     % can be removed if space on the page is tight
     \column {
      \line { \bold "2."
        \text-column {
          "q This is verse two."
          "q It has two lines."
        }
      }
      \combine \null \vspace #0.1 % adds vertical spacing between verses
      \line { \bold "3."
        \text-column {
          "q This is verse three."
          "q It has two lines."
        }
      }
    }
    \hspace #0.1 % adds horizontal spacing between columns;
    \column {
      \line { \bold "4."
        \text-column {
          "This is verse four."
          "It has two lines."
        }
      }
      \combine \null \vspace #0.1 % adds vertical spacing between verses
      \line { \bold "5."
        \text-column {
          "This is verse five."
          "It has two lines."
        }
      }
    }
  \hspace #0.1 % gives some extra space on the right margin;
  % can be removed if page space is tight
  }
}


That does get rid of finding baseline-skip values
by hand or by manual computation and is a bit simpler
than your previous solutions. Just beware if
you use \font-size: you have to write it as

\fontsize #x \text-column { ... }

and not

\text-column \fontsize #x { ... }

But sorry if I've missed something again; due to
lack of time, I'm writing all of this a bit fast.

Best,
Jean