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--2007 Han-Wen Nienhuys <hanwen@xs4all.nl>
   7 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
   8
   9 (use-modules (oop goops)
  10              (srfi srfi-13)
  11              (srfi srfi-1))
  12
  13 (define-class <texi-node> ()
  14   (children #:init-value '() #:accessor node-children #:init-keyword #:children)
  15   (text #:init-value "" #:accessor node-text #:init-keyword #:text)
  16   (name #:init-value "" #:accessor node-name #:init-keyword #:name)
  17   (description #:init-value "" #:accessor node-desc #:init-keyword #:desc))
  18
  19 (define (menu-entry x)
  20   (cons
  21    (node-name x)
  22    (node-desc x)))
  23
  24 (define* (dump-node node port level #:optional (appendix #f))
  25   (display
  26    (string-append
  27     "\n@node "
  28     (node-name node)
  29     "\n\n"
  30     (if appendix
  31         (texi-appendix-section-command level)
  32         (texi-section-command level))
  33     " "
  34     (node-name node)
  35     "\n\n"
  36     (node-text node)
  37     "\n\n"
  38     (if (pair? (node-children node))
  39         (texi-menu
  40          (map (lambda (x) (menu-entry x))
  41               (node-children node)))
  42         ""))
  43    port)
  44   (map (lambda (x) (dump-node x port (+ 1 level) appendix))
  45        (node-children node)))
  46
  47 (define (processing name)
  48   (ly:message (_ "Processing ~S...") name))
  49
  50 (define (self-evaluating? x)
  51   (or (number? x) (string? x) (procedure? x) (boolean? x)))
  52
  53 (define (texify x)
  54   x)
  55
  56 (define (scm->texi x)
  57   (string-append "@code{" (texify (scm->string x)) "}"))
  58
  59
  60
  61 (define (texi-section-command level)
  62   (cdr (assoc level '(
  63                       ;; Hmm, texinfo doesn't have ``part''
  64                       (0 . "@top")
  65                       (1 . "@unnumbered")
  66                       (2 . "@unnumberedsec")
  67                       (3 . "@unnumberedsubsec")
  68                       (4 . "@unnumberedsubsubsec")
  69                       (5 . "@unnumberedsubsubsec")))))
  70
  71 (define (texi-appendix-section-command level)
  72   (cdr (assoc level '((0 . "@top")
  73                       (1 . "@appendix")
  74                       (2 . "@appendixsec")
  75                       (3 . "@appendixsubsec")
  76                       (4 . "@appendixsubsubsec")
  77                       (5 . "@appendixsubsubsec")))))
  78
  79 (define (one-item->texi label-desc-pair)
  80   "Document one (LABEL . DESC); return empty string if LABEL is empty string."
  81   (if (eq? (car label-desc-pair) "")
  82       ""
  83       (string-append "\n@item " (car label-desc-pair) "\n" (cdr label-desc-pair))))
  84
  85
  86 (define (description-list->texi items-alist quote?)
  87   "Document ITEMS-ALIST in a table; entries contain (item-label .
  88 string-to-use).  If QUOTE? is #t, embed table in a @quotation environment."
  89   (string-append
  90    "\n"
  91    (if quote? "@quotation\n" "")
  92    "@table @asis\n"
  93    (apply string-append (map one-item->texi items-alist))
  94    "\n"
  95    "@end table\n"
  96    (if quote? "@end quotation\n" "")))
  97
  98 (define (texi-menu items-alist)
  99   "Generate what is between @menu and @end menu."
 100   (let ((maxwid
 101          (apply max (map (lambda (x) (string-length (car x))) items-alist))))
 102
 103     (string-append
 104      "\n@menu"
 105      (apply string-append
 106             (map (lambda (x)
 107                    (string-append
 108                     (string-pad-right
 109                      (string-append "\n* " (car x) ":: ")
 110                      (+ maxwid 8))
 111                     (cdr x)))
 112                  items-alist))
 113      "\n@end menu\n"
 114      ;; Menus don't appear in html, so we make a list ourselves
 115      "\n@ignore\n"
 116      "\n@ifhtml\n"
 117      (description-list->texi (map (lambda (x) (cons (ref-ify (car x)) (cdr x)))
 118                                   items-alist)
 119                              #t)
 120      "\n@end ifhtml\n"
 121      "\n@end ignore\n")))
 122
 123 (define (texi-file-head name file-name top)
 124   (string-append
 125    "\\input texinfo @c -*-texinfo-*-"
 126    "\n@setfilename " file-name ".info"
 127    "\n@settitle " name
 128    "\n@dircategory LilyPond"
 129    "\n@direntry"
 130    ;; prepend GNU for dir, must be unique
 131    "\n* GNU " name ": (" file-name ").          " name "."
 132    "\n@end direntry\n"
 133    "@documentlanguage en\n"
 134    "@documentencoding utf-8\n"))
 135
 136 (define (context-name name)
 137   name)
 138
 139 (define (engraver-name name)
 140   name)
 141
 142 (define (grob-name name)
 143   (if (symbol? name)
 144       (symbol->string name)
 145       name))
 146
 147 (define (interface-name name)
 148   name)
 149
 150 (define (ref-ify x)
 151   "Add ref to X"
 152   (string-append "@ref{" x "}"))
 153
 154 (define (human-listify lst)
 155   "Produce a textual enumeration from LST, a list of strings"
 156
 157   (cond
 158    ((null? lst) "none")
 159    ((null? (cdr lst)) (car lst))
 160    ((null? (cddr lst)) (string-append (car lst) " and " (cadr lst)))
 161    (else (string-append (car lst) ", " (human-listify (cdr lst))))))
 162
 163 (define (writing-wip x)
 164   (ly:message (_ "Writing ~S...") x))
 165
 166
 167 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 168 ;; property  stuff.
 169
 170 (define (property->texi where sym . rest)
 171   "Document SYM for WHERE (which can be translation, backend, music),
 172 with init values from ALIST (1st optional argument)
 173 "
 174   (let* ((name (symbol->string sym))
 175          (alist (if (pair? rest) (car rest) '()))
 176          (type?-name (string->symbol
 177                       (string-append (symbol->string where) "-type?")))
 178          (doc-name (string->symbol
 179                     (string-append (symbol->string where) "-doc")))
 180          (type (object-property sym type?-name))
 181          (typename (type-name type))
 182          (desc (object-property sym doc-name))
 183          (handle (assoc sym alist)))
 184
 185     (if (eq? desc #f)
 186         (ly:error (_ "cannot find description for property ~S (~S)") sym where))
 187
 188     (cons
 189      (string-append "@code{" name "} "
 190                     "(" typename ")"
 191                     (if handle
 192                         (string-append
 193                          ":\n\n"
 194                          (scm->texi (cdr handle))
 195                          "\n\n")
 196                         ""))
 197      desc)))
 198