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--2001 Han-Wen Nienhuys <hanwen@cs.uu.nl>
   7 ;;; Jan Nieuwenhuizen <janneke@gnu.org>
   8
   9 (define (processing name)
  10   (display (string-append "\nProcessing " name " ... ") (current-error-port)))
  11
  12 (define (self-evaluating? x)
  13   (or (number? x) (string? x) (procedure? x) (boolean? x)))
  14
  15 (define (texify x)
  16   x)
  17 ;;  (let*
  18 ;;     ((x1 (regexp-substitute/global #f "\([^@]\){" x 'pre "\1@{" 'post))
  19 ;;      ((x2 (regexp-substitute/global #f "\([^@]\){" x 'pre "\1@{" 'post))
  20 ;;      ((x3 (regexp-substitute/global #f "\([^@]\)@" x 'pre "\1@@" 'post))
  21 ;;       )
  22 ;;    x2))
  23
  24
  25
  26 (define (scm->texi x)
  27   (string-append "@code{" (texify (scm->string x)) "}")
  28   )
  29
  30 (define (scm->string val)
  31   (string-append
  32    (if (self-evaluating? val) "" "'")
  33    (call-with-output-string (lambda (port) (display val port)))
  34   ))
  35
  36 (define (node name)
  37   (string-append
  38    "\n@html"
  39    "\n<hr>"
  40    "\n@end html"
  41    "\n@node " name))
  42
  43 (define texi-section-alist
  44   '(
  45     ;; Hmm, texinfo doesn't have ``part''
  46     (0 . "@top")
  47     (1 . "@unnumbered")
  48     (2 . "@unnumberedsec")
  49     (3 . "@unnumberedsubsec")
  50     (4 . "@unnumberedsubsubsec")
  51     (5 . "@unnumberedsubsubsec")
  52     ))
  53
  54 (define (texi-section level name ref)
  55   "texi sectioning command (lower LEVEL means more significant).
  56 Add a ref if REF is set
  57 "
  58
  59   (string-append
  60    "\n" (cdr (assoc level texi-section-alist)) " "
  61    (if ref
  62        (ref-ify name)
  63        name)
  64    "\n"))
  65
  66
  67 (define (one-item->texi label-desc-pair)
  68   "Document one (LABEL . DESC); return empty string if LABEL is empty string.
  69 "
  70   (if (eq? (car label-desc-pair) "")
  71       ""
  72       (string-append "\n@item " (car label-desc-pair) "\n" (cdr label-desc-pair))
  73   ))
  74
  75
  76 (define (description-list->texi items-alist)
  77   "Document ITEMS-ALIST in a table. entries contain (item-label . string-to-use)
  78 "
  79   (string-append
  80    "\n@table @samp\n"
  81    (apply string-append (map one-item->texi items-alist))
  82    "\n@end table\n"))
  83
  84 (define (texi-menu items-alist)
  85   (let
  86       (
  87        (maxwid (apply max (map (lambda (x) (string-length (car x)))
  88                                items-alist)))
  89        )
  90
  91
  92
  93   (string-append
  94   "\n@menu"
  95   (apply string-append
  96          (map (lambda (x)
  97                 (string-append
  98                 (pad-string-to
  99                  (string-append "\n* " (car x) ":: ")
 100                  (+ maxwid 8)
 101                  )
 102                 (cdr x))
 103                 )
 104               items-alist))
 105   "\n@end menu\n"
 106   ;; Menus don't appear in html, so we make a list ourselves
 107   "\n@ignore\n"
 108   "\n@ifhtml\n"
 109   (description-list->texi (map (lambda (x) (cons (ref-ify (car x)) (cdr x)))
 110                          items-alist))
 111   "\n@end ifhtml\n"
 112   "\n@end ignore\n")))
 113
 114
 115 (define (texi-node-menu name items-alist)
 116   (string-append
 117    (node name)
 118    (texi-section 1 name #f)
 119    (texi-menu items-alist)))
 120
 121
 122
 123 (define (texi-file-head name file-name top items-alist)
 124
 125
 126   (string-append
 127    "\\input texinfo @c -*-texinfo-*-"
 128    "\n@setfilename " file-name ".info"
 129    "\n@settitle " name
 130    "\n@dircategory GNU music project"
 131    "\n@direntry"
 132    ;; prepend GNU for dir, must be unique
 133    "\n* GNU " name ": (" file-name ").          " name "."
 134    "\n@end direntry"
 135    ;; ugh, prev and next should be settable, of course
 136    (node "Top") ",(lilypond)Index,(lilypond)Full Grob interface list," top
 137    "\n@top"
 138    (texi-section 1 name #f)
 139    (texi-menu items-alist)
 140    "\n@contents"
 141    ))
 142
 143 (define (itexi-file-head name file-name top items-alist)
 144   (string-append
 145    "@c -*-texinfo-*-"
 146    (node name) ",,," top
 147    (texi-section 1 name #f)
 148    (texi-menu items-alist)
 149    "\n@contents"
 150    ))
 151
 152
 153 (define (context-name name)
 154   name)
 155
 156 (define (engraver-name name)
 157   name)
 158
 159 (define (grob-name name)
 160   (if (symbol? name)
 161       (symbol->string name)
 162       name))
 163
 164 (define (interface-name name)
 165   name)
 166
 167 (define (ref-ify 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)))