2 ;;;; documentation-lib.scm -- Assorted Functions for generated documentation
4 ;;;; source file of the GNU LilyPond music typesetter
6 ;;;; (c) 2000--2007 Han-Wen Nienhuys <hanwen@xs4all.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))
19 (define (menu-entry x)
24 (define (dump-node node port level)
30 (texi-section-command level) " "
35 (if (pair? (node-children node))
37 (map (lambda (x) (menu-entry x))
38 (node-children node)))
41 (map (lambda (x) (dump-node x port (+ 1 level)))
42 (node-children node)))
44 (define (processing name)
45 (ly:message (_ "Processing ~S...") name))
47 (define (self-evaluating? x)
48 (or (number? x) (string? x) (procedure? x) (boolean? x)))
54 (string-append "@code{" (texify (scm->string x)) "}"))
58 (define (texi-section-command level)
60 ;; Hmm, texinfo doesn't have ``part''
63 (2 . "@unnumberedsec")
64 (3 . "@unnumberedsubsec")
65 (4 . "@unnumberedsubsubsec")
66 (5 . "@unnumberedsubsubsec")))))
68 (define (one-item->texi label-desc-pair)
69 "Document one (LABEL . DESC); return empty string if LABEL is empty string."
70 (if (eq? (car label-desc-pair) "")
72 (string-append "\n@item " (car label-desc-pair) "\n" (cdr label-desc-pair))))
75 (define (description-list->texi items-alist quote?)
76 "Document ITEMS-ALIST in a table; entries contain (item-label .
77 string-to-use). If QUOTE? is #t, embed table in a @quotation environment."
80 (if quote? "@quotation\n" "")
82 (apply string-append (map one-item->texi items-alist))
85 (if quote? "@end quotation\n" "")))
87 (define (texi-menu items-alist)
88 "Generate what is between @menu and @end menu."
90 (apply max (map (lambda (x) (string-length (car x))) items-alist))))
98 (string-append "\n* " (car x) ":: ")
103 ;; Menus don't appear in html, so we make a list ourselves
106 (description-list->texi (map (lambda (x) (cons (ref-ify (car x)) (cdr x)))
112 (define (texi-file-head name file-name top)
114 "\\input texinfo @c -*-texinfo-*-"
115 "\n@setfilename " file-name ".info"
117 "\n@dircategory LilyPond"
119 ;; prepend GNU for dir, must be unique
120 "\n* GNU " name ": (" file-name "). " name "."
122 "@documentlanguage en\n"
123 "@documentencoding utf-8\n"))
125 (define (context-name name)
128 (define (engraver-name name)
131 (define (grob-name name)
133 (symbol->string name)
136 (define (interface-name name)
141 (string-append "@ref{" x "}"))
143 (define (human-listify lst)
144 "Produce a textual enumeration from LST, a list of strings"
148 ((null? (cdr lst)) (car lst))
149 ((null? (cddr lst)) (string-append (car lst) " and " (cadr lst)))
150 (else (string-append (car lst) ", " (human-listify (cdr lst))))))
152 (define (writing-wip x)
153 (ly:message (_ "Writing ~S...") x))
156 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
159 (define (property->texi where sym . rest)
160 "Document SYM for WHERE (which can be translation, backend, music),
161 with init values from ALIST (1st optional argument)
163 (let* ((name (symbol->string sym))
164 (alist (if (pair? rest) (car rest) '()))
165 (type?-name (string->symbol
166 (string-append (symbol->string where) "-type?")))
167 (doc-name (string->symbol
168 (string-append (symbol->string where) "-doc")))
169 (type (object-property sym type?-name))
170 (typename (type-name type))
171 (desc (object-property sym doc-name))
172 (handle (assoc sym alist)))
175 (ly:error (_ "cannot find description for property ~S (~S)") sym where))
178 (string-append "@code{" name "} "
183 (scm->texi (cdr handle))