Improve formatting of internal documentation.

o Add `quote' argument to `description-list->texi' to control insertion of
  `@quotation ... @end quotation'.  Update all callers appropriately.

o Sort table of identifiers.

diff --git a/scm/document-backend.scm b/scm/document-backend.scm
index 610f7c094a44ea30ec566c9aa623ee8c4af94af2..d291b2299cdad34e1d307931fd1fb8d1712dec4a 100644 (file)
--- a/scm/document-backend.scm
+++ b/scm/document-backend.scm
@@ -26,13 +26,13 @@
      (if (pair? uprops)
         (string-append
          "\n\n@unnumberedsubsubsec User settable properties:\n"
-         (description-list->texi user-propdocs))
+         (description-list->texi user-propdocs #t))
         "")
 
      (if (pair? iprops)
         (string-append
          "\n\n@unnumberedsubsubsec Internal properties:\n"
-         (description-list->texi internal-propdocs))
+         (description-list->texi internal-propdocs #t))
         ""))))
 
 (define iface->grob-table (make-vector 61 '()))
@@ -74,7 +74,8 @@
 
     (description-list->texi
      (map (lambda (y) (property->texi 'backend y alist))
-         uprops))))
+         uprops)
+     #t)))
 
 (define (grob-doc description)
   "Given a property alist DESCRIPTION, make a documentation
@@ -155,7 +156,7 @@ node."
   (let* ((ps (sort (map symbol->string lst) string<?))
         (descs (map (lambda (prop)
                       (property->texi 'backend (string->symbol prop) '())) ps))
-        (texi (description-list->texi descs)))
+        (texi (description-list->texi descs #f)))
     texi))
 
 ;;(dump-node (grob-doc (cdadr all-grob-descriptions)) (current-output-port) 0 )

diff --git a/scm/document-identifiers.scm b/scm/document-identifiers.scm
index 736da249048bbc223512a54845aacb83757a0100..67e282bd862cd594beb8c26680ac25d0697021a2 100644 (file)
--- a/scm/document-identifiers.scm
+++ b/scm/document-identifiers.scm
@@ -1,12 +1,11 @@
 ;;
 ;; document-identifiers.scm -- implement documentation
 ;; of identifiers from .ly file.
-;; 
+;;
 ;; source file of the GNU LilyPond music typesetter
-;; 
+;;
 ;; (c) 2006 Han-Wen Nienhuys <hanwen@lilypond.org>
-;; 
-
+;;
 
 (use-modules (ice-9 format))
 
@@ -16,51 +15,54 @@
        (music-func (cdr music-func-pair))
        (func (ly:music-function-extract music-func))
        (arg-names
-       (map symbol->string 
+       (map symbol->string
             (cddr (cadr (procedure-source func)))))
        (doc (procedure-documentation func))
        (sign (object-property func 'music-function-signature))
        (type-names (map type-name sign))
 
-       ;; C&P
-       (signature (zip arg-names arg-names type-names))
        (signature-str
-         (string-join
-          (map (lambda (x) (format "@var{~a} (~a)"
-                                   (car x)
-                                   (cadr x)))
-                                   
-               (zip arg-names type-names)))))
-
+       (string-join
+        (map (lambda (x) (format "@var{~a} (~a)"
+                                 (car x)
+                                 (cadr x)))
+             (zip arg-names type-names)))))
     (format
-     
-     "\n
-@item @code{~a} - ~a\n
+     "@item @code{~a}~a~a
 @findex ~a
-
-~a\n\n"
-
-     name-sym signature-str
+~a
+"
+     name-sym (if (equal? "" signature-str) "" " - ") signature-str
      name-sym
      (if doc doc "(undocumented; fixme)"))))
 
 
-
 (define (document-object obj-pair)
   (cond
-   ((ly:music-function? (cdr obj-pair)) (document-music-function obj-pair))
+   ((ly:music-function? (cdr obj-pair))
+    (document-music-function obj-pair))
    (else
     #f)))
 
+
+(define (identifier<? a b)
+  (string<?
+   (symbol->string (car a))
+   (symbol->string (car b))))
+
+
 (define-public (identifiers-doc-string)
   (format
    "@table @asis
 ~a
 @end table
 "
-  (string-join
-   (filter
-    identity
-   (map
-    document-object
-    (ly:module->alist (current-module)))))))
+   (string-join
+    (filter
+     identity
+     (map
+      document-object
+      (sort
+       (ly:module->alist (current-module))
+       identifier<?)))
+    "")))

diff --git a/scm/document-music.scm b/scm/document-music.scm
index 4c12b6b1e9a9e39621f688760bec1b315f55ec5a..927c91fd94b1252cecc4ac2fb9c542432252c995 100644 (file)
--- a/scm/document-music.scm
+++ b/scm/document-music.scm
@@ -14,7 +14,7 @@
           (descs (map (lambda (prop)
                         (property->texi 'music (string->symbol prop)))
                       ps))
-          (texi (description-list->texi descs)))
+          (texi (description-list->texi descs #f)))
       texi)))
 
 (define music-types->names (make-vector 61 '()))
@@ -94,7 +94,8 @@
      (description-list->texi
       (map
        (lambda (x) (property->texi 'music x props))
-       (map car props))))))
+       (map car props))
+      #t))))
 
 (define (music-object-doc obj)
   (make <texi-node>

diff --git a/scm/document-translation.scm b/scm/document-translation.scm
index 38b74e25d89b99ec4b5e1b2115094ce28a73134b..2c11e163d8985729b1401e699b6130ac9bc37800 100644 (file)
--- a/scm/document-translation.scm
+++ b/scm/document-translation.scm
@@ -45,7 +45,8 @@
         (string-append
          "Properties (read)"
          (description-list->texi
-          (map (lambda (x) (property->texi 'translation x '())) propsr)))
+          (map (lambda (x) (property->texi 'translation x '())) propsr)
+          #t))
         "")
      
      (if (null? propsw)
@@ -53,7 +54,8 @@
         (string-append
          "Properties (write)" 
          (description-list->texi
-          (map (lambda (x) (property->texi 'translation x '())) propsw))))
+          (map (lambda (x) (property->texi 'translation x '())) propsw)
+          #t)))
      (if  (null? grobs)
          ""
          (string-append
@@ -195,7 +197,9 @@
           ""
           (string-append
            "\n\nThis context is built from the following engravers:"
-           (description-list->texi (map document-engraver-by-name consists))))))))
+           (description-list->texi
+            (map document-engraver-by-name consists)
+            #t)))))))
 
 (define (engraver-grobs grav)
   (let* ((eg (if (symbol? grav)
@@ -250,7 +254,7 @@
          (map
           (lambda (x) (property->texi 'translation  x '()))
           sortedsyms))
-        (texi (description-list->texi propdescs)))
+        (texi (description-list->texi propdescs #f)))
     texi))
 
 (define (translation-doc-node)

diff --git a/scm/documentation-lib.scm b/scm/documentation-lib.scm
index 5239ce78912fec620d955a0936c96560537bde4b..2576dd223ba448a6fbfec597608eba2bf682ea9c 100644 (file)
--- a/scm/documentation-lib.scm
+++ b/scm/documentation-lib.scm
@@ -66,25 +66,22 @@
                      (5 . "@unnumberedsubsubsec")))))
 
 (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))))
 
 
-(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)."
   (string-append
    "\n"
-   "@quotation\n"
+   (if quote? "@quotation\n" "")
    "@table @asis\n"
    (apply string-append (map one-item->texi items-alist))
    "\n"
    "@end table\n"
-   "@end quotation\n"))
+   (if quote? "@end quotation\n" "")))
 
 (define (texi-menu items-alist)
   "Generate what is between @menu and @end menu."
@@ -106,7 +103,8 @@
      "\n@ignore\n"
      "\n@ifhtml\n"
      (description-list->texi (map (lambda (x) (cons (ref-ify (car x)) (cdr x)))
-                                 items-alist))
+                                 items-alist)
+                            #t)
      "\n@end ifhtml\n"
      "\n@end ignore\n")))