2 ;;; documentation-lib.scm -- Assorted Functions for generated 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>
9 (use-modules (oop goops)
13 (define-class <texi-node> ()
14 (children #:init-value '() #:accessor node-children #:init-keyword #:children)
15 (text #:init-value "" #:accessor node-text #:init-keyword #:text)
16 (name #:init-value "" #:accessor node-name #:init-keyword #:name)
17 (description #:init-value "" #:accessor node-desc #:init-keyword #:desc)
20 (define (menu-entry x)
26 (define (dump-node node port level)
34 (texi-section-command level) " "
39 (if (pair? (node-children node))
41 (map (lambda (x) (menu-entry x) )
42 (node-children node)))
45 (map (lambda (x) (dump-node x port (+ 1 level)))
49 (define (processing name)
50 (display (string-append "\nProcessing " name " ... ") (current-error-port)))
52 (define (self-evaluating? x)
53 (or (number? x) (string? x) (procedure? x) (boolean? x)))
59 (string-append "@code{" (texify (scm->string x)) "}")
64 ;; don't confuse users with #<procedure .. > syntax.
66 (define (scm->string val)
67 (if (and (procedure? val) (symbol? (procedure-name val)))
68 (symbol->string (procedure-name val))
70 (if (self-evaluating? val) "" "'")
71 (call-with-output-string (lambda (port) (display val port)))
75 (define (texi-section-command level)
77 ;; Hmm, texinfo doesn't have ``part''
80 (2 . "@unnumberedsec")
81 (3 . "@unnumberedsubsec")
82 (4 . "@unnumberedsubsubsec")
83 (5 . "@unnumberedsubsubsec")
86 (define (one-item->texi label-desc-pair)
87 "Document one (LABEL . DESC); return empty string if LABEL is empty string.
89 (if (eq? (car label-desc-pair) "")
91 (string-append "\n@item " (car label-desc-pair) "\n" (cdr label-desc-pair))
95 (define (description-list->texi items-alist)
96 "Document ITEMS-ALIST in a table. entries contain (item-label
101 (apply string-append (map one-item->texi items-alist))
104 (define (texi-menu items-alist)
105 "Generate what is between @menu and @end menu."
108 (maxwid (apply max (map (lambda (x) (string-length (car x)))
120 (string-append "\n* " (car x) ":: ")
127 ;; Menus don't appear in html, so we make a list ourselves
130 (description-list->texi (map (lambda (x) (cons (ref-ify (car x)) (cdr x)))
138 (define (texi-file-head name file-name top)
140 "\\input texinfo @c -*-texinfo-*-"
141 "\n@setfilename " file-name ".info"
143 "\n@dircategory GNU music project"
145 ;; prepend GNU for dir, must be unique
146 "\n* GNU " name ": (" file-name "). " name "."
151 (define (context-name name)
154 (define (engraver-name name)
157 (define (grob-name name)
159 (symbol->string name)
162 (define (interface-name name)
167 (string-append "@ref{" x "}"))
169 (define (human-listify l)
170 "Produce a textual enumeration from L, a list of strings"
174 ((null? (cdr l)) (car l))
175 ((null? (cddr l)) (string-append (car l) " and " (cadr l)))
176 (else (string-append (car l) ", " (human-listify (cdr l))))
179 (define (writing-wip x)
180 (display (string-append "\nWriting " x " ... ") (current-error-port)))
183 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
186 (define (property->texi where sym)
187 "Document SYM for WHERE (which can be translation, backend, music)"
189 (name (symbol->string sym))
190 (type?-name (string->symbol
191 (string-append (symbol->string where) "-type?")))
192 (doc-name (string->symbol
193 (string-append (symbol->string where) "-doc")))
194 (type (object-property sym type?-name))
195 (typename (type-name type))
196 (desc (object-property sym doc-name)))
199 (error "No description for property ~S" sym)
202 (string-append "@code{" name "} "
208 (define (document-property-value sym alist)
209 "Extract value for SYM from ALIST, return as texi string"
210 (let* ((handle (assoc sym alist)))
213 (scm->texi (cdr handle)))))
215 (define (backend-property->texi sym)
216 (property->texi 'backend sym))
218 (define (document-property sym where alist)
219 "Document SYM. If GROB-DESCRIPTION is not #f, it's an alist
220 containing default values."
222 ((without (property->texi where sym))
231 (document-property-value sym alist))))))