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--2009 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) ly:string-ci<?))
  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         (map ref-ify (sort (map symbol->string (cdr entry))
  57                            ly:string-ci<?)))
  58        "."
  59
  60        "\n\n"
  61        (if (equal? accept-list "none")
  62            "Not accepted by any engraver or performer"
  63            (string-append
  64             "Accepted by: "
  65             accept-list))
  66        "."))))
  67
  68 (define (music-types-doc)
  69   (make <texi-node>
  70     #:name "Music classes"
  71     #:children
  72     (map music-type-doc
  73          (sort
  74           (hash-table->alist music-types->names) ly:alist-ci<?))))
  75
  76 (define (music-doc-str obj)
  77   (let* ((namesym  (car obj))
  78          (props (cdr obj))
  79          (class (ly:camel-case->lisp-identifier namesym))
  80          (classes (ly:make-event-class class))
  81          (accept-list (if classes
  82                           (human-listify
  83                            (map ref-ify
  84                                 (map symbol->string
  85                                      (map ly:translator-name
  86                                           (filter
  87                                            (lambda (x)
  88                                              (engraver-accepts-music-types? classes x))
  89                                            all-engravers-list)))))
  90                           ""))
  91          (event-texi (if classes
  92                          (string-append
  93                           "\n\nEvent classes:\n"
  94                           (human-listify
  95                            (map ref-ify (sort (map symbol->string classes)
  96                                               ly:string-ci<?)))
  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        (sort (map car props) ly:symbol-ci<?))
 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))))