scm/backend-documentation-lib.scm

   1
   2 ;;; backend-documentation-lib.scm -- Functions for backend documentation
   3 ;;;
   4 ;;; source file of the GNU LilyPond music typesetter
   5 ;;;
   6 ;;; (c) 2000 Han-Wen Nienhuys <hanwen@cs.uu.nl>
   7 ;;; Jan Nieuwenhuizen <janneke@gnu.org>
   8
   9
  10 ;;; This file generates documentation for the backend of lilypond.
  11
  12
  13 ;; alist of property descriptions
  14 (define (document-element-property prop desc)
  15   (let ((handle (assoc (car prop) desc)))
  16     (cons
  17      (string-append
  18       "@code{" (symbol->string (car prop)) "} "
  19       "(" (type-name (cadr prop)) "):")
  20      (string-append
  21       (caddr prop)
  22       "\ndefault value: @code{"
  23       (if (pair? handle)
  24           (scm->string (cdr handle))
  25           "not set" )
  26       "}"))))
  27
  28 ;; First level Interface description
  29 ;; Second level, part of element description
  30 (define (document-interface level interface element-description)
  31   (let* ((name (car interface))
  32          (desc (cadr interface))
  33          (props (caddr interface))
  34          (docs (map (lambda (x)
  35                       (document-element-property x element-description))
  36                     props)))
  37
  38     (string-append
  39      (section level (string-append (interface-name (symbol->string name))))
  40      desc
  41      (description-list docs))))
  42
  43 ;; First level Interface description
  44 (define (document-separate-interface interface)
  45   (let ((name (car interface)))
  46     (string-append
  47      (node (interface-name name))
  48      (document-interface 2 interface '()))))
  49
  50 ;; First level element description
  51 (define (document-element iname description)
  52   (display (string-append "\nProcessing " iname " ... ") (current-error-port))
  53   (let* ((metah (assoc 'meta description))
  54
  55          (meta (if (pair? metah)
  56                    (cdr metah)
  57                    '((properties . ()) (name . "huh?"))
  58                    ))
  59
  60          (name (cdr (assoc 'name meta)))
  61          (ifaces (cdr (assoc 'interface-descriptions meta)))
  62          (ifacedoc (map (lambda (x) (document-interface 3 x description))
  63                         (reverse ifaces))))
  64
  65     (string-append
  66      (node (element-name name))
  67      (section 2 (element-name name))
  68      "\n"
  69
  70      (let* ((element (string->symbol name))
  71             (engravers
  72              (apply append
  73                     (map (lambda (x)
  74                            (let ((engraver (car x))
  75                                  (objs (cadddr x)))
  76                              (if (member element objs)
  77                                  (list engraver)
  78                                  '())))
  79                          engraver-description-alist))))
  80        (string-append
  81         name " elements are created by: "
  82         (human-listify (map reffy (map engraver-name engravers)))))
  83
  84      (apply string-append ifacedoc))))
  85
  86
  87 (define (document-all-elements name)
  88   (let* ((doc (apply string-append
  89                      (map (lambda (x) (document-element (car x) (cdr x)))
  90                           all-element-descriptions)))
  91          (names (map car all-element-descriptions)))
  92
  93     (string-append
  94      (texi-node-menu name (map (lambda (x) (cons (element-name x) ""))
  95                                names))
  96      doc)))
  97
  98 ;; testin.. -- how to do this
  99 (eval-string (ly-gulp-file "interface.scm"))
 100 (define interface-description-alist
 101   `(
 102     (general-element . ,general-element-interface)
 103     (beam . ,beam-interface)
 104     (clef . ,clef-interface)
 105     (slur . ,slur-interface)
 106     ))
 107
 108 (define (document-all-interfaces name)
 109   (string-append
 110    (texi-node-menu name (map (lambda (x) (cons (interface-name x) ""))
 111                              (map cadr interface-description-alist)))
 112    (apply string-append
 113           (map document-separate-interface
 114                (map cdr interface-description-alist)))))
 115
 116