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--2007 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)))
  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 (lambda (cl)
  26                            (hashq-set! music-types->names cl
  27                                        (cons (car entry)
  28                                              (hashq-ref music-types->names cl '()))))
  29                          classes)
  30                     #f)))
  31
  32             music-descriptions)
  33
  34 (define (strip-description x)
  35   (cons (symbol->string (car x))
  36         ""))
  37
  38 (define (music-type-doc entry)
  39   (make <texi-node>
  40     #:name  (symbol->string (car entry))
  41     #:text
  42     (string-append
  43      "\nMusic event type @code{"
  44      (symbol->string (car entry))
  45      "} is in music objects of type "
  46      (human-listify
  47       (sort
  48        (map (lambda (x) (ref-ify (symbol->string x)))
  49             (cdr entry)) string<?))
  50      "."
  51
  52      "\n\nAccepted by: "
  53      (human-listify
  54       (map ref-ify
  55            (map symbol->string
  56                 (map ly:translator-name
  57                      (filter
  58                       (lambda (x) (engraver-accepts-music-type? (car entry) x)) all-engravers-list)))))
  59      "."
  60      "\n\n")))
  61
  62 (define (music-types-doc)
  63   (make <texi-node>
  64     #:name "Music classes"
  65     #:children
  66     (map music-type-doc
  67          (sort
  68           (hash-table->alist music-types->names) alist<?))))
  69
  70 (define (music-doc-str obj)
  71   (let* ((namesym  (car obj))
  72          (props (cdr obj))
  73          (class (ly:camel-case->lisp-identifier namesym))
  74          (classes (ly:make-event-class class))
  75          (event-texi (if classes
  76                          (string-append
  77                           "\n\nEvent classes:\n"
  78                           (human-listify (map ref-ify (map symbol->string classes)))
  79                           "."
  80
  81                           "\n\nAccepted by: "
  82                           (human-listify
  83                            (map ref-ify
  84                                 (map symbol->string (map ly:translator-name
  85                                                          (filter
  86                                                           (lambda (x) (engraver-accepts-music-types? classes x)) all-engravers-list)))))
  87                           ".")
  88                          "")))
  89
  90     (string-append
  91      (object-property namesym 'music-description)
  92      event-texi
  93      "\n\nProperties:\n"
  94      (description-list->texi
  95       (map
  96        (lambda (x) (property->texi 'music x props))
  97        (map car props))))))
  98
  99 (define (music-object-doc obj)
 100   (make <texi-node>
 101     #:name (symbol->string (car obj))
 102     #:text (music-doc-str obj)))
 103
 104 (define (music-expressions-doc)
 105   (make <texi-node>
 106     #:name "Music expressions"
 107     #:desc "Objects that represent music."
 108     #:children
 109     (map music-object-doc music-descriptions)))
 110
 111 (define (music-doc-node)
 112   (make <texi-node>
 113     #:name "Music definitions"
 114     #:desc "Definition of the input data structures."
 115     #:children
 116     (list
 117      (music-expressions-doc)
 118      (music-types-doc)
 119      (music-props-doc))))