1 ;;;; document-translation.scm -- Functions for engraver documentation
3 ;;;; source file of the GNU LilyPond music typesetter
5 ;;;; (c) 2000--2004 Han-Wen Nienhuys <hanwen@cs.uu.nl>
6 ;;;; Jan Nieuwenhuizen <janneke@gnu.org>
9 (define (engraver-makes-grob? name-symbol grav)
10 (memq name-symbol (assoc 'grobs-created (ly:translator-description grav)))
13 (define (engraver-accepts-music-type? name-symbol grav)
14 (memq name-symbol (assoc 'events-accepted (ly:translator-description grav)))
18 (define (engraver-accepts-music-types? types grav)
22 (engraver-accepts-music-type? (car types) grav)
23 (engraver-accepts-music-types? (cdr types) grav)))
26 (define (engraver-doc-string engraver in-which-contexts)
28 (propsr (cdr (assoc 'properties-read (ly:translator-description engraver))))
29 (propsw (cdr (assoc 'properties-written (ly:translator-description engraver))))
30 (accepted (cdr (assoc 'events-accepted (ly:translator-description engraver))))
31 (name-sym (ly:translator-name engraver))
32 (name-str (symbol->string name-sym))
33 (desc (cdr (assoc 'description (ly:translator-description engraver))))
34 (grobs (engraver-grobs engraver))
42 "Music types accepted:\n\n"
55 (description-list->texi
56 (map (lambda (x) (property->texi 'translation x '())) propsr)))
63 (description-list->texi
64 (map (lambda (x) (property->texi 'translation x '())) propsw))))
68 "This engraver creates the following layout objects: \n "
69 (human-listify (map ref-ify (uniq-list (sort grobs string<? ))))
77 ((paper-alist (My_lily_parser::paper_description))
78 (context-description-alist (map cdr paper-alist))
84 ((context (cdr (assoc 'context-name x)))
85 (group (assq-ref x 'group-type))
90 (cdr (assoc 'consists x))
95 (if (member name-sym consists)
98 context-description-alist))))
100 "@code{" name-str "} is part of contexts: "
101 (human-listify (map ref-ify
103 (map symbol->string contexts) string<?)))))
110 ;; First level Engraver description
111 (define (engraver-doc grav)
113 #:name (symbol->string (ly:translator-name grav))
114 #:text (engraver-doc-string grav #t)
117 ;; Second level, part of Context description
119 (define name->engraver-table (make-vector 61 '()))
122 (hash-set! name->engraver-table (ly:translator-name x) x))
123 (ly:get-all-translators))
125 (define (find-engraver-by-name name)
127 (hash-ref name->engraver-table name #f))
129 (define (document-engraver-by-name name)
133 (eg (find-engraver-by-name name ))
136 (cons (symbol->string name )
137 (engraver-doc-string eg #f)
141 (define (document-property-operation op)
152 (if (null? (cddr body))
156 "grob-property @code{"
157 (symbol->string (cadr body))
158 "} in @ref{" (symbol->string sym)
160 (if (not (null? (cddr body)))
161 (string-append " to @code{" (scm->texi (cadr (cdr body))) "}" )
167 ((equal? (object-property sym 'is-grob?) #t) "")
168 ((equal? (car op) 'assign)
170 "@item Set translator property @code{"
171 (symbol->string (car body))
173 (scm->texi (cadr body))
181 (define (context-doc context-desc)
184 (name-sym (cdr (assoc 'context-name context-desc)))
185 (name (symbol->string name-sym))
186 (aliases (map symbol->string (cdr (assoc 'aliases context-desc))))
187 (desc-handle (assoc 'description context-desc))
188 (desc (if (and (pair? desc-handle) (string? (cdr desc-handle)))
189 (cdr desc-handle) "(not documented)"))
191 (accepts (cdr (assoc 'accepts context-desc)))
192 (group (assq-ref context-desc 'group-type))
195 (if group (list group)
197 (cdr (assoc 'consists context-desc))
199 (props (cdr (assoc 'property-ops context-desc)))
200 (grobs (context-grobs context-desc))
201 (grob-refs (map (lambda (x) (ref-ify x)) grobs)) )
208 "\n\n This context is also known as: \n\n"
209 (human-listify aliases)
210 "\n\nThis context creates the following layout objects: \n\n"
211 (human-listify (uniq-list (sort grob-refs string<? )))
215 "\n\nThis context sets the following properties:\n"
217 (apply string-append (map document-property-operation props))
224 "\n\nThis context is a `bottom' context; it can not contain other contexts."
227 name " can contain \n"
228 (human-listify (map ref-ify (map symbol->string accepts)))))
230 "\n\nThis context is built from the following engravers: "
231 (description-list->texi
232 (map document-engraver-by-name consists))
235 (define (engraver-grobs grav)
236 (let* ((eg (if (symbol? grav)
237 (find-engraver-by-name grav)
241 (map symbol->string (cdr (assoc 'grobs-created (ly:translator-description eg)))))
244 (define (context-grobs context-desc)
246 (group (assq-ref context-desc 'group-type))
251 (cdr (assoc 'consists context-desc))
254 (map engraver-grobs consists))
261 (define (all-contexts-doc)
264 (sort (My_lily_parser::paper_description)
265 (lambda (x y) (symbol<? (car x) (car y)))))
266 (names (sort (map symbol->string (map car paper-alist)) string<?))
267 (contexts (map cdr paper-alist))
272 #:desc "Complete descriptions of all contexts"
274 (map context-doc contexts)
279 (define all-engravers-list (ly:get-all-translators))
280 (set! all-engravers-list
281 (sort all-engravers-list
282 (lambda (a b) (string<? (symbol->string (ly:translator-name a))
283 (symbol->string (ly:translator-name b))))))
285 (define (all-engravers-doc)
288 #:desc "All separate engravers"
290 (map engraver-doc all-engravers-list)))
292 (define (translation-properties-doc-string lst)
294 ((ps (sort (map symbol->string lst) string<?))
295 (sortedsyms (map string->symbol ps))
298 (lambda (x) (property->texi 'translation x '()))
300 (texi (description-list->texi propdescs)))
305 (define (translation-doc-node)
308 #:desc "From music to layout"
314 #:name "Tunable context properties"
315 #:desc "All tunable context properties"
316 #:text (translation-properties-doc-string
317 all-user-translation-properties))
320 #:name "Internal context properties"
321 #:desc "All internal context properties"
322 #:text (translation-properties-doc-string
323 all-internal-translation-properties))