]> git.donarmstrong.com Git - lilypond.git/blob - scm/backend-documentation-lib.scm
* scm/music-documentation-lib.scm: dump music expressions and
[lilypond.git] / 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   ))