1 ;;; backend-documentation-lib.scm -- Functions for backend documentation
3 ;;; source file of the GNU LilyPond music typesetter
5 ;;; (c) 2000--2001 Han-Wen Nienhuys <hanwen@cs.uu.nl>
6 ;;; Jan Nieuwenhuizen <janneke@gnu.org>
9 ;;; This file generates documentation for the backend of lilypond.
11 ;; alist of property descriptions
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.
18 (define (backend-property->texi sym)
19 (let* ((name (symbol->string sym))
20 (type (object-property sym 'backend-type?))
21 (typename (type-name type))
22 (desc (object-property sym 'backend-doc)))
26 (error "Unknown property " sym)
28 (cons (string-append "@code{" name "} "
32 ; index gets too messy
33 ; "@vindex " name "\n"
37 (define (document-grob-property sym grob-description )
38 "Document SYM, filling in default values."
39 (let* ((handle (assoc sym grob-description))
40 (defval (if (eq? handle #f)
42 (scm->texi (cdr handle))))
43 (propdoc (backend-property->texi sym)))
45 (cons (car propdoc) (string-append (cdr propdoc)
50 (define (document-interface where interface grob-description)
52 (let* ((level (if (eq? where 'grob) 3 2))
53 (name (car interface))
54 (desc (cadr interface))
55 (props (caddr interface))
57 (document-grob-property
58 pr grob-description )))
59 (docs (map docfunc props)))
63 (string-append (interface-name (symbol->string name)))
64 (eq? where 'grob)) ;gur.
66 (description-list->texi docs))))
68 ;; First level Interface description
69 (define (document-separate-interface interface)
70 (let ((name (symbol->string (car interface))))
73 (node (interface-name name))
74 (document-interface 'self interface '()))))
77 ;; First level grob description
78 (define (document-grob iname description)
80 (let* ((metah (assoc 'meta description))
83 (name (cdr (assoc 'name meta)))
84 (ifaces (map lookup-interface (cdr (assoc 'interfaces meta))))
85 (ifacedoc (map (lambda (iface)
86 (document-interface 'grob iface description))
92 (node (grob-name name))
93 (texi-section 2 (grob-name name) #f)
96 (engravers (filter-list
97 (lambda (x) (engraver-makes-grob? name x)) all-engravers-list))
98 (engraver-names (map Translator::name engravers))
102 (symbol->string name) " grobs are created by: "
103 (human-listify (map ref-ify
104 (map engraver-name engraver-names)))))
106 (apply string-append ifacedoc))))
110 (define (engraver-makes-grob? name-symbol grav)
111 (memq name-symbol (assoc 'grobs-created (Translator::description grav)))
114 (define (document-all-grobs name)
115 (let* ((doc (apply string-append
117 (document-grob (symbol->string (car x)) (cdr x)))
118 all-grob-descriptions)))
119 (names (map symbol->string (map car all-grob-descriptions))))
122 (texi-node-menu name (map (lambda (x) (cons (grob-name x) ""))
126 ;; ugh, this works standalone, but not anymore with lily
127 (if (not (defined? 'standalone))
130 (debug-enable 'backtrace)
132 (load "standalone.scm")
134 (define (number-pair? x)
135 (and (pair? x) (number? (car x)) (number? (cdr x))))
136 (define (ly-grob? x) #f)
137 (define (ly-input-location? x) #f)
139 (define (moment? x) #f)
142 (use-modules (ice-9 string-fun))
146 (display "(define (list-interface-names) '")
147 (write (ugh-standalone-list-interface-names))
152 (define interface-description-alist
154 (lambda (key val prior)
155 (cons (cons key val) prior)
157 '() (ly-all-grob-interfaces)))
159 (set! interface-description-alist (sort interface-description-alist alist<?))
162 ;;;;;;;;;; check for dangling backend properties.
163 (define (mark-interface-properties entry)
164 (map (lambda (x) (set-object-property! x 'iface-marked #t)) (caddr (cdr entry)))
167 (map mark-interface-properties interface-description-alist)
169 (define (check-dangling-properties prop)
170 (if (not (object-property prop 'iface-marked))
171 (error "\nDangling property: " prop))
174 (map check-dangling-properties all-backend-properties)
178 (define (lookup-interface name)
180 (entry (hashq-ref (ly-all-grob-interfaces) name #f))
183 (if (equal? entry #f)
184 (error "Unknown interface" name))
189 ;(write (map car interface-description-alist) (current-error-port))
190 ;(display (lookup-interface 'volta-bracket-interface))
192 (define (document-all-interfaces name)
194 (texi-node-menu name (map (lambda (x)
195 (cons (interface-name (symbol->string x)) ""))
196 (map cadr interface-description-alist)))
198 (map document-separate-interface
199 (map cdr interface-description-alist)))))
201 (define (document-all-backend-properties name)
204 (ps (sort (map symbol->string all-backend-properties) string<?))
205 (descs (map (lambda (prop)
206 (backend-property->texi (string->symbol prop)))
208 (texi (description-list->texi descs))
213 (texi-section 1 name #f)