scm/documentation-lib.scm

   1 ;;;
   2 ;;; documentation-lib.scm -- Assorted Functions for generated documentation
   3 ;;;
   4 ;;; source file of the GNU LilyPond music typesetter
   5 ;;;
   6 ;;; (c)  2000--2003 Han-Wen Nienhuys <hanwen@cs.uu.nl>
   7 ;;; Jan Nieuwenhuizen <janneke@gnu.org>
   8
   9 (use-modules (oop goops)
  10              (srfi srfi-13)
  11              (srfi srfi-1)
  12              )
  13
  14 (define-class <texi-node> ()
  15   (children #:init-value '() #:accessor node-children #:init-keyword #:children)
  16   (text #:init-value "" #:accessor node-text #:init-keyword #:text)
  17   (name #:init-value "" #:accessor node-name #:init-keyword #:name)
  18   (description #:init-value "" #:accessor node-desc #:init-keyword #:desc)
  19   )
  20
  21 (define (menu-entry x)
  22   (cons
  23    (node-name x)
  24    (node-desc x))
  25   )
  26
  27 (define (dump-node node port level)
  28   (display
  29    (string-append
  30     "\n@html"
  31     "\n<hr>"
  32     "\n@end html\n@node "
  33     (node-name node)
  34     "\n\n"
  35     (texi-section-command level) " "
  36     (node-name node)
  37     "\n\n"
  38     (node-text node)
  39     "\n\n"
  40     (if (pair? (node-children node))
  41         (texi-menu
  42          (map (lambda (x) (menu-entry x) )
  43               (node-children node)))
  44          ""))
  45    port)
  46   (map (lambda (x) (dump-node x port (+ 1 level)))
  47         (node-children node))
  48   )
  49
  50 (define (processing name)
  51   (display (string-append "\nProcessing " name " ... ") (current-error-port)))
  52
  53 (define (self-evaluating? x)
  54   (or (number? x) (string? x) (procedure? x) (boolean? x)))
  55
  56 (define (texify x)
  57   x)
  58
  59 (define (scm->texi x)
  60   (string-append "@code{" (texify (scm->string x)) "}")
  61   )
  62
  63
  64 ;;
  65 ;; don't confuse users with #<procedure .. > syntax.
  66 ;;
  67 (define (scm->string val)
  68   (if (and (procedure? val) (symbol? (procedure-name val)))
  69       (symbol->string (procedure-name val))
  70       (string-append
  71        (if (self-evaluating? val) "" "'")
  72        (call-with-output-string (lambda (port) (display val port)))
  73        )))
  74
  75
  76 (define (texi-section-command level)
  77   (cdr (assoc level '(
  78     ;; Hmm, texinfo doesn't have ``part''
  79     (0 . "@top")
  80     (1 . "@unnumbered")
  81     (2 . "@unnumberedsec")
  82     (3 . "@unnumberedsubsec")
  83     (4 . "@unnumberedsubsubsec")
  84     (5 . "@unnumberedsubsubsec")
  85     ))))
  86
  87 (define (one-item->texi label-desc-pair)
  88   "Document one (LABEL . DESC); return empty string if LABEL is empty string.
  89 "
  90   (if (eq? (car label-desc-pair) "")
  91       ""
  92       (string-append "\n@item " (car label-desc-pair) "\n" (cdr label-desc-pair))
  93   ))
  94
  95
  96 (define (description-list->texi items-alist)
  97   "Document ITEMS-ALIST in a table. entries contain (item-label
  98 . string-to-use)
  99 "
 100   (string-append
 101    "\n@table @asis\n"
 102    (apply string-append (map one-item->texi items-alist))
 103    "\n@end table\n"))
 104
 105 (define (texi-menu items-alist)
 106   "Generate what is between @menu and @end menu."
 107   (let
 108       (
 109        (maxwid (apply max (map (lambda (x) (string-length (car x)))
 110                                items-alist)))
 111        )
 112
 113
 114
 115   (string-append
 116   "\n@menu"
 117   (apply string-append
 118          (map (lambda (x)
 119                 (string-append
 120                 (string-pad-right
 121                  (string-append "\n* " (car x) ":: ")
 122                  (+ maxwid 8)
 123                  )
 124                 (cdr x))
 125                 )
 126               items-alist))
 127   "\n@end menu\n"
 128   ;; Menus don't appear in html, so we make a list ourselves
 129   "\n@ignore\n"
 130   "\n@ifhtml\n"
 131   (description-list->texi (map (lambda (x) (cons (ref-ify (car x)) (cdr x)))
 132                          items-alist))
 133   "\n@end ifhtml\n"
 134   "\n@end ignore\n")))
 135
 136
 137
 138
 139 (define (texi-file-head name file-name top)
 140   (string-append
 141    "\\input texinfo @c -*-texinfo-*-"
 142    "\n@setfilename " file-name ".info"
 143    "\n@settitle " name
 144    "\n@dircategory GNU music project"
 145    "\n@direntry"
 146    ;; prepend GNU for dir, must be unique
 147    "\n* GNU " name ": (" file-name ").          " name "."
 148    "\n@end direntry"
 149    ))
 150
 151
 152 (define (context-name name)
 153   name)
 154
 155 (define (engraver-name name)
 156   name)
 157
 158 (define (grob-name name)
 159   (if (symbol? name)
 160       (symbol->string name)
 161       name))
 162
 163 (define (interface-name name)
 164   name)
 165
 166 (define (ref-ify x)
 167   "Add ref to X"
 168   (string-append "@ref{" x "}"))
 169
 170 (define (human-listify l)
 171   "Produce a textual enumeration from L, a list of strings"
 172
 173   (cond
 174    ((null? l) "none")
 175    ((null? (cdr l)) (car l))
 176    ((null? (cddr l)) (string-append (car l) " and " (cadr l)))
 177    (else (string-append (car l) ", " (human-listify (cdr l))))
 178    ))
 179
 180 (define (writing-wip x)
 181   (display (string-append "\nWriting " x " ... ") (current-error-port)))
 182
 183
 184 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 185 ;; property  stuff.
 186
 187 (define (property->texi where sym)
 188   "Document SYM for WHERE (which can be translation, backend, music)"
 189   (let* (
 190          (name (symbol->string sym))
 191          (type?-name (string->symbol
 192                       (string-append (symbol->string where) "-type?")))
 193          (doc-name (string->symbol
 194                     (string-append (symbol->string where) "-doc")))
 195          (type (object-property sym type?-name))
 196          (typename (type-name type))
 197          (desc (object-property sym doc-name)))
 198
 199     (if (eq? desc #f)
 200         (error "No description for property ~S" sym)
 201         )
 202     (cons
 203      (string-append "@code{" name "} "
 204                     "(" typename ")")
 205      desc)
 206
 207     ))
 208
 209 (define (document-property-value sym alist)
 210   "Extract value for SYM from ALIST, return as texi string"
 211   (let* ((handle (assoc sym alist)))
 212     (if (eq? handle #f)
 213         "(unset)"
 214         (scm->texi (cdr handle)))))
 215
 216 (define (backend-property->texi sym)
 217   (property->texi 'backend sym))
 218
 219 (define (document-property sym where alist)
 220   "Document SYM. If GROB-DESCRIPTION is not #f, it's an alist
 221 containing default values."
 222   (let*
 223       ((without (property->texi where sym))
 224        (rv
 225
 226         (cons (car without)
 227               (if (eq? alist #f)
 228                   (cdr without)
 229                   (string-append
 230                    (cdr without)
 231                    "\nDefault value: "
 232                    (document-property-value sym alist))))))
 233     rv))