;;;; document-translation.scm -- Functions for engraver documentation
;;;;
;;;; source file of the GNU LilyPond music typesetter
-;;;;
-;;;; (c) 2000--2006 Han-Wen Nienhuys <hanwen@xs4all.nl>
+;;;;
+;;;; (c) 2000--2009 Han-Wen Nienhuys <hanwen@xs4all.nl>
;;;; Jan Nieuwenhuizen <janneke@gnu.org>
(define (engraver-makes-grob? name-symbol grav)
(define (engraver-doc-string engraver in-which-contexts)
(let* ((propsr (cdr (assoc 'properties-read (ly:translator-description engraver))))
(propsw (cdr (assoc 'properties-written (ly:translator-description engraver))))
- (accepted (cdr (assoc 'events-accepted (ly:translator-description engraver))))
+ (accepted (cdr (assoc 'events-accepted (ly:translator-description engraver))))
(name-sym (ly:translator-name engraver))
(name-str (symbol->string name-sym))
(desc (cdr (assoc 'description (ly:translator-description engraver))))
(string-append
"Properties (read)"
(description-list->texi
- (map (lambda (x) (property->texi 'translation x '())) propsr)))
+ (map (lambda (x) (property->texi 'translation x '())) propsr)
+ #t))
"")
-
+
(if (null? propsw)
""
(string-append
- "Properties (write)"
+ "Properties (write)"
(description-list->texi
- (map (lambda (x) (property->texi 'translation x '())) propsw))))
+ (map (lambda (x) (property->texi 'translation x '())) propsw)
+ #t)))
(if (null? grobs)
""
(string-append
- "\n\nThis engraver creates the following layout objects:\n\n"
+ "\n\nThis engraver creates the following layout object(s):\n\n"
(human-listify (map ref-ify (uniq-list (sort grobs string<?))))
"."))
(if (member name-sym consists)
(list context)
'())))
- context-description-alist))))
+ context-description-alist)))
+ (context-list (human-listify (map ref-ify
+ (sort
+ (map symbol->string contexts)
+ string<?)))))
(string-append
- "@code{" name-str "} is part of contexts: "
- (human-listify (map ref-ify
- (sort
- (map symbol->string contexts) string<?)))))
+ "@code{" name-str "} "
+ (if (equal? context-list "none")
+ "is not part of any context"
+ (string-append
+ "is part of the following context(s): "
+ context-list))
+ "."))
""))))
;; First level Engraver description
(ly:get-all-translators))
(define (find-engraver-by-name name)
- "NAME is a symbol."
+ "NAME is a symbol."
(hash-ref name->engraver-table name #f))
(define (document-engraver-by-name name)
"NAME is a symbol."
-
+
(let* ((eg (find-engraver-by-name name)))
(cons (string-append "@code{" (ref-ify (symbol->string name)) "}")
context-sym
(scm->texi (car args))))
)))
-
+
(define (context-doc context-desc)
(let* ((name-sym (cdr (assoc 'context-name context-desc)))
(desc-handle (assoc 'description context-desc))
(desc (if (and (pair? desc-handle) (string? (cdr desc-handle)))
(cdr desc-handle) "(not documented)"))
-
+
(accepts (cdr (assoc 'accepts context-desc)))
(consists (cdr (assoc 'consists context-desc)))
(props (cdr (assoc 'property-ops context-desc)))
(make <texi-node>
#:name name
#:text
- (string-append
+ (string-append
desc
(if (pair? aliases)
(string-append
".")
"")
- "\n\nThis context creates the following layout objects:\n\n"
+ "\n\nThis context creates the following layout object(s):\n\n"
(human-listify (uniq-list (sort grob-refs string<?)))
"."
(if (and (pair? props) (not (null? props)))
- (string-append
- "\n\nThis context sets the following properties:\n"
- "@itemize @bullet\n"
- (apply string-append (map document-property-operation props))
- "@end itemize\n")
+ (let ((str (apply string-append (map document-property-operation
+ props))))
+ (if (string-null? str)
+ ""
+ (string-append
+ "\n\nThis context sets the following properties:\n\n"
+ "@itemize @bullet\n"
+ str
+ "@end itemize\n")))
"")
-
+
(if (null? accepts)
"\n\nThis context is a `bottom' context; it cannot contain other contexts."
(string-append
" can contain\n"
(human-listify (map ref-ify (map symbol->string accepts)))
"."))
-
+
(if (null? consists)
""
(string-append
- "\n\nThis context is built from the following engravers:"
- (description-list->texi (map document-engraver-by-name consists))))))))
+ "\n\nThis context is built from the following engraver(s):"
+ (description-list->texi
+ (map document-engraver-by-name consists)
+ #t)))))))
(define (engraver-grobs grav)
(let* ((eg (if (symbol? grav)
(define (all-engravers-doc)
(make <texi-node>
- #:name "Engravers"
- #:desc "All separate engravers."
- #:text "See @usermanref{Modifying context plug-ins}."
+ #:name "Engravers and Performers"
+ #:desc "All separate engravers and performers."
+ #:text "See @ruser{Modifying context plug-ins}."
#:children
(map engraver-doc all-engravers-list)))
(map
(lambda (x) (property->texi 'translation x '()))
sortedsyms))
- (texi (description-list->texi propdescs)))
+ (texi (description-list->texi propdescs #f)))
texi))
(define (translation-doc-node)