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 (engraver-makes-grob? name-symbol grav)
  67   (memq name-symbol (assoc 'grobs-created (ly-translator-description grav)))
  68   )
  69
  70 (define (all-grobs-doc)
  71   (make <texi-node>
  72     #:name "All Graphical objects"
  73     #:desc "Description and defaults for all Grobs"
  74     #:children
  75     (map (lambda (x) (grob-doc (cdr x)))  all-grob-descriptions)))
  76
  77 (define interface-description-alist
  78   (hash-fold
  79    (lambda (key val prior)
  80      (cons (cons key val)  prior)
  81      )
  82    '() (ly-all-grob-interfaces)))
  83
  84 (set! interface-description-alist (sort interface-description-alist alist<?))
  85
  86
  87 ;;;;;;;;;; check for dangling backend properties.
  88 (define (mark-interface-properties entry)
  89   (map (lambda (x) (set-object-property! x  'iface-marked #t)) (caddr (cdr entry)))
  90   )
  91
  92 (map mark-interface-properties interface-description-alist)
  93
  94 (define (check-dangling-properties prop)
  95   (if (not (object-property prop 'iface-marked))
  96       (error  "\nDangling property: " prop))
  97   )
  98
  99 (map check-dangling-properties all-backend-properties)
 100
 101 ;;;;;;;;;;;;;;;;
 102
 103 (define (lookup-interface name)
 104   (let*  (
 105           (entry  (hashq-ref (ly-all-grob-interfaces) name #f))
 106           )
 107
 108     (if (equal? entry #f)
 109         (error "Unknown interface" name))
 110
 111     entry
 112 ))
 113
 114 (define (all-interfaces-doc)
 115   (make <texi-node>
 116     #:name "Graphical Object Interfaces"
 117     #:desc "Building blocks of graphical objects"
 118     #:children
 119     (map interface-doc interface-description-alist)
 120     ))
 121
 122 (define (all-backend-properties-doc)
 123   (let*
 124       (
 125        (ps (sort (map symbol->string all-backend-properties) string<?))
 126        (descs (map (lambda (prop)
 127                      (document-property (string->symbol prop) 'backend #f))
 128                    ps))
 129        (texi (description-list->texi descs))
 130        )
 131     (make <texi-node>
 132       #:name "backend properties"
 133       #:desc "all the properties in use as grob properties"
 134       #:text texi)
 135   ))
 136
 137 ;(dump-node (grob-doc (cdadr all-grob-descriptions))  (current-output-port) 0 )
 138 (define (backend-doc-node)
 139   (make <texi-node>
 140     #:name "Backend"
 141     #:desc "Reference for the layout engine"
 142     #:children
 143     (list
 144      (all-grobs-doc)
 145      (all-interfaces-doc)
 146      (all-backend-properties-doc)
 147      )
 148   ))