scm/document-music.scm

   1 ;;;; This file is part of LilyPond, the GNU music typesetter.
   2 ;;;;
   3 ;;;; Copyright (C) 1998--2015 Han-Wen Nienhuys <hanwen@xs4all.nl>
   4 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
   5 ;;;;
   6 ;;;; LilyPond is free software: you can redistribute it and/or modify
   7 ;;;; it under the terms of the GNU General Public License as published by
   8 ;;;; the Free Software Foundation, either version 3 of the License, or
   9 ;;;; (at your option) any later version.
  10 ;;;;
  11 ;;;; LilyPond is distributed in the hope that it will be useful,
  12 ;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 ;;;; GNU General Public License for more details.
  15 ;;;;
  16 ;;;; You should have received a copy of the GNU General Public License
  17 ;;;; along with LilyPond.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 (define (music-props-doc)
  20   (make <texi-node>
  21     #:name "Music properties"
  22     #:desc "All music properties, including descriptions."
  23     #:text
  24     (let* ((ps (sort (map symbol->string all-music-properties) ly:string-ci<?))
  25            (descs (map (lambda (prop)
  26                          (property->texi 'music (string->symbol prop)))
  27                        ps))
  28            (texi (description-list->texi descs #f)))
  29       texi)))
  30
  31 (define music-types->names (make-hash-table 61))
  32
  33 (for-each (lambda (entry)
  34             (let* ((class (ly:camel-case->lisp-identifier (car entry)))
  35                    (classes (ly:make-event-class class)))
  36               (if classes
  37                   (for-each
  38                    (lambda (cl)
  39                      (hashq-set! music-types->names cl
  40                                  (cons (car entry)
  41                                        (hashq-ref music-types->names cl '()))))
  42                    classes))))
  43           music-descriptions)
  44
  45 (define (strip-description x)
  46   (cons (symbol->string (car x))
  47         ""))
  48
  49 (define (music-type-doc entry)
  50   (let* ((accept-list (human-listify
  51                        (map ref-ify
  52                             (map symbol->string
  53                                  (map ly:translator-name
  54                                       (filter
  55                                        (lambda (x)
  56                                          (engraver-accepts-music-type? (car entry) x))
  57                                        all-engravers-list)))))))
  58     (make <texi-node>
  59       #:name (symbol->string (car entry))
  60       #:text
  61       (string-append
  62        "\nMusic event type @code{"
  63        (symbol->string (car entry))
  64        "} is in music objects of type "
  65        (human-listify
  66         (map ref-ify (sort (map symbol->string (cdr entry))
  67                            ly:string-ci<?)))
  68        "."
  69
  70        "\n\n"
  71        (if (equal? accept-list "none")
  72            "Not accepted by any engraver or performer"
  73            (string-append
  74             "Accepted by: "
  75             accept-list))
  76        "."))))
  77
  78 (define (music-types-doc)
  79   (make <texi-node>
  80     #:name "Music classes"
  81     #:children
  82     (map music-type-doc
  83          (sort
  84           (hash-table->alist music-types->names) ly:alist-ci<?))))
  85
  86 (define (music-doc-str obj)
  87   (let* ((namesym  (car obj))
  88          (props (cdr obj))
  89          (class (ly:camel-case->lisp-identifier namesym))
  90          (classes (ly:make-event-class class))
  91          (accept-list (if classes
  92                           (human-listify
  93                            (map ref-ify
  94                                 (map symbol->string
  95                                      (map ly:translator-name
  96                                           (filter
  97                                            (lambda (x)
  98                                              (engraver-accepts-music-types? classes x))
  99                                            all-engravers-list)))))
 100                           ""))
 101          (event-texi (if classes
 102                          (string-append
 103                           "\n\nEvent classes:\n"
 104                           (human-listify
 105                            (map ref-ify (sort (map symbol->string classes)
 106                                               ly:string-ci<?)))
 107                           "."
 108
 109                           "\n\n"
 110                           (if (equal? accept-list "none")
 111                               "Not accepted by any engraver or performer"
 112                               (string-append
 113                                "Accepted by: "
 114                                accept-list))
 115                           ".")
 116                          "")))
 117
 118     (string-append
 119      (object-property namesym 'music-description)
 120      event-texi
 121      "\n\nProperties:\n"
 122      (description-list->texi
 123       (map
 124        (lambda (x) (property->texi 'music x props))
 125        (sort (map car props) ly:symbol-ci<?))
 126       #t))))
 127
 128 (define (music-object-doc obj)
 129   (make <texi-node>
 130     #:name (symbol->string (car obj))
 131     #:text (music-doc-str obj)))
 132
 133 (define (music-expressions-doc)
 134   (make <texi-node>
 135     #:name "Music expressions"
 136     #:desc "Objects that represent music."
 137     #:children
 138     (map music-object-doc music-descriptions)))
 139
 140 (define (music-doc-node)
 141   (make <texi-node>
 142     #:name "Music definitions"
 143     #:desc "Definition of the input data structures."
 144     #:children
 145     (list
 146      (music-expressions-doc)
 147      (music-types-doc)
 148      (music-props-doc))))