scm/backend-documentation-lib.scm

   1 ;;; backend-documentation-lib.scm -- Functions for backend documentation
   2 ;;;
   3 ;;; source file of the GNU LilyPond music typesetter
   4 ;;;
   5 ;;; (c) 2000--2002 Han-Wen Nienhuys <hanwen@cs.uu.nl>
   6 ;;; Jan Nieuwenhuizen <janneke@gnu.org>
   7
   8
   9 ;;; This file generates documentation for the backend of lilypond.
  10
  11 ;; alist of property descriptions
  12
  13 ;;
  14 "
  15 TODO:
  16
  17
  18 Grob bla
  19
  20 Created by:
  21
  22   * preset properties + explanation
  23
  24 Interfaces:
  25
  26   * properties available.
  27
  28 "
  29
  30
  31 (define (interface-doc-string interface grob-description)
  32   (let*
  33       (
  34        (name (car interface))
  35        (desc (cadr interface))
  36        (props (sort (caddr interface) symbol<?))
  37        (docfunc (lambda (pr)
  38                   (document-property
  39                    pr 'backend grob-description )))
  40        (propdocs (map docfunc props))
  41        )
  42
  43     (string-append
  44      desc
  45      "\n\n"
  46      (description-list->texi propdocs))
  47
  48     ))
  49
  50
  51 (define iface->grob-table (make-vector 61 '()))
  52 ;; extract ifaces, and put grob into the hash table.
  53 (map
  54  (lambda (x)
  55    (let*
  56        (
  57         (metah (assoc 'meta (cdr x)))
  58         (meta (cdr metah))
  59         (ifaces (cdr (assoc 'interfaces meta)))
  60         )
  61
  62      (map (lambda (iface)
  63             (hashq-set!
  64              iface->grob-table iface
  65              (cons (car x)
  66                    (hashq-ref iface->grob-table iface '())
  67                    )))
  68           ifaces)
  69      ))
  70  all-grob-descriptions)
  71
  72 ;; First level Interface description
  73 (define (interface-doc interface)
  74   (let ((name (symbol->string (car interface))))
  75     (make <texi-node>
  76       #:name name
  77       #:text (string-append
  78               (interface-doc-string (cdr interface) #f)
  79               "\n\n"
  80               "This grob interface is used in the following graphical objects: "
  81
  82               (human-listify
  83                (map ref-ify
  84                     (map symbol->string
  85                          (hashq-ref iface->grob-table (car interface) '() )))))
  86
  87       )))
  88
  89 (define (grob-doc description)
  90   "Given a property alist DESCRIPTION, make a documentation
  91 node."
  92
  93   (let*
  94       (
  95        (metah (assoc 'meta description))
  96
  97        (meta (cdr metah))
  98        (name (cdr (assoc 'name meta)))
  99        (ifaces (map lookup-interface (cdr (assoc 'interfaces meta))))
 100        (ifacedoc (map (lambda (iface)
 101                         (string-append
 102 "@html
 103 <hr>
 104 @end html
 105
 106 @subsubheading "
 107 (ref-ify (symbol->string (car iface)))
 108
 109 "\n\n"
 110                         (interface-doc-string iface description)))
 111                       (reverse ifaces)))
 112        (engravers (filter-list
 113                    (lambda (x) (engraver-makes-grob? name x)) all-engravers-list))
 114        (namestr (symbol->string name))
 115        (engraver-names (map ly:translator-name engravers))
 116        )
 117
 118     (make <texi-node>
 119       #:name namestr
 120       #:text
 121       (string-append
 122        namestr " grobs are created by: "
 123        (human-listify (map ref-ify
 124                            (map engraver-name engraver-names)))
 125        (apply string-append ifacedoc)
 126        ))
 127     ))
 128
 129 (define (all-grobs-doc)
 130   (make <texi-node>
 131     #:name "All Graphical objects"
 132     #:desc "Description and defaults for all Grobs"
 133     #:children
 134     (map (lambda (x) (grob-doc (cdr x)))  all-grob-descriptions)))
 135
 136 (define interface-description-alist
 137   (hash-fold
 138    (lambda (key val prior)
 139      (cons (cons key val)  prior)
 140      )
 141    '() (ly:all-grob-interfaces)))
 142
 143 (set! interface-description-alist (sort interface-description-alist alist<?))
 144
 145
 146 ;;;;;;;;;; check for dangling backend properties.
 147 (define (mark-interface-properties entry)
 148   (map (lambda (x) (set-object-property! x  'iface-marked #t)) (caddr (cdr entry)))
 149   )
 150
 151 (map mark-interface-properties interface-description-alist)
 152
 153 (define (check-dangling-properties prop)
 154   (if (not (object-property prop 'iface-marked))
 155       (error  "\nDangling property: " prop))
 156   )
 157
 158 (map check-dangling-properties all-backend-properties)
 159
 160 ;;;;;;;;;;;;;;;;
 161
 162 (define (lookup-interface name)
 163   (let*  (
 164           (entry  (hashq-ref (ly:all-grob-interfaces) name #f))
 165           )
 166
 167     (if (equal? entry #f)
 168         (error "Unknown interface" name))
 169
 170     entry
 171 ))
 172
 173 (define (all-interfaces-doc)
 174   (make <texi-node>
 175     #:name "Graphical Object Interfaces"
 176     #:desc "Building blocks of graphical objects"
 177     #:children
 178     (map interface-doc interface-description-alist)
 179     ))
 180
 181 (define (all-backend-properties-doc)
 182   (let*
 183       (
 184        (ps (sort (map symbol->string all-backend-properties) string<?))
 185        (descs (map (lambda (prop)
 186                      (document-property (string->symbol prop) 'backend #f))
 187                    ps))
 188        (texi (description-list->texi descs))
 189        )
 190     (make <texi-node>
 191       #:name "backend properties"
 192       #:desc "all the properties in use as grob properties"
 193       #:text texi)
 194   ))
 195
 196 ;(dump-node (grob-doc (cdadr all-grob-descriptions))  (current-output-port) 0 )
 197 (define (backend-doc-node)
 198   (make <texi-node>
 199     #:name "Backend"
 200     #:desc "Reference for the layout engine"
 201     #:children
 202     (list
 203      (all-grobs-doc)
 204      (all-interfaces-doc)
 205      (all-backend-properties-doc)
 206      )
 207   ))