scm/document-backend.scm

   1 ;;; backend-documentation-lib.scm -- Functions for backend documentation
   2 ;;;
   3 ;;; source file of the GNU LilyPond music typesetter
   4 ;;;
   5 ;;; (c)  2000--2003 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  "\ngrob-property-description.scm: Can't find interface for property:" prop)))
 156
 157 (map check-dangling-properties all-backend-properties)
 158
 159 ;;;;;;;;;;;;;;;;
 160
 161 (define (lookup-interface name)
 162   (let*  (
 163           (entry  (hashq-ref (ly:all-grob-interfaces) name #f))
 164           )
 165
 166     (if (equal? entry #f)
 167         (error "Unknown interface" name))
 168
 169     entry
 170 ))
 171
 172 (define (all-interfaces-doc)
 173   (make <texi-node>
 174     #:name "Graphical Object Interfaces"
 175     #:desc "Building blocks of graphical objects"
 176     #:children
 177     (map interface-doc interface-description-alist)
 178     ))
 179
 180 (define (all-backend-properties-doc)
 181   (let*
 182       (
 183        (ps (sort (map symbol->string all-backend-properties) string<?))
 184        (descs (map (lambda (prop)
 185                      (document-property (string->symbol prop) 'backend #f))
 186                    ps))
 187        (texi (description-list->texi descs))
 188        )
 189     (make <texi-node>
 190       #:name "backend properties"
 191       #:desc "all the properties in use as grob properties"
 192       #:text texi)
 193   ))
 194
 195 ;(dump-node (grob-doc (cdadr all-grob-descriptions))  (current-output-port) 0 )
 196 (define (backend-doc-node)
 197   (make <texi-node>
 198     #:name "Backend"
 199     #:desc "Reference for the layout engine"
 200     #:children
 201     (list
 202      (all-grobs-doc)
 203      (all-interfaces-doc)
 204      (all-backend-properties-doc)
 205      )
 206   ))