Re: define-grobs.scm properties not alphabetical

[Mark Polesky]

Graham Percival wrote:

> I think this is the coolest thing I've ever seen on a lilypond
> mailist, and that says a lot.  :)

Thanks, Graham!

Regarding the all-grob-properties alist in define-grobs.scm...

I've written a function that will automatically sort the alist
(soon after its definition) so that:

* all meta fields are forced to the end of each property list.
* all grobs, properties, and interfaces are listed in an intuitive
  order in the docs.

This required some new definitions that I put into a small file
called lily-sort.scm, which define-public's 6 binary predicates:

  ly:string<?   ly:string-ci<?
  ly:symbol<?   ly:symbol-ci<?
  ly:alist<?    ly:alist-ci<?

I suppose the additional code is small enough to be incorporated
into lily-library.scm, but for the moment it's a separate file.

Also, my work on sorting the grob-list* inspired me to write a
debugging tool, which I did. The debugging tool also assists in
manual code cleanup (for future developers as well) by displaying
an analysis of the alist in the console. I created a separate file
for this as well, called debug-groblist.scm. When turned on, it
generates a (potentially long) string at compile time and sends it
to the console.

*http://codereview.appspot.com/83042/show

To implement this, I added the following lines immediately after
the definition of the alist, and just before the function which
sorts the alist for the docs.

;; cleanup/debugging for this file (define-grobs.scm)
;; change to #t and compile an empty .ly file
(if #f (begin (load "debug-groblist.scm")
              (display groblist-debug-string)))

Really the main purpose of the cleanup tool is to provide an easy
way to periodically check up on the orderliness of the code. It 
does not affect the end user in any way (in the sense that the
sorting function which follows does). When all-grob-descriptions
is perfectly ordered, the debugger prints this:


**********************************************************
Analysis of all-grob-descriptions alist (define-grobs.scm)
**********************************************************
+ All grob descriptions are pairs.
+ All meta fields are in proper tail position.
+ No grobs have duplicate properties.
+ All grob descriptions are in order.
+ All grob interfaces are in order.




Running the debugger on define-grobs.scm as it currently
exists generates this:

**********************************************************
Analysis of all-grob-descriptions alist (define-grobs.scm)
**********************************************************
+ All grob descriptions are pairs.
+ All meta fields are in proper tail position.
- The following grobs have duplicate properties:
      TextScript: (direction).
- The following pairs of grobs are out of order
  (for each pair, move the first one down or the second one up):
      AccidentalSuggestion   AccidentalPlacement
      AmbitusLine   AmbitusAccidental
      BreakAlignment   BreakAlignGroup
      ... (+ 10 more lines)

- The interfaces of the following grobs are not in order.
      AccidentalSuggestion
      Ambitus
      AmbitusLine
      ... (+ 88 more lines)


It is of course not necessary, for example, for all grob
properties to be in order in the code; Neil raised a good point
that certain related properties (like 'kern and 'thin-kern) might
be better left together. However, a few exceptions to the sorting
can be noted where they occur, and the sorting function that
follows the debugger will ensure that they're listed intuitively
in the docs.

One thing I don't understand: why do I need to use (load ...) to
retrieve functions that are defined with define-public in the same
directory?

Anyway, if anyone is curious to test this out, save the attached
files lily-sort.scm and debug-groblist.scm to the /scm folder and
add the lines (included below this message) to define-grobs.scm
-- just after the definition of all-grob-descriptions and just
before the line

(define (completize-grob-entry x) ...

I'd really like this (or something along these lines) to get
incorporated into the source code. If not the debugger, at least
the lily-sort stuff. If nothing else, it makes doc-searching for
things a lot easier. Also, if this is generally well-received by
the developers-that-be, I'd like to extend the idea to other lists
of things, like IR 4: Scheme functions. I can't tell you how many
times I couldn't find ly:grob? because it wasn't between
ly:get-option and ly:grob-alist-chain...

I'll format a patch if anyone thinks a few changes would make it
feasible for inclusion.

(The debugger is turned on for you already)

Hope you enjoy it.
- Mark
______________________________________________________


;; cleanup/debugging for this file (define-grobs.scm)
;; change to #t and compile an empty .ly file
(if #t (begin (load "debug-groblist.scm")
              (display groblist-debug-string)))

; this is temporary:
(load "lily-sort.scm")

(define (sort-grob-properties x)
  ;; force 'meta to the end of each prop-list
  (let ((meta (assoc 'meta x)))
    (append (sort (assoc-remove! x 'meta) ly:alist-ci<?)
            (list meta))))

; properly sort all grobs, properties, and interfaces
(map
  (lambda (x)
    (let* ((props      (assoc-ref all-grob-descriptions (car x)))
           (meta       (assoc-ref props 'meta))
           (interfaces (assoc-ref meta 'interfaces)))
      (set! all-grob-descriptions
        (sort (assoc-set! all-grob-descriptions (car x)
               (sort-grob-properties
                (assoc-set! props 'meta
                 (assoc-set! meta 'interfaces
                  (sort interfaces ly:symbol-ci<?)))))
              ly:alist-ci<?))))
  all-grob-descriptions)

;; this is temporary....set to #t to see the effect of above sort.
(if #f (begin (load "debug-groblist.scm")
              (display groblist-debug-string)))

lily-sort.scm
Description: Text Data

debug-groblist.scm
Description: Text Data