1 ;;; backend-documentation-lib.scm -- Functions for backend documentation
3 ;;; source file of the GNU LilyPond music typesetter
5 ;;; (c) 2000 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 (define (backend-property->texi sym)
15 (let* ((name (symbol->string sym))
16 (type (object-property sym 'backend-type?))
17 (typename (type-name type))
18 (desc (object-property sym 'backend-doc)))
20 (cons (string-append "@code{" name "} "
24 ; index gets too messy
25 ; "@vindex " name "\n"
31 (define (document-grob-property sym grob-description )
32 (let* ((handle (assoc sym grob-description))
33 (defval (if (eq? handle #f)
35 (scm->texi (cdr handle))))
36 (propdoc (backend-property->texi sym)))
38 (cons (car propdoc) (string-append (cdr propdoc)
42 (define (document-interface where interface grob-description)
43 (let* ((level (if (eq? where 'grob) 3 2))
44 (name (car interface))
45 (desc (cadr interface))
46 (props (caddr interface))
48 (document-grob-property
49 x grob-description )))
50 (docs (map docfunc props)))
54 (string-append (interface-name (symbol->string name)))
55 (eq? where 'grob)) ;gur.
57 (description-list->texi docs))))
59 ;; First level Interface description
60 (define (document-separate-interface interface)
61 (let ((name (symbol->string (car interface))))
64 (node (interface-name name))
65 (document-interface 'self interface '()))))
67 ;; First level grob description
68 (define (document-grob iname description)
70 (let* ((metah (assoc 'meta description))
72 (meta (if (pair? metah)
74 '((properties . ()) (name . "huh?"))
77 (name (cdr (assoc 'name meta)))
78 (ifaces (cdr (assoc 'interface-descriptions meta)))
79 (ifacedoc (map (lambda (x)
80 (document-interface 'grob x description))
84 (node (grob-name name))
85 (texi-section 2 (grob-name name) #f)
88 (let* ((grob (string->symbol name))
92 (let ((engraver (car x))
94 (if (member grob objs)
97 engraver-description-alist))))
99 name " grobs are created by: "
100 (human-listify (map ref-ify
102 (map symbol->string engravers))))))
104 (apply string-append ifacedoc))))
107 (define (document-all-grobs name)
108 (let* ((doc (apply string-append
110 (document-grob (symbol->string (car x)) (cdr x)))
111 all-grob-descriptions)))
112 (names (map symbol->string (map car all-grob-descriptions))))
115 (texi-node-menu name (map (lambda (x) (cons (grob-name x) ""))
119 ;; ugh, this works standalone, but not anymore with lily
120 (if (not (defined? 'standalone))
123 (debug-enable 'backtrace)
125 (load "standalone.scm")
127 (define (number-pair? x)
128 (and (pair? x) (number? (car x)) (number? (cdr x))))
130 (define (ly-grob? x) #f)
131 (define (ly-input-location? x) #f)
133 (define (moment? x) #f)
136 (use-modules (ice-9 string-fun))
138 (define interface-file-str (string-append (ly-gulp-file "interface-description.scm") "\n(define "))
140 ;;(define (list-interface-names)
141 (define (ugh-standalone-list-interface-names)
142 (let* ((text interface-file-str)
143 (t1 (regexp-substitute/global #f "\n" text 'pre 'post))
144 (t (regexp-substitute/global #f "[^\t ]define[ \t]*([a-z-]+interface)"
146 (ugh (regexp-substitute/global #f " .*" t 'pre 'post))
147 (l (separate-fields-discarding-char #\ ugh list)))
148 (reverse (cdr (reverse l)))))
152 (display "(define (list-interface-names) '")
153 (write (ugh-standalone-list-interface-names))
158 ;; This list is generated manually, by doing:
160 ;; guile> (load "backend-documentation-lib.scm")
161 ;; For some reason, this can't be generated when lilypond is loaded;
162 ;; the regexp stuff behaves weird.
163 (define (list-interface-names) '("general-grob-interface" "beam-interface" "clef-interface" "axis-group-interface" "note-column-interface" "stem-interface" "slur-interface" "side-position-interface" "accidentals-interface" "line-of-score-interface" "note-head-interface" "note-name-interface" "rhythmic-head-interface" "rest-interface" "tuplet-bracket-interface" "align-interface" "aligned-interface" "break-aligned-interface" "chord-name-interface" "time-signature-interface" "bar-line-interface" "hairpin-interface" "arpeggio-interface" "note-collision-interface" "custos-interface" "dot-interface" "font-interface" "text-interface" "dot-column-interface" "dynamic-interface" "finger-interface" "separation-spanner-interface" "text-script-interface" "grace-alignment-interface" "hara-kiri-group-interface" "line-spanner-interface" "lyric-hyphen-interface" "key-signature-interface" "lyric-extender-interface" "lyric-syllable-interface" "mark-interface" "multi-measure-rest-interface" "paper-column-interface" "spaceable-element-interface" "rest-collision-interface" "script-interface" "script-column-interface" "spacing-spanner-interface" "staff-symbol-interface" "stem-tremolo-interface" "separation-item-interface" "sustain-pedal-interface" "system-start-delimiter-interface" "text-spanner-interface" "tie-interface" "tie-column-interface" "volta-bracket-interface" "span-bar-interface"))
166 (eval-string (ly-gulp-file "interface-description.scm"))
168 (define interface-description-alist
169 (map (lambda (x) (cons (string->symbol x) (eval-string x)))
170 (list-interface-names)))
172 (set! interface-description-alist (sort interface-description-alist alist<?))
174 (define (document-all-interfaces name)
176 (texi-node-menu name (map (lambda (x)
177 (cons (interface-name (symbol->string x)) ""))
178 (map cadr interface-description-alist)))
180 (map document-separate-interface
181 (map cdr interface-description-alist)))))
183 (define (document-all-backend-properties name)
186 (ps (sort (map symbol->string all-backend-properties) string<?))
187 (descs (map (lambda (prop)
188 (backend-property->texi (string->symbol prop)))
190 (texi (description-list->texi descs))
195 (texi-section 1 name #f)