X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=scm%2Fdocumentation-lib.scm;h=24d94215fa19c00ae70b3e5fa808f79aad2d9ed2;hb=af23c513b356d3fbb8dfa2c53c031e134f2c7dac;hp=047dc03fdcb9f2305ce29a6e0873568ef0a3c8ba;hpb=e01d440915be7b23b804d5886d685ba91617edf0;p=lilypond.git

diff --git a/scm/documentation-lib.scm b/scm/documentation-lib.scm
index 047dc03fdc..24d94215fa 100644
--- a/scm/documentation-lib.scm
+++ b/scm/documentation-lib.scm
@@ -1,136 +1,137 @@
-;;;
-;;; documentation-lib.scm -- Assorted Functions for generated documentation
-;;;
-;;; source file of the GNU LilyPond music typesetter
-;;; 
-;;; (c) 2000 Han-Wen Nienhuys <hanwen@cs.uu.nl>
-;;; Jan Nieuwenhuizen <janneke@gnu.org>
-
-(define (uniqued-alist  alist acc)
-  (if (null? alist) acc
-      (if (assoc (caar alist) acc)
-	  (uniqued-alist (cdr alist) acc)
-	  (uniqued-alist (cdr alist) (cons (car alist) acc)
-  ))))
-
-
-(define (alist<? x y)
-  (string<? (symbol->string (car x))
-	    (symbol->string (car y))))
+;;;;
+;;;; documentation-lib.scm -- Assorted Functions for generated documentation
+;;;;
+;;;; source file of the GNU LilyPond music typesetter
+;;;; 
+;;;; (c) 2000--2007 Han-Wen Nienhuys <hanwen@xs4all.nl>
+;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
+
+(use-modules (oop goops)
+	     (srfi srfi-13)
+	     (srfi srfi-1))
+
+(define-class <texi-node> ()
+  (children #:init-value '() #:accessor node-children #:init-keyword #:children)
+  (text #:init-value "" #:accessor node-text #:init-keyword #:text)
+  (name #:init-value "" #:accessor node-name #:init-keyword #:name)
+  (description #:init-value "" #:accessor node-desc #:init-keyword #:desc))
+
+(define (menu-entry x)
+  (cons
+   (node-name x)
+   (node-desc x)))
+
+(define* (dump-node node port level #:optional (appendix #f))
+  (display
+   (string-append
+    "\n@node "
+    (node-name node)
+    "\n\n"
+    (if appendix
+        (texi-appendix-section-command level)
+        (texi-section-command level))
+    " "
+    (node-name node)
+    "\n\n"
+    (node-text node)
+    "\n\n"
+    (if (pair? (node-children node))
+	(texi-menu
+	 (map (lambda (x) (menu-entry x))
+	      (node-children node)))
+	""))
+   port)
+  (map (lambda (x) (dump-node x port (+ 1 level) appendix))
+       (node-children node)))
 
 (define (processing name)
-  (display (string-append "\nProcessing " name " ... ") (current-error-port)))
+  (ly:message (_ "Processing ~S...") name))
 
 (define (self-evaluating? x)
   (or (number? x) (string? x) (procedure? x) (boolean? x)))
 
 (define (texify x)
   x)
-;;  (let*
-;;     ((x1 (regexp-substitute/global #f "\([^@]\){" x 'pre "\1@{" 'post))
-;;      ((x2 (regexp-substitute/global #f "\([^@]\){" x 'pre "\1@{" 'post))
-;;      ((x3 (regexp-substitute/global #f "\([^@]\)@" x 'pre "\1@@" 'post))
-;;       )
-;;    x2))
-
-
 
 (define (scm->texi x)
-  (string-append "@code{" (texify (scm->string x)) "}")
-  )
+  (string-append "@code{" (texify (scm->string x)) "}"))
 
-(define (scm->string val)
-  (string-append
-   (if (self-evaluating? val) "" "'")
-   (call-with-output-string (lambda (port) (display val port)))
-  ))
 
-(define (node name)
-  (string-append
-   "\n@html"
-   "\n<hr>"
-   "\n@end html"
-   "\n@node " name))
-
-(define texi-section-alist
-  '(
-    ;; Hmm, texinfo doesn't have ``part''
-    (0 . "@top")
-    (1 . "@unnumbered")
-    (2 . "@unnumberedsec")
-    (3 . "@unnumberedsubsec")
-    (4 . "@unnumberedsubsubsec")
-    (5 . "@unnumberedsubsubsec")
-    ))
-    
-(define (texi-section level name ref)
-  "texi sectioning command (lower LEVEL means more significant).
-Add a ref if REF is set
-"
-     
-  (string-append
-   "\n" (cdr (assoc level texi-section-alist)) " "
-   (if ref
-       (ref-ify name)
-       name)
-   "\n"))
 
+(define (texi-section-command level)
+  (cdr (assoc level '(
+		      ;; Hmm, texinfo doesn't have ``part''
+		      (0 . "@top")
+		      (1 . "@unnumbered")
+		      (2 . "@unnumberedsec")
+		      (3 . "@unnumberedsubsec")
+		      (4 . "@unnumberedsubsubsec")
+		      (5 . "@unnumberedsubsubsec")))))
+
+(define (texi-appendix-section-command level)
+  (cdr (assoc level '((0 . "@top")
+		      (1 . "@appendix")
+		      (2 . "@appendixsec")
+		      (3 . "@appendixsubsec")
+		      (4 . "@appendixsubsubsec")
+		      (5 . "@appendixsubsubsec")))))
 
 (define (one-item->texi label-desc-pair)
-  "Document one (LABEL . DESC); return empty string if LABEL is empty string. 
-"
+  "Document one (LABEL . DESC); return empty string if LABEL is empty string."
   (if (eq? (car label-desc-pair) "")
       ""
-      (string-append "\n@item " (car label-desc-pair) "\n" (cdr label-desc-pair))
-  ))
+      (string-append "\n@item " (car label-desc-pair) "\n" (cdr label-desc-pair))))
 
 
-(define (description-list->texi items-alist)
-  "Document ITEMS-ALIST in a table. entries contain (item-label . string-to-use)
-"
+(define (description-list->texi items-alist quote?)
+  "Document ITEMS-ALIST in a table; entries contain (item-label .
+string-to-use).  If QUOTE? is #t, embed table in a @quotation environment."
   (string-append
-   "\n@table @samp\n"
+   "\n"
+   (if quote? "@quotation\n" "")
+   "@table @asis\n"
    (apply string-append (map one-item->texi items-alist))
-   "\n@end table\n"))
+   "\n"
+   "@end table\n"
+   (if quote? "@end quotation\n" "")))
 
 (define (texi-menu items-alist)
-  (string-append
-  "\n@menu"
-  (apply string-append
-	 (map (lambda (x) (string-append "\n* " (car x) ":: " (cdr x)))
-	      items-alist))
-  "\n@end menu\n"
-  ;; Menus don't appear in html, so we make a list ourselves
-  "\n@ignore\n"
-  "\n@ifhtml\n"
-  (description-list->texi (map (lambda (x) (cons (ref-ify (car x)) (cdr x)))
-			 items-alist))
-  "\n@end ifhtml\n"
-  "\n@end ignore\n"))
-
-  
-(define (texi-node-menu name items-alist)
-  (string-append
-   (node name)
-   (texi-section 1 name #f)
-   (texi-menu items-alist)))
-
-(define (texi-file-head name file-name top items-alist)
+  "Generate what is between @menu and @end menu."
+  (let ((maxwid
+	 (apply max (map (lambda (x) (string-length (car x))) items-alist))))
+    
+    (string-append
+     "\n@menu"
+     (apply string-append
+	    (map (lambda (x)
+		   (string-append
+		    (string-pad-right 
+		     (string-append "\n* " (car x) ":: ")
+		     (+ maxwid 8))
+		    (cdr x)))
+		 items-alist))
+     "\n@end menu\n"
+     ;; Menus don't appear in html, so we make a list ourselves
+     "\n@ignore\n"
+     "\n@ifhtml\n"
+     (description-list->texi (map (lambda (x) (cons (ref-ify (car x)) (cdr x)))
+				  items-alist)
+			     #t)
+     "\n@end ifhtml\n"
+     "\n@end ignore\n")))
+
+(define (texi-file-head name file-name top)
   (string-append
    "\\input texinfo @c -*-texinfo-*-"
    "\n@setfilename " file-name ".info"
    "\n@settitle " name
-   "\n@dircategory GNU music project"
+   "\n@dircategory LilyPond"
    "\n@direntry"
    ;; prepend GNU for dir, must be unique
-   "\n* GNU " name " (" file-name ").           " name "."
-   "\n@end direntry"
-   (node "Top") ",(lilypond)Index,(lilypond)Development," top
-   "\n@top"
-   (texi-section 1 name #f)
-   (texi-menu items-alist)
-   "\n@contents"
-   ))
+   "\n* GNU " name ": (" file-name ").          " name "."
+   "\n@end direntry\n"
+   "@documentlanguage en\n"
+   "@documentencoding utf-8\n"))
 
 (define (context-name name)
   name)
@@ -139,21 +140,59 @@ Add a ref if REF is set
   name)
 
 (define (grob-name name)
-  name)
+  (if (symbol? name)
+      (symbol->string name)
+      name))
 
 (define (interface-name name)
   name)
 
 (define (ref-ify x)
+  "Add ref to X"
   (string-append "@ref{" x "}"))
 
-(define (human-listify l)
+(define (human-listify lst)
+  "Produce a textual enumeration from LST, a list of strings"
+  
   (cond
-   ((null? l) "none")
-   ((null? (cdr l)) (car l))
-   ((null? (cddr l)) (string-append (car l) " and " (cadr l)))
-   (else (string-append (car l) ", " (human-listify (cdr l))))
-   ))
+   ((null? lst) "none")
+   ((null? (cdr lst)) (car lst))
+   ((null? (cddr lst)) (string-append (car lst) " and " (cadr lst)))
+   (else (string-append (car lst) ", " (human-listify (cdr lst))))))
 
 (define (writing-wip x)
-  (display (string-append "\nWriting " x " ... ") (current-error-port)))
+  (ly:message (_ "Writing ~S...") x))
+
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; property  stuff.
+
+(define (property->texi where sym . rest)
+  "Document SYM for WHERE (which can be translation, backend, music),
+with init values from ALIST (1st optional argument)
+"
+  (let* ((name (symbol->string sym))
+	 (alist (if (pair? rest) (car rest) '()))
+	 (type?-name (string->symbol
+		      (string-append (symbol->string where) "-type?")))
+	 (doc-name (string->symbol		    
+		    (string-append (symbol->string where) "-doc")))
+	 (type (object-property sym type?-name))
+	 (typename (type-name type))
+	 (desc (object-property sym doc-name))
+	 (handle (assoc sym alist)))
+
+    (if (eq? desc #f)
+	(ly:error (_ "cannot find description for property ~S (~S)") sym where))
+    
+    (cons
+     (string-append "@code{" name "} "
+		    "(" typename ")"
+		    (if handle
+			(string-append
+			 ":\n\n"
+			 (scm->texi (cdr handle))
+			 "\n\n")
+			""))
+     desc)))
+