Re: moving tweaks into markup-definition

[Orm Finnendahl]

Am Mittwoch, den 17. September 2014 um 07:53:48 Uhr (+0100) schrieb James:
> Do you have any other suggestions we could improve the documentation
> with perhaps?

The main problem in this special case for me is the fact, that David's
code suggests that the first three elements of the prop argument of a
define-markup-command are alists which contain mutable properties,
immutable properties and font-defaults (in that order). I couldn't
(and still can't) find a place where that is documented.

In addition, I don't know:

1. Which properties of layout objects are mutable/immutable?  

2. Although David's set! instruction to reassign the props symbol
   makes that improbable: Could there be other elems at the end of the
   prop list (and which, if there are)?

I already had read through everything David pointed me to before
except for the c++ code which seemingliy gave David the insight to
enable him helping me out. So maybe it would be a good idea to explain
those arguments (layout props, etc.) somewhere in more detail with
examples...

Reading the interface for programmers documentation, other things
remain unclear to me. One example is the following code from the
define-markup-command documentation:

#(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)))

I don't exactly understand the syntactical function of the :properties
keyword in the second line: Is it syntactical sugar for a let
construct?

So I tried this:

#(define-markup-command (double-box layout props text) (markup?)
  (let ((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))))

and that works as well. But I still don't know whether there are any
drawbacks doing it with let (is there some machinery behind the scenes
of the :properties construct doing more than assigning the values to
the symbols?). For me personally (as I'm acquainted with lisp and its
dialects) it would be very helpful if those non-scheme-standard
syntactical constructs would be explained.

I'm by no means complaining: It is a gigantic task to make a
documentation of such a complex project and the current documentation
is awesome already. Specifying something like the API of lilypond
seems extremely tricky. I'm feeling somewhat challenged and think
seriously about writing up something to help others. But first I need
to be more aware of the internals and comfortable that I have really
understood how it works. Unfortunately that seems a long way from
where I am at at the moment...

--
Orm