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--2004 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       ((name (car interface))
  34        (desc (cadr interface))
  35        (props (sort (caddr interface) symbol<?))
  36        (docfunc (lambda (pr)
  37                   (document-property
  38                    pr 'backend grob-description)))
  39        (propdocs (map docfunc props)))
  40     (string-append
  41      desc
  42      "\n\n"
  43      (description-list->texi propdocs))
  44     ))
  45
  46
  47 (define iface->grob-table (make-vector 61 '()))
  48 ;; extract ifaces, and put grob into the hash table.
  49 (map
  50  (lambda (x)
  51    (let*
  52        (
  53         (metah (assoc 'meta (cdr x)))
  54         (meta (cdr metah))
  55         (ifaces (cdr (assoc 'interfaces meta)))
  56         )
  57
  58      (map (lambda (iface)
  59             (hashq-set!
  60              iface->grob-table iface
  61              (cons (car x)
  62                    (hashq-ref iface->grob-table iface '())
  63                    )))
  64           ifaces)
  65      ))
  66  all-grob-descriptions)
  67
  68 ;; First level Interface description
  69 (define (interface-doc interface)
  70   (let ((name (symbol->string (car interface))))
  71     (make <texi-node>
  72       #:name name
  73       #:text (string-append
  74               (interface-doc-string (cdr interface) #f)
  75               "\n\n"
  76               "This grob interface is used in the following graphical objects: "
  77
  78               (human-listify
  79                (map ref-ify
  80                     (map symbol->string
  81                          (hashq-ref iface->grob-table (car interface) '() )))))
  82
  83       )))
  84
  85 (define (grob-doc description)
  86   "Given a property alist DESCRIPTION, make a documentation
  87 node."
  88
  89   (let*
  90       (
  91        (metah (assoc 'meta description))
  92
  93        (meta (cdr metah))
  94        (name (cdr (assoc 'name meta)))
  95        (ifaces (map lookup-interface (cdr (assoc 'interfaces meta))))
  96        (ifacedoc (map (lambda (iface)
  97                         (string-append
  98 "
  99 @subsubheading "
 100 (ref-ify (symbol->string (car iface)))
 101
 102 "\n\n"
 103                         (interface-doc-string iface description)))
 104                       (reverse ifaces)))
 105        (engravers (filter
 106                    (lambda (x) (engraver-makes-grob? name x)) all-engravers-list))
 107        (namestr (symbol->string name))
 108        (engraver-names (map symbol->string (map ly:translator-name engravers)))
 109        )
 110
 111     (make <texi-node>
 112       #:name namestr
 113       #:text
 114       (string-append
 115        namestr " grobs are created by: "
 116        (human-listify (map ref-ify
 117                            (map engraver-name engraver-names)))
 118        (apply string-append ifacedoc)
 119        ))
 120     ))
 121
 122 (define (all-grobs-doc)
 123   (make <texi-node>
 124     #:name "All layout objects"
 125     #:desc "Description and defaults for all Grobs"
 126     #:children
 127     (map (lambda (x) (grob-doc (cdr x)))  all-grob-descriptions)))
 128
 129 (define interface-description-alist
 130   (hash-fold
 131    (lambda (key val prior)
 132      (cons (cons key val)  prior)
 133      )
 134    '() (ly:all-grob-interfaces)))
 135
 136 (set! interface-description-alist (sort interface-description-alist alist<?))
 137
 138
 139 ;;;;;;;;;; check for dangling backend properties.
 140 (define (mark-interface-properties entry)
 141   (map (lambda (x) (set-object-property! x  'iface-marked #t)) (caddr (cdr entry)))
 142   )
 143
 144 (map mark-interface-properties interface-description-alist)
 145
 146 (define (check-dangling-properties prop)
 147   (if (not (object-property prop 'iface-marked))
 148       (error  "\ndefine-grob-properties.scm: Can't find interface for property:" prop)))
 149
 150 (map check-dangling-properties all-backend-properties)
 151
 152 ;;;;;;;;;;;;;;;;
 153
 154 (define (lookup-interface name)
 155   (let*  (
 156           (entry  (hashq-ref (ly:all-grob-interfaces) name #f))
 157           )
 158
 159     (if (equal? entry #f)
 160         (error "Unknown interface" name))
 161
 162     entry
 163 ))
 164
 165 (define (all-interfaces-doc)
 166   (make <texi-node>
 167     #:name "Graphical Object Interfaces"
 168     #:desc "Building blocks of graphical objects"
 169     #:children
 170     (map interface-doc interface-description-alist)
 171     ))
 172
 173 (define (all-backend-properties-doc)
 174   (let*
 175       (
 176        (ps (sort (map symbol->string all-backend-properties) string<?))
 177        (descs (map (lambda (prop)
 178                      (document-property (string->symbol prop) 'backend #f))
 179                    ps))
 180        (texi (description-list->texi descs))
 181        )
 182     (make <texi-node>
 183       #:name "All backend properties"
 184       #:desc "All grob properties in a big list"
 185       #:text texi)
 186   ))
 187
 188 ;(dump-node (grob-doc (cdadr all-grob-descriptions))  (current-output-port) 0 )
 189 (define (backend-doc-node)
 190   (make <texi-node>
 191     #:name "Backend"
 192     #:desc "Reference for the layout engine"
 193     #:children
 194     (list
 195      (all-grobs-doc)
 196      (all-interfaces-doc)
 197      (all-backend-properties-doc)
 198      )
 199   ))