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 "
  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      (description-list->texi propdocs))
  46
  47     ))
  48
  49 ;; First level Interface description
  50 (define (interface-doc interface)
  51   (let ((name (symbol->string (car interface))))
  52     (make <texi-node>
  53       #:name name
  54       #:text (interface-doc-string (cdr interface) #f))))
  55
  56 (define (grob-doc description)
  57   (let*
  58       (
  59        (metah (assoc 'meta description))
  60
  61        (meta (cdr metah))
  62        (name (cdr (assoc 'name meta)))
  63        (ifaces (map lookup-interface (cdr (assoc 'interfaces meta))))
  64        (ifacedoc (map (lambda (iface)
  65                         (interface-doc-string iface description))
  66                       (reverse ifaces)))
  67        (engravers (filter-list
  68                    (lambda (x) (engraver-makes-grob? name x)) all-engravers-list))
  69        (namestr (symbol->string name))
  70        (engraver-names (map ly-translator-name engravers))
  71        )
  72
  73     (make <texi-node>
  74       #:name namestr
  75       #:text
  76       (string-append
  77        namestr " grobs are created by: "
  78        (human-listify (map ref-ify
  79                            (map engraver-name engraver-names)))
  80        (apply string-append ifacedoc)
  81        ))
  82     ))
  83
  84 (define (all-grobs-doc)
  85   (make <texi-node>
  86     #:name "All Graphical objects"
  87     #:desc "Description and defaults for all Grobs"
  88     #:children
  89     (map (lambda (x) (grob-doc (cdr x)))  all-grob-descriptions)))
  90
  91 (define interface-description-alist
  92   (hash-fold
  93    (lambda (key val prior)
  94      (cons (cons key val)  prior)
  95      )
  96    '() (ly-all-grob-interfaces)))
  97
  98 (set! interface-description-alist (sort interface-description-alist alist<?))
  99
 100
 101 ;;;;;;;;;; check for dangling backend properties.
 102 (define (mark-interface-properties entry)
 103   (map (lambda (x) (set-object-property! x  'iface-marked #t)) (caddr (cdr entry)))
 104   )
 105
 106 (map mark-interface-properties interface-description-alist)
 107
 108 (define (check-dangling-properties prop)
 109   (if (not (object-property prop 'iface-marked))
 110       (error  "\nDangling property: " prop))
 111   )
 112
 113 (map check-dangling-properties all-backend-properties)
 114
 115 ;;;;;;;;;;;;;;;;
 116
 117 (define (lookup-interface name)
 118   (let*  (
 119           (entry  (hashq-ref (ly-all-grob-interfaces) name #f))
 120           )
 121
 122     (if (equal? entry #f)
 123         (error "Unknown interface" name))
 124
 125     entry
 126 ))
 127
 128 (define (all-interfaces-doc)
 129   (make <texi-node>
 130     #:name "Graphical Object Interfaces"
 131     #:desc "Building blocks of graphical objects"
 132     #:children
 133     (map interface-doc interface-description-alist)
 134     ))
 135
 136 (define (all-backend-properties-doc)
 137   (let*
 138       (
 139        (ps (sort (map symbol->string all-backend-properties) string<?))
 140        (descs (map (lambda (prop)
 141                      (document-property (string->symbol prop) 'backend #f))
 142                    ps))
 143        (texi (description-list->texi descs))
 144        )
 145     (make <texi-node>
 146       #:name "backend properties"
 147       #:desc "all the properties in use as grob properties"
 148       #:text texi)
 149   ))
 150
 151 ;(dump-node (grob-doc (cdadr all-grob-descriptions))  (current-output-port) 0 )
 152 (define (backend-doc-node)
 153   (make <texi-node>
 154     #:name "Backend"
 155     #:desc "Reference for the layout engine"
 156     #:children
 157     (list
 158      (all-grobs-doc)
 159      (all-interfaces-doc)
 160      (all-backend-properties-doc)
 161      )
 162   ))