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