-
;;; backend-documentation-lib.scm -- Functions for backend documentation
;;;
;;; source file of the GNU LilyPond music typesetter
;;; This file generates documentation for the backend of lilypond.
;; alist of property descriptions
-;; when called by First level Interface description, desc == '()
-;; CDR "not set" is only used for Second level Element description
-(define (document-element-property prop desc)
- (let ((handle (assoc (car prop) desc)))
- (cons
- (string-append "@code{" (symbol->string (car prop)) "} "
- "(" (type-name (cadr prop)) ")"
- (if (equal? desc '()) "" ":"))
- (string-append (if (equal? desc '())
- (caddr prop)
- (if (pair? handle)
- (string-append (caddr prop)
- "\ndefault value: @code{"
- (scm->string (cdr handle))
- "}")
- "not set"))))))
-;; First level Interface description
-;; Second level, part of element description
-(define (document-interface level interface element-description)
- (let* ((name (car interface))
+
+(define (document-element-property property-def element-description only-doc-if-set)
+ "
+"
+ (let* (
+ (handle (assoc (car property-def) element-description))
+ (def-val-str (if (eq? handle #f)
+ "not set"
+ (scm->texi (cdr handle))))
+
+ (name (symbol->string (car property-def)))
+ (type (type-name (cadr property-def)))
+ (desc (caddr property-def))
+ )
+
+ (if (and (eq? handle #f) only-doc-if-set)
+ '("" . "")
+ (cons (string-append "@code{" name "} "
+ "(" type ")"
+ ":" )
+ (string-append desc
+ "\nDefault value: "
+ def-val-str))
+ ))
+ )
+
+(define (document-interface where interface element-description)
+ "
+
+"
+ (let* ((level (if (eq? where 'element) 3 2))
+ (name (car interface))
(desc (cadr interface))
(props (caddr interface))
- (docs (map (lambda (x)
- (document-element-property x element-description))
- props)))
+ (docfun (lambda (x)
+ (document-element-property
+ x element-description (eq? where 'element))))
+ (docs (map docfun props))
+ )
(string-append
- (section level (string-append (interface-name (symbol->string name))))
+ (texi-section level (string-append (interface-name (symbol->string name))) (eq? where 'element)) ;gur.
desc
- (description-list
- ;; filter-out entries with CDR "not set"
- (apply append
- (map (lambda (x)
- (if (string-match "not set" (cdr x)) '() (list x)))
- docs))))))
+ (description-list->texi docs)
+ )))
;; First level Interface description
(define (document-separate-interface interface)
(processing name)
(string-append
(node (interface-name name))
- (document-interface 2 interface '()))))
+ (document-interface 'self interface '()))))
;; First level element description
(define (document-element iname description)
(name (cdr (assoc 'name meta)))
(ifaces (cdr (assoc 'interface-descriptions meta)))
- (ifacedoc (map (lambda (x) (document-interface 3 x description))
+ (ifacedoc (map (lambda (x) (document-interface 'element x description))
(reverse ifaces))))
(string-append
(node (element-name name))
- (section 2 (element-name name))
+ (texi-section 2 (element-name name) #f)
"\n"
(let* ((element (string->symbol name))
(load "lily.scm")))
(use-modules (ice-9 string-fun))
+
+(define interface-file-str (string-append (ly-gulp-file "interface.scm") "\n(define "))
(define (list-interface-names)
- (let* ((text (string-append (ly-gulp-file "interface.scm") "\n(define "))
+ (let* ((text interface-file-str)
(r (make-regexp
"\n[(](define *([a-z-]*-interface)*)*[^\n]*"))
(t (regexp-substitute/global #f r text 2 " " 'post))
-;;;
+;;
;;; documentation-lib.scm -- Assorted Functions for generated documentation
;;;
;;; source file of the GNU LilyPond music typesetter
;; )
;; x2))
+
+
+(define (scm->texi x)
+ (string-append "@code{" (texify (scm->string x)) "}")
+ )
+
(define (scm->string val)
(string-append
(if (self-evaluating? val) "" "'")
- (texify
- (call-with-output-string (lambda (port) (display val port))))
+ (call-with-output-string (lambda (port) (display val port)))
))
(define (node name)
"\n@end html"
"\n@node " name ",,,"))
-(define section-alist
+(define texi-section-alist
'(
;; Hmm, texinfo doesn't have ``part''
(0 . "@top")
(5 . "@unnumberedsubsubsec")
))
-(define (section level name)
- (string-append "\n" (cdr (assoc level section-alist)) " " name "\n"))
-
-(define (description-list items-alist)
+(define (texi-section level name ref)
+ "texi sectioning command (lower LEVEL means more significant).
+Add a ref if REF is set
+"
+
+ (string-append
+ "\n" (cdr (assoc level texi-section-alist)) " "
+ (if ref
+ (string-append "@ref{" name "}")
+ name)
+ "\n"))
+
+
+(define (one-item->texi label-desc-pair)
+ "Document one (LABEL . DESC); return empty string if LABEL is empty string.
+"
+ (if (eq? (car label-desc-pair) "")
+ ""
+ (string-append "\n@item " (car label-desc-pair) "\n" (cdr label-desc-pair))
+ ))
+
+
+(define (description-list->texi items-alist)
+ "Document ITEMS-ALIST in a table. entries contain (item-label . string-to-use)
+"
(string-append
"\n@table @samp\n"
- (apply string-append
- (map (lambda (x) (string-append "\n@item " (car x) "\n" (cdr x)))
- items-alist))
+ (apply string-append (map one-item->texi items-alist))
"\n@end table\n"))
(define (texi-menu items-alist)
;; Menus don't appear in html, so we make a list ourselves
"\n@ignore\n"
"\n@ifhtml\n"
- (description-list (map (lambda (x) (cons (reffy (car x)) (cdr x)))
+ (description-list->texi (map (lambda (x) (cons (reffy (car x)) (cdr x)))
items-alist))
"\n@end ifhtml\n"
"\n@end ignore\n"))
(define (texi-node-menu name items-alist)
(string-append
(node name)
- (section 1 name)
+ (texi-section 1 name #f)
(texi-menu items-alist)))
(define (texi-file-head name file-name top items-alist)
"\n@settitle " name
(node "Top") top
"\n@top"
- (section 1 name)
+ (texi-section 1 name #f)
(texi-menu items-alist)
"\n@contents"
))
;; First level Engraver description and
;; second level Context description
-(define (document-engraver level engraver-descr)
+(define (document-engraver where engraver-descr)
(let* (
+ (level (if (eq? where 'context) 3 2))
(props (car (cdddr engraver-descr)))
(name (car engraver-descr))
(desc (cadr engraver-descr))
)
(string-append
- (section level (engraver-name name))
+ (texi-section level (engraver-name name) (eq? where 'context))
desc
"\n\n"
(if (null? props)
""
(string-append
- (section (+ level 1) "Properties")
- (description-list
+ (texi-section (+ level 1) "Properties" #f)
+ (description-list->texi
(map (lambda (x) (document-translator-property x)) props))))
(if (null? objs)
""
(processing name)
(string-append
(node (engraver-name name))
- (document-engraver 2 description))))
+ (document-engraver 'self description))))
;; Second level, part of Context description
(define (document-engraver-by-name name)
(if (eq? eg #f)
(string-append "Engraver " name ", not documented.\n")
- (document-engraver 3 (cdr eg))
+ (document-engraver 'context (cdr eg))
)
))
(processing name)
(string-append
(node (context-name name))
- (section 2 (context-name name))
+ (texi-section 2 (context-name name) #f)
doc)))
(define (document-paper name)
(translator-property-description 'barAlways boolean? " If set to true a bar line is drawn after each note.
")
- (translator-property-description 'defaultBarType string? "Sets the default type of bar line. See Section XREF-barlines [FIXME]
- for a list of available bar types.
+ (translator-property-description 'defaultBarType string? "Sets the default type of bar line. Available bar types: [FIXME]
")
(translator-property-description 'skipBars boolean? " Set to true to skip the empty bars that are produced by
multimeasure notes and rests. These bars will not appear on the
projects / lilypond.git / commitdiff