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 "
 103 @subsubheading "
 104 (ref-ify (symbol->string (car iface)))
 105
 106 "\n\n"
 107                         (interface-doc-string iface description)))
 108                       (reverse ifaces)))
 109        (engravers (filter
 110                    (lambda (x) (engraver-makes-grob? name x)) all-engravers-list))
 111        (namestr (symbol->string name))
 112        (engraver-names (map ly:translator-name engravers))
 113        )
 114
 115     (make <texi-node>
 116       #:name namestr
 117       #:text
 118       (string-append
 119        namestr " grobs are created by: "
 120        (human-listify (map ref-ify
 121                            (map engraver-name engraver-names)))
 122        (apply string-append ifacedoc)
 123        ))
 124     ))
 125
 126 (define (all-grobs-doc)
 127   (make <texi-node>
 128     #:name "All layout objects"
 129     #:desc "Description and defaults for all Grobs"
 130     #:children
 131     (map (lambda (x) (grob-doc (cdr x)))  all-grob-descriptions)))
 132
 133 (define interface-description-alist
 134   (hash-fold
 135    (lambda (key val prior)
 136      (cons (cons key val)  prior)
 137      )
 138    '() (ly:all-grob-interfaces)))
 139
 140 (set! interface-description-alist (sort interface-description-alist alist<?))
 141
 142
 143 ;;;;;;;;;; check for dangling backend properties.
 144 (define (mark-interface-properties entry)
 145   (map (lambda (x) (set-object-property! x  'iface-marked #t)) (caddr (cdr entry)))
 146   )
 147
 148 (map mark-interface-properties interface-description-alist)
 149
 150 (define (check-dangling-properties prop)
 151   (if (not (object-property prop 'iface-marked))
 152       (error  "\ngrob-property-description.scm: Can't find interface for property:" prop)))
 153
 154 (map check-dangling-properties all-backend-properties)
 155
 156 ;;;;;;;;;;;;;;;;
 157
 158 (define (lookup-interface name)
 159   (let*  (
 160           (entry  (hashq-ref (ly:all-grob-interfaces) name #f))
 161           )
 162
 163     (if (equal? entry #f)
 164         (error "Unknown interface" name))
 165
 166     entry
 167 ))
 168
 169 (define (all-interfaces-doc)
 170   (make <texi-node>
 171     #:name "Graphical Object Interfaces"
 172     #:desc "Building blocks of graphical objects"
 173     #:children
 174     (map interface-doc interface-description-alist)
 175     ))
 176
 177 (define (all-backend-properties-doc)
 178   (let*
 179       (
 180        (ps (sort (map symbol->string all-backend-properties) string<?))
 181        (descs (map (lambda (prop)
 182                      (document-property (string->symbol prop) 'backend #f))
 183                    ps))
 184        (texi (description-list->texi descs))
 185        )
 186     (make <texi-node>
 187       #:name "All backend properties"
 188       #:desc "All grob properties in a big list"
 189       #:text texi)
 190   ))
 191
 192 ;(dump-node (grob-doc (cdadr all-grob-descriptions))  (current-output-port) 0 )
 193 (define (backend-doc-node)
 194   (make <texi-node>
 195     #:name "Backend"
 196     #:desc "Reference for the layout engine"
 197     #:children
 198     (list
 199      (all-grobs-doc)
 200      (all-interfaces-doc)
 201      (all-backend-properties-doc)
 202      )
 203   ))