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--2001 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 ;;;;;; TODO: sort out symbol vs. string stuff.
  15 ;;;;;; TODO: use flatten write iso. string-append; might be possible to fold
  16 ;;;;;; in symbol->string integrally.
  17
  18 (define (interface-doc-string interface grob-description)
  19   (let* ((name (car interface))
  20          (desc (cadr interface))
  21          (props (sort (caddr interface) symbol<?))
  22          (docfunc (lambda (pr)
  23                     (document-property
  24                      pr 'backend grob-description )))
  25          (propdocs (map docfunc props)))
  26
  27      desc
  28      (description-list->texi propdocs)))
  29
  30 ;; First level Interface description
  31 (define (interface-doc interface)
  32   (let ((name (symbol->string (car interface))))
  33     (make <texi-node>
  34       #:name name
  35       #:text (interface-doc-string (cdr interface) #f))))
  36
  37 ;; First level grob description
  38 (define (grob-doc description)
  39   (let*
  40       (
  41        (metah (assoc 'meta description))
  42
  43        (meta (cdr metah))
  44        (name (cdr (assoc 'name meta)))
  45        (ifaces (map lookup-interface (cdr (assoc 'interfaces meta))))
  46        (ifacedoc (map (lambda (iface)
  47                         (interface-doc-string iface description))
  48                       (reverse ifaces)))
  49        (engravers (filter-list
  50                    (lambda (x) (engraver-makes-grob? name x)) all-engravers-list))
  51        (namestr (symbol->string name))
  52        (engraver-names (map ly-translator-name engravers))
  53        )
  54
  55     (make <texi-node>
  56       #:name namestr
  57       #:text
  58       (string-append
  59        namestr " grobs are created by: "
  60        (human-listify (map ref-ify
  61                            (map engraver-name engraver-names)))
  62        (apply string-append ifacedoc)
  63        ))
  64     ))
  65
  66 (define (all-grobs-doc)
  67   (make <texi-node>
  68     #:name "All Graphical objects"
  69     #:desc "Description and defaults for all Grobs"
  70     #:children
  71     (map (lambda (x) (grob-doc (cdr x)))  all-grob-descriptions)))
  72
  73 (define interface-description-alist
  74   (hash-fold
  75    (lambda (key val prior)
  76      (cons (cons key val)  prior)
  77      )
  78    '() (ly-all-grob-interfaces)))
  79
  80 (set! interface-description-alist (sort interface-description-alist alist<?))
  81
  82
  83 ;;;;;;;;;; check for dangling backend properties.
  84 (define (mark-interface-properties entry)
  85   (map (lambda (x) (set-object-property! x  'iface-marked #t)) (caddr (cdr entry)))
  86   )
  87
  88 (map mark-interface-properties interface-description-alist)
  89
  90 (define (check-dangling-properties prop)
  91   (if (not (object-property prop 'iface-marked))
  92       (error  "\nDangling property: " prop))
  93   )
  94
  95 (map check-dangling-properties all-backend-properties)
  96
  97 ;;;;;;;;;;;;;;;;
  98
  99 (define (lookup-interface name)
 100   (let*  (
 101           (entry  (hashq-ref (ly-all-grob-interfaces) name #f))
 102           )
 103
 104     (if (equal? entry #f)
 105         (error "Unknown interface" name))
 106
 107     entry
 108 ))
 109
 110 (define (all-interfaces-doc)
 111   (make <texi-node>
 112     #:name "Graphical Object Interfaces"
 113     #:desc "Building blocks of graphical objects"
 114     #:children
 115     (map interface-doc interface-description-alist)
 116     ))
 117
 118 (define (all-backend-properties-doc)
 119   (let*
 120       (
 121        (ps (sort (map symbol->string all-backend-properties) string<?))
 122        (descs (map (lambda (prop)
 123                      (document-property (string->symbol prop) 'backend #f))
 124                    ps))
 125        (texi (description-list->texi descs))
 126        )
 127     (make <texi-node>
 128       #:name "backend properties"
 129       #:desc "all the properties in use as grob properties"
 130       #:text texi)
 131   ))
 132
 133 ;(dump-node (grob-doc (cdadr all-grob-descriptions))  (current-output-port) 0 )
 134 (define (backend-doc-node)
 135   (make <texi-node>
 136     #:name "Backend"
 137     #:desc "Reference for the layout engine"
 138     #:children
 139     (list
 140      (all-grobs-doc)
 141      (all-interfaces-doc)
 142      (all-backend-properties-doc)
 143      )
 144   ))