2 ;;; engraver-doumentation-lib.scm -- Functions for engraver documentation
4 ;;; source file of the GNU LilyPond music typesetter
6 ;;; (c) 2000--2001 Han-Wen Nienhuys <hanwen@cs.uu.nl>
7 ;;; Jan Nieuwenhuizen <janneke@gnu.org>
11 ;; alist of translater descriptions
12 (define (document-translator-property sym)
15 "@code{" (symbol->string sym) "} "
16 "(" (type-name (object-property sym 'translation-type?)) "):")
17 (object-property sym 'translation-doc)))
19 ;; First level Engraver description and
20 ;; second level Context description
21 (define (document-engraver where engraver)
24 (level (if (eq? where 'context) 3 2))
25 (propsr (cdr (assoc 'properties-read (ly-translator-description engraver))))
26 (propsw (cdr (assoc 'properties-written (ly-translator-description engraver))))
27 (name (ly-translator-name engraver))
28 (name-sym (string->symbol name))
29 (desc (cdr (assoc 'description (ly-translator-description engraver))))
30 (grobs (engraver-grobs engraver))
34 (texi-section level (engraver-name name) (eq? where 'context))
40 (texi-section (+ level 1) "Properties (read)" #f)
41 (description-list->texi
42 (map (lambda (x) (document-translator-property x)) propsr))))
46 (texi-section (+ level 1) "Properties (write)" #f)
47 (description-list->texi
48 (map (lambda (x) (document-translator-property x)) propsw))))
52 "This engraver creates the following grobs: \n "
53 (human-listify (map ref-ify (uniq-list (sort grobs string<? ))))
59 (let* ((paper-alist (My_lily_parser::paper_description))
60 (context-description-alist (map cdr paper-alist))
64 (let ((context (cdr (assoc 'type-name x)))
66 (list (cdr (assoc 'group-type x)))
67 (cdr (assoc 'consists x))
68 (cdr (assoc 'end-consists x)))))
70 (if (member name consists)
73 context-description-alist))))
75 name " is part of contexts: "
76 (human-listify (map ref-ify (map context-name contexts))))))))
79 ;; First level Engraver description
80 (define (document-separate-engraver top grav)
81 (let ((name (ly-translator-name grav)))
84 (node (engraver-name name))
85 (document-engraver 'self grav))))
87 ;; Second level, part of Context description
88 (define (find-engraver-by-name name list)
91 (if (equal? name (ly-translator-name (car list)))
93 (find-engraver-by-name name (cdr list)))))
95 (define (document-engraver-by-name name)
98 (eg (find-engraver-by-name name all-engravers-list))
102 (string-append "Engraver " name ", not documented.\n")
103 (document-engraver 'context eg)
107 (define (document-property-operation op)
118 (if (null? (cddr body))
123 (symbol->string (cadr body))
124 " in " (symbol->string sym)
125 (if (not (null? (cddr body)))
126 (string-append " to " (scm->texi (cadr (cdr body))))
132 ((equal? (object-property sym 'is-grob?) #t) "")
133 ((equal? (car op) 'assign)
135 "@item Set translator property "
136 (symbol->string (car body))
138 (scm->texi (cadr body))
147 (define (context-doc-string context-desc)
150 (name (cdr (assoc 'type-name context-desc)))
151 (desc-handle (assoc (string->symbol name) context-description-alist))
152 (desc (if (pair? desc-handle) (cdr desc-handle) ""))
154 (accepts (cdr (assoc 'accepts context-desc)))
156 (list (cdr (assoc 'group-type context-desc)))
157 (cdr (assoc 'consists context-desc))
158 (cdr (assoc 'end-consists context-desc))
160 (props (cdr (assoc 'property-ops context-desc)))
161 (grobs (context-grobs context-desc))
162 (grob-refs (map (lambda (x) (ref-ify x)) grobs))
167 "\n\nThis context creates the following grobs: \n\n"
168 (human-listify (uniq-list (sort grob-refs string<? )))
172 "\n\nThis context sets the following properties:\n"
174 (apply string-append (map document-property-operation props))
181 "\n\nThis context is a `bottom' context; it can not contain other contexts."
184 name " can contain \n"
185 (human-listify (map ref-ify (map context-name accepts)))))
187 "\n\nThis context is built from the following engravers: "
189 (human-listify (map ref-ify (map engraver-name consists)))
191 (map document-engraver-by-name consists))))))
193 (define (engraver-grobs grav)
195 (eg (if (string? grav)
196 (find-engraver-by-name grav all-engravers-list)
203 (map symbol->string (cdr (assoc 'grobs-created (ly-translator-description eg))))
207 (define (context-grobs context-desc)
210 (list (cdr (assoc 'group-type context-desc)))
211 (cdr (assoc 'consists context-desc))
212 (cdr (assoc 'end-consists context-desc))
215 (map engraver-grobs consists))
222 ;; First level Context description
223 (define (document-context top context-desc)
224 (let ((name (cdr (assoc 'type-name context-desc)))
225 (doc (context-doc-string context-desc)))
228 (node (context-name name))
229 (texi-section 2 (context-name name) #f)
232 (define (symbol<? l r)
233 (string<? (symbol->string l) (symbol->string r)))
235 (define (document-paper name)
237 (sort (My_lily_parser::paper_description)
238 (lambda (x y) (symbol<? (car x) (car y)))))
239 (names (sort (map symbol->string (map car paper-alist)) string<?))
240 (contexts (map cdr paper-alist))
241 (doc (apply string-append
242 (map (lambda (x) (document-context name x)) contexts))))
245 (texi-node-menu name (map (lambda (x) (cons (context-name x) ""))
249 (define all-engravers-list (ly-get-all-translators))
250 (define (document-all-engravers name)
251 (let* ((gravs all-engravers-list)
252 (names (map ly-translator-name gravs))
253 (doc (apply string-append
254 (map (lambda (x) (document-separate-engraver name x))
257 (texi-node-menu name (map (lambda (x) (cons (engraver-name x) ""))
261 (define (document-all-engraver-properties name)
262 (let* ((ps (sort (map symbol->string all-translation-properties) string<?))
263 (sortedsyms (map string->symbol ps))
264 (propdescs (map document-translator-property sortedsyms))
265 (texi (description-list->texi propdescs)))
269 (texi-section 1 name #f)