scm/document-music.scm

   1 ;;;; This file is part of LilyPond, the GNU music typesetter.
   2 ;;;;
   3 ;;;; Copyright (C) 1998--2012 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 (filter-map (lambda (entry)
  33               (let* ((class (ly:camel-case->lisp-identifier (car entry)))
  34                      (classes (ly:make-event-class class)))
  35                 (if classes
  36                     (map
  37                      (lambda (cl)
  38                        (hashq-set! music-types->names cl
  39                                    (cons (car entry)
  40                                          (hashq-ref music-types->names cl '()))))
  41                      classes)
  42                     #f)))
  43
  44             music-descriptions)
  45
  46 (define (strip-description x)
  47   (cons (symbol->string (car x))
  48         ""))
  49
  50 (define (music-type-doc entry)
  51   (let* ((accept-list (human-listify
  52                        (map ref-ify
  53                             (map symbol->string
  54                                  (map ly:translator-name
  55                                       (filter
  56                                        (lambda (x)
  57                                          (engraver-accepts-music-type? (car entry) x))
  58                                        all-engravers-list)))))))
  59     (make <texi-node>
  60       #:name (symbol->string (car entry))
  61       #:text
  62       (string-append
  63        "\nMusic event type @code{"
  64        (symbol->string (car entry))
  65        "} is in music objects of type "
  66        (human-listify
  67         (map ref-ify (sort (map symbol->string (cdr entry))
  68                            ly:string-ci<?)))
  69        "."
  70
  71        "\n\n"
  72        (if (equal? accept-list "none")
  73            "Not accepted by any engraver or performer"
  74            (string-append
  75             "Accepted by: "
  76             accept-list))
  77        "."))))
  78
  79 (define (music-types-doc)
  80   (make <texi-node>
  81     #:name "Music classes"
  82     #:children
  83     (map music-type-doc
  84          (sort
  85           (hash-table->alist music-types->names) ly:alist-ci<?))))
  86
  87 (define (music-doc-str obj)
  88   (let* ((namesym  (car obj))
  89          (props (cdr obj))
  90          (class (ly:camel-case->lisp-identifier namesym))
  91          (classes (ly:make-event-class class))
  92          (accept-list (if classes
  93                           (human-listify
  94                            (map ref-ify
  95                                 (map symbol->string
  96                                      (map ly:translator-name
  97                                           (filter
  98                                            (lambda (x)
  99                                              (engraver-accepts-music-types? classes x))
 100                                            all-engravers-list)))))
 101                           ""))
 102          (event-texi (if classes
 103                          (string-append
 104                           "\n\nEvent classes:\n"
 105                           (human-listify
 106                            (map ref-ify (sort (map symbol->string classes)
 107                                               ly:string-ci<?)))
 108                           "."
 109
 110                           "\n\n"
 111                           (if (equal? accept-list "none")
 112                               "Not accepted by any engraver or performer"
 113                               (string-append
 114                                "Accepted by: "
 115                                accept-list))
 116                           ".")
 117                          "")))
 118
 119     (string-append
 120      (object-property namesym 'music-description)
 121      event-texi
 122      "\n\nProperties:\n"
 123      (description-list->texi
 124       (map
 125        (lambda (x) (property->texi 'music x props))
 126        (sort (map car props) ly:symbol-ci<?))
 127       #t))))
 128
 129 (define (music-object-doc obj)
 130   (make <texi-node>
 131     #:name (symbol->string (car obj))
 132     #:text (music-doc-str obj)))
 133
 134 (define (music-expressions-doc)
 135   (make <texi-node>
 136     #:name "Music expressions"
 137     #:desc "Objects that represent music."
 138     #:children
 139     (map music-object-doc music-descriptions)))
 140
 141 (define (music-doc-node)
 142   (make <texi-node>
 143     #:name "Music definitions"
 144     #:desc "Definition of the input data structures."
 145     #:children
 146     (list
 147      (music-expressions-doc)
 148      (music-types-doc)
 149      (music-props-doc))))