2 ;;; engraver-doumentation-lib.scm -- Functions for engraver documentation
4 ;;; source file of the GNU LilyPond music typesetter
6 ;;; (c) 2000--2003 Han-Wen Nienhuys <hanwen@cs.uu.nl>
7 ;;; Jan Nieuwenhuizen <janneke@gnu.org>
10 (define (engraver-makes-grob? name-symbol grav)
11 (memq name-symbol (assoc 'grobs-created (ly:translator-description grav)))
14 (define (engraver-accepts-music-type? name-symbol grav)
15 (memq name-symbol (assoc 'events-accepted (ly:translator-description grav)))
19 (define (engraver-accepts-music-types? types grav)
23 (engraver-accepts-music-type? (car types) grav)
24 (engraver-accepts-music-types? (cdr types) grav)))
27 (define (engraver-doc-string engraver in-which-contexts)
29 (propsr (cdr (assoc 'properties-read (ly:translator-description engraver))))
30 (propsw (cdr (assoc 'properties-written (ly:translator-description engraver))))
31 (accepted (cdr (assoc 'events-accepted (ly:translator-description engraver))))
32 (name (ly:translator-name engraver))
33 (name-sym (string->symbol name))
34 (desc (cdr (assoc 'description (ly:translator-description engraver))))
35 (grobs (engraver-grobs engraver))
43 "Music types accepted:\n\n"
56 (description-list->texi
57 (map (lambda (x) (document-property x 'translation #f)) propsr)))
64 (description-list->texi
65 (map (lambda (x) (document-property x 'translation #f)) propsw))))
69 "This engraver creates the following grobs: \n "
70 (human-listify (map ref-ify (uniq-list (sort grobs string<? ))))
77 (let* ((paper-alist (My_lily_parser::paper_description))
78 (context-description-alist (map cdr paper-alist))
82 (let ((context (cdr (assoc 'type-name x)))
84 (list (cdr (assoc 'group-type x)))
85 (cdr (assoc 'consists x))
86 (cdr (assoc 'end-consists x)))))
88 (if (member name consists)
91 context-description-alist))))
93 name " is part of contexts: "
94 (human-listify (map ref-ify (map symbol->string contexts)))))
101 ;; First level Engraver description
102 (define (engraver-doc grav)
104 #:name (ly:translator-name grav)
105 #:text (engraver-doc-string grav #t)
108 ;; Second level, part of Context description
110 (define name->engraver-table (make-vector 61 '()))
113 (hash-set! name->engraver-table (ly:translator-name x) x))
114 (ly:get-all-translators))
116 (define (find-engraver-by-name name)
117 (hash-ref name->engraver-table name #f))
119 (define (document-engraver-by-name name)
122 (eg (find-engraver-by-name name ))
126 (engraver-doc-string eg #f)
131 (define (document-property-operation op)
142 (if (null? (cddr body))
146 "grob-property @code{"
147 (symbol->string (cadr body))
148 "} in @ref{" (symbol->string sym)
150 (if (not (null? (cddr body)))
151 (string-append " to @code{" (scm->texi (cadr (cdr body))) "}" )
157 ((equal? (object-property sym 'is-grob?) #t) "")
158 ((equal? (car op) 'assign)
160 "@item Set translator property @code{"
161 (symbol->string (car body))
163 (scm->texi (cadr body))
171 (define (context-doc context-desc)
174 (name-sym (cdr (assoc 'type-name context-desc)))
175 (name (symbol->string name-sym))
176 (aliases (map symbol->string (cdr (assoc 'aliases context-desc))))
177 (desc-handle (assoc 'description context-desc))
178 (desc (if (and (pair? desc-handle) (string? (cdr desc-handle)))
179 (cdr desc-handle) "(not documented)"))
181 (accepts (cdr (assoc 'accepts context-desc)))
183 (list (cdr (assoc 'group-type context-desc)))
184 (cdr (assoc 'consists context-desc))
185 (cdr (assoc 'end-consists context-desc))
187 (props (cdr (assoc 'property-ops context-desc)))
188 (grobs (context-grobs context-desc))
189 (grob-refs (map (lambda (x) (ref-ify x)) grobs)) )
196 "\n\n This context is also known as: \n\n"
197 (human-listify aliases)
198 "\n\nThis context creates the following grobs: \n\n"
199 (human-listify (uniq-list (sort grob-refs string<? )))
203 "\n\nThis context sets the following properties:\n"
205 (apply string-append (map document-property-operation props))
212 "\n\nThis context is a `bottom' context; it can not contain other contexts."
215 name " can contain \n"
216 (human-listify (map ref-ify (map symbol->string accepts)))))
218 "\n\nThis context is built from the following engravers: "
219 (description-list->texi
220 (map document-engraver-by-name consists))
223 (define (engraver-grobs grav)
225 (eg (if (string? grav)
226 (find-engraver-by-name grav)
233 (map symbol->string (cdr (assoc 'grobs-created (ly:translator-description eg))))
237 (define (context-grobs context-desc)
240 (list (cdr (assoc 'group-type context-desc)))
241 (cdr (assoc 'consists context-desc))
242 (cdr (assoc 'end-consists context-desc))
245 (map engraver-grobs consists))
251 (define (symbol<? l r)
252 (string<? (symbol->string l) (symbol->string r)))
254 (define (all-contexts-doc)
257 (sort (My_lily_parser::paper_description)
258 (lambda (x y) (symbol<? (car x) (car y)))))
259 (names (sort (map symbol->string (map car paper-alist)) string<?))
260 (contexts (map cdr paper-alist))
265 #:desc "Complete descriptions of all contexts"
267 (map context-doc contexts)
272 (define all-engravers-list (ly:get-all-translators))
273 (set! all-engravers-list
274 (sort all-engravers-list
275 (lambda (a b) (string<? (ly:translator-name a)
276 (ly:translator-name b)))))
278 (define (all-engravers-doc)
281 #:desc "All separate engravers"
283 (map engraver-doc all-engravers-list)))
285 (define (all-translation-properties-doc)
289 (ps (sort (map symbol->string all-translation-properties) string<?))
290 (sortedsyms (map string->symbol ps))
293 (lambda (x) (document-property x 'translation #f))
295 (texi (description-list->texi propdescs))
299 #:name "Context properties"
300 #:desc "All context properties"
305 ;(dump-node (all-contexts-doc) (current-output-port) 0 )
307 (define (translation-doc-node)
310 #:desc "From music to layout"
315 (all-translation-properties-doc)