scm/document-music.scm

   1 ;;;; document-markup.scm -- part of generated backend documentation
   2 ;;;;
   3 ;;;;  source file of the GNU LilyPond music typesetter
   4 ;;;;
   5 ;;;; (c) 1998--2008 Han-Wen Nienhuys <hanwen@xs4all.nl>
   6 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
   7
   8 (define (music-props-doc)
   9   (make <texi-node>
  10     #:name "Music properties"
  11     #:desc "All music properties, including descriptions."
  12     #:text
  13     (let* ((ps (sort (map symbol->string all-music-properties) string<?))
  14            (descs (map (lambda (prop)
  15                          (property->texi 'music (string->symbol prop)))
  16                        ps))
  17            (texi (description-list->texi descs #f)))
  18       texi)))
  19
  20 (define music-types->names (make-vector 61 '()))
  21 (filter-map (lambda (entry)
  22               (let* ((class (ly:camel-case->lisp-identifier (car entry)))
  23                      (classes (ly:make-event-class class)))
  24                 (if classes
  25                     (map
  26                      (lambda (cl)
  27                        (hashq-set! music-types->names cl
  28                                    (cons (car entry)
  29                                          (hashq-ref music-types->names cl '()))))
  30                      classes)
  31                     #f)))
  32
  33             music-descriptions)
  34
  35 (define (strip-description x)
  36   (cons (symbol->string (car x))
  37         ""))
  38
  39 (define (music-type-doc entry)
  40   (let* ((accept-list (human-listify
  41                        (map ref-ify
  42                             (map symbol->string
  43                                  (map ly:translator-name
  44                                       (filter
  45                                        (lambda (x)
  46                                          (engraver-accepts-music-type? (car entry) x))
  47                                        all-engravers-list)))))))
  48     (make <texi-node>
  49       #:name (symbol->string (car entry))
  50       #:text
  51       (string-append
  52        "\nMusic event type @code{"
  53        (symbol->string (car entry))
  54        "} is in music objects of type "
  55        (human-listify
  56         (sort
  57          (map (lambda (x) (ref-ify (symbol->string x)))
  58               (cdr entry)) string<?))
  59        "."
  60
  61        "\n\n"
  62        (if (equal? accept-list "none")
  63            "Not accepted by any engraver or performer"
  64            (string-append
  65             "Accepted by: "
  66             accept-list))
  67        "."))))
  68
  69 (define (music-types-doc)
  70   (make <texi-node>
  71     #:name "Music classes"
  72     #:children
  73     (map music-type-doc
  74          (sort
  75           (hash-table->alist music-types->names) alist<?))))
  76
  77 (define (music-doc-str obj)
  78   (let* ((namesym  (car obj))
  79          (props (cdr obj))
  80          (class (ly:camel-case->lisp-identifier namesym))
  81          (classes (ly:make-event-class class))
  82          (accept-list (if classes
  83                           (human-listify
  84                            (map ref-ify
  85                                 (map symbol->string
  86                                      (map ly:translator-name
  87                                           (filter
  88                                            (lambda (x)
  89                                              (engraver-accepts-music-types? classes x))
  90                                            all-engravers-list)))))
  91                           ""))
  92          (event-texi (if classes
  93                          (string-append
  94                           "\n\nEvent classes:\n"
  95                           (human-listify
  96                            (map ref-ify (map symbol->string classes)))
  97                           "."
  98
  99                           "\n\n"
 100                           (if (equal? accept-list "none")
 101                               "Not accepted by any engraver or performer"
 102                               (string-append
 103                                "Accepted by: "
 104                                accept-list))
 105                           ".")
 106                          "")))
 107
 108     (string-append
 109      (object-property namesym 'music-description)
 110      event-texi
 111      "\n\nProperties:\n"
 112      (description-list->texi
 113       (map
 114        (lambda (x) (property->texi 'music x props))
 115        (map car props))
 116       #t))))
 117
 118 (define (music-object-doc obj)
 119   (make <texi-node>
 120     #:name (symbol->string (car obj))
 121     #:text (music-doc-str obj)))
 122
 123 (define (music-expressions-doc)
 124   (make <texi-node>
 125     #:name "Music expressions"
 126     #:desc "Objects that represent music."
 127     #:children
 128     (map music-object-doc music-descriptions)))
 129
 130 (define (music-doc-node)
 131   (make <texi-node>
 132     #:name "Music definitions"
 133     #:desc "Definition of the input data structures."
 134     #:children
 135     (list
 136      (music-expressions-doc)
 137      (music-types-doc)
 138      (music-props-doc))))