1 ;;;; This file is part of LilyPond, the GNU music typesetter.
3 ;;;; Copyright (C) 2000--2014 Han-Wen Nienhuys <hanwen@xs4all.nl>
4 ;;;; Jan Nieuwenhuizen <janneke@gnu.org>
6 ;;;; LilyPond is free software: you can redistribute it and/or modify
7 ;;;; it under the terms of the GNU General Public License as published by
8 ;;;; the Free Software Foundation, either version 3 of the License, or
9 ;;;; (at your option) any later version.
11 ;;;; LilyPond is distributed in the hope that it will be useful,
12 ;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
13 ;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 ;;;; GNU General Public License for more details.
16 ;;;; You should have received a copy of the GNU General Public License
17 ;;;; along with LilyPond. If not, see <http://www.gnu.org/licenses/>.
19 (define (engraver-makes-grob? name-symbol grav)
20 (memq name-symbol (assoc 'grobs-created (ly:translator-description grav))))
22 (define (engraver-accepts-music-type? name-symbol grav)
23 (memq name-symbol (assoc 'events-accepted (ly:translator-description grav))))
25 (define (engraver-accepts-music-types? types grav)
29 (engraver-accepts-music-type? (car types) grav)
30 (engraver-accepts-music-types? (cdr types) grav))))
32 (define (engraver-doc-string engraver in-which-contexts)
33 (let* ((propsr (assoc-get 'properties-read (ly:translator-description engraver)))
34 (propsw (assoc-get 'properties-written (ly:translator-description engraver)))
35 (accepted (assoc-get 'events-accepted (ly:translator-description engraver)))
36 (name-sym (ly:translator-name engraver))
37 (name-str (symbol->string name-sym))
38 (desc (assoc-get 'description (ly:translator-description engraver)))
39 (grobs (engraver-grobs engraver)))
46 "Music types accepted:\n\n"
48 (map ref-ify (sort (map symbol->string accepted) ly:string-ci<?))))
54 (description-list->texi
55 (map (lambda (x) (property->texi 'translation x '()))
56 (sort propsr ly:symbol-ci<?))
64 (description-list->texi
65 (map (lambda (x) (property->texi 'translation x '()))
66 (sort propsw ly:symbol-ci<?))
71 "\n\nThis engraver creates the following layout object(s):\n\n"
72 (human-listify (map ref-ify (uniq-list (sort grobs ly:string-ci<?))))
78 (let* ((layout-alist (ly:output-description $defaultlayout))
79 (context-description-alist (map cdr layout-alist))
83 (let* ((context (assoc-get 'context-name x))
84 (group (assq-ref x 'group-type))
89 (assoc-get 'consists x))))
90 (if (member name-sym consists)
93 context-description-alist))
94 (context-list (human-listify (map ref-ify
96 (map symbol->string contexts)
99 "@code{" name-str "} "
100 (if (equal? context-list "none")
101 "is not part of any context"
103 "is part of the following context(s): "
108 ;; First level Engraver description
109 (define (engraver-doc grav)
111 #:name (symbol->string (ly:translator-name grav))
112 #:text (engraver-doc-string grav #t)))
114 ;; Second level, part of Context description
115 (define name->engraver-table (make-hash-table 61))
118 (hash-set! name->engraver-table (ly:translator-name x) x))
119 (ly:get-all-translators))
121 (define (find-engraver-by-name name)
123 (hash-ref name->engraver-table name #f))
125 (define (document-engraver-by-name name)
128 (let* ((eg (find-engraver-by-name name)))
130 (cons (string-append "@code{" (ref-ify (symbol->string name)) "}")
131 (engraver-doc-string eg #f))))
133 (define (document-property-operation op)
135 (context-sym (cadr op))
146 (format #f "@item Set grob-property @code{~{~a~^.~}} " path)
147 (format #f "in @ref{~a} to" context-sym)
148 (if (pretty-printable? value)
149 (format #f ":~a\n" (scm->texi value))
150 (format #f " ~a.\n" (scm->texi value))))))
151 ((equal? (object-property context-sym 'is-grob?) #t) "")
152 ((equal? tag 'assign)
154 (format #f "@item Set translator property @code{~a} to" context-sym)
155 (if (pretty-printable? (car args))
156 (format #f ":~a\n" (scm->texi (car args)))
157 (format #f " ~a.\n" (scm->texi (car args)))))))))
160 (define (context-doc context-desc)
161 (let* ((name-sym (assoc-get 'context-name context-desc))
162 (name (symbol->string name-sym))
163 (aliases (map symbol->string (assoc-get 'aliases context-desc)))
164 (desc (assoc-get 'description context-desc "(not documented"))
165 (accepts (assoc-get 'accepts context-desc))
166 (consists (assoc-get 'consists context-desc))
167 (props (assoc-get 'property-ops context-desc))
168 (defaultchild (assoc-get 'default-child context-desc))
169 (grobs (context-grobs context-desc))
170 (grob-refs (map ref-ify (sort grobs ly:string-ci<?))))
179 "\n\nThis context also accepts commands for the following context(s):\n\n"
180 (human-listify (sort aliases ly:string-ci<?))
184 "\n\nThis context creates the following layout object(s):\n\n"
185 (human-listify (uniq-list grob-refs))
188 (if (and (pair? props) (not (null? props)))
189 (let ((str (string-concatenate
190 (sort (map document-property-operation props)
192 (if (string-null? str)
195 "\n\nThis context sets the following properties:\n\n"
202 (format #f "\n\nThis is not a `Bottom' context; search for such a one will commence after creating an implicit context of type @ref{~a}."
204 "\n\nThis is a `Bottom' context; no contexts will be created implicitly from it.")
207 "\n\nThis context cannot contain other contexts."
212 (human-listify (map ref-ify (sort (map symbol->string accepts)
219 "\n\nThis context is built from the following engraver(s):"
220 (description-list->texi
221 (map document-engraver-by-name (sort consists ly:symbol-ci<?))
224 (define (engraver-grobs grav)
225 (let* ((eg (if (symbol? grav)
226 (find-engraver-by-name grav)
230 (map symbol->string (assoc-get 'grobs-created (ly:translator-description eg))))))
232 (define (context-grobs context-desc)
233 (let* ((group (assq-ref context-desc 'group-type))
238 (assoc-get 'consists context-desc)))
239 (grobs (append-map engraver-grobs consists)))
242 (define (all-contexts-doc)
244 (sort (ly:output-description $defaultlayout)
245 (lambda (x y) (ly:symbol-ci<? (car x) (car y)))))
246 (names (sort (map symbol->string (map car layout-alist)) ly:string-ci<?))
247 (contexts (map cdr layout-alist)))
251 #:desc "Complete descriptions of all contexts."
253 (map context-doc contexts))))
255 (define all-engravers-list (ly:get-all-translators))
256 (set! all-engravers-list
257 (sort all-engravers-list
258 (lambda (a b) (ly:string-ci<? (symbol->string (ly:translator-name a))
259 (symbol->string (ly:translator-name b))))))
261 (define (all-engravers-doc)
263 #:name "Engravers and Performers"
264 #:desc "All separate engravers and performers."
265 #:text "See @ruser{Modifying context plug-ins}."
267 (map engraver-doc all-engravers-list)))
269 (define (translation-properties-doc-string lst)
270 (let* ((ps (sort (map symbol->string lst) ly:string-ci<?))
271 (sortedsyms (map string->symbol ps))
274 (lambda (x) (property->texi 'translation x '()))
276 (texi (description-list->texi propdescs #f)))
279 (define (translation-doc-node)
282 #:desc "From music to layout."
288 #:name "Tunable context properties"
289 #:desc "All tunable context properties."
290 #:text (translation-properties-doc-string
291 all-user-translation-properties))
294 #:name "Internal context properties"
295 #:desc "All internal context properties."
296 #:text (translation-properties-doc-string
297 all-internal-translation-properties)))))