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
  31 ;;
  32 ;; don't confuse users with #<procedure .. > syntax.
  33 ;;
  34 (define (scm->string val)
  35   (if (and (procedure? val) (symbol? (procedure-name val)))
  36       (symbol->string (procedure-name val))
  37       (string-append
  38        (if (self-evaluating? val) "" "'")
  39        (call-with-output-string (lambda (port) (display val port)))
  40        )))
  41
  42 (define (node name)
  43   (string-append
  44    "\n@html"
  45    "\n<hr>"
  46    "\n@end html"
  47    "\n@node " name))
  48
  49 (define texi-section-alist
  50   '(
  51     ;; Hmm, texinfo doesn't have ``part''
  52     (0 . "@top")
  53     (1 . "@unnumbered")
  54     (2 . "@unnumberedsec")
  55     (3 . "@unnumberedsubsec")
  56     (4 . "@unnumberedsubsubsec")
  57     (5 . "@unnumberedsubsubsec")
  58     ))
  59
  60 (define (texi-section level name ref)
  61   "texi sectioning command (lower LEVEL means more significant).
  62 Add a ref if REF is set
  63 "
  64
  65   (string-append
  66    "\n" (cdr (assoc level texi-section-alist)) " "
  67    (if ref
  68        (ref-ify name)
  69        name)
  70    "\n"))
  71
  72
  73 (define (one-item->texi label-desc-pair)
  74   "Document one (LABEL . DESC); return empty string if LABEL is empty string.
  75 "
  76   (if (eq? (car label-desc-pair) "")
  77       ""
  78       (string-append "\n@item " (car label-desc-pair) "\n" (cdr label-desc-pair))
  79   ))
  80
  81
  82 (define (description-list->texi items-alist)
  83   "Document ITEMS-ALIST in a table. entries contain (item-label . string-to-use)
  84 "
  85   (string-append
  86    "\n@table @samp\n"
  87    (apply string-append (map one-item->texi items-alist))
  88    "\n@end table\n"))
  89
  90 (define (texi-menu items-alist)
  91   (let
  92       (
  93        (maxwid (apply max (map (lambda (x) (string-length (car x)))
  94                                items-alist)))
  95        )
  96
  97
  98
  99   (string-append
 100   "\n@menu"
 101   (apply string-append
 102          (map (lambda (x)
 103                 (string-append
 104                 (pad-string-to
 105                  (string-append "\n* " (car x) ":: ")
 106                  (+ maxwid 8)
 107                  )
 108                 (cdr x))
 109                 )
 110               items-alist))
 111   "\n@end menu\n"
 112   ;; Menus don't appear in html, so we make a list ourselves
 113   "\n@ignore\n"
 114   "\n@ifhtml\n"
 115   (description-list->texi (map (lambda (x) (cons (ref-ify (car x)) (cdr x)))
 116                          items-alist))
 117   "\n@end ifhtml\n"
 118   "\n@end ignore\n")))
 119
 120
 121 (define (texi-node-menu name items-alist)
 122   (string-append
 123    (node name)
 124    (texi-section 1 name #f)
 125    (texi-menu items-alist)))
 126
 127
 128
 129 (define (texi-file-head name file-name top items-alist)
 130
 131
 132   (string-append
 133    "\\input texinfo @c -*-texinfo-*-"
 134    "\n@setfilename " file-name ".info"
 135    "\n@settitle " name
 136    "\n@dircategory GNU music project"
 137    "\n@direntry"
 138    ;; prepend GNU for dir, must be unique
 139    "\n* GNU " name ": (" file-name ").          " name "."
 140    "\n@end direntry"
 141    ;; ugh, prev and next should be settable, of course
 142    (node "Top") ",(lilypond)Index,(lilypond)Full Grob interface list," top
 143    "\n@top"
 144    (texi-section 1 name #f)
 145    (texi-menu items-alist)
 146    "\n@contents"
 147    ))
 148
 149 (define (itexi-file-head name file-name top items-alist)
 150   (string-append
 151    "@c -*-texinfo-*-"
 152    (node name) ",,," top
 153    (texi-section 1 name #f)
 154    (texi-menu items-alist)
 155    "\n@contents"
 156    ))
 157
 158
 159 (define (context-name name)
 160   name)
 161
 162 (define (engraver-name name)
 163   name)
 164
 165 (define (grob-name name)
 166   (if (symbol? name)
 167       (symbol->string name)
 168       name))
 169
 170 (define (interface-name name)
 171   name)
 172
 173 (define (ref-ify x)
 174   (string-append "@ref{" x "}"))
 175
 176 (define (human-listify l)
 177   "Produce a textual enumeration from L, a list of strings"
 178
 179   (cond
 180    ((null? l) "none")
 181    ((null? (cdr l)) (car l))
 182    ((null? (cddr l)) (string-append (car l) " and " (cadr l)))
 183    (else (string-append (car l) ", " (human-listify (cdr l))))
 184    ))
 185
 186 (define (writing-wip x)
 187   (display (string-append "\nWriting " x " ... ") (current-error-port)))