Avoid `blabla: none' messages in internal documentation.

Make generated documentation even more pretty.

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index ef4e30d80fe120415a770d56866e35e41af9b430..6f9c02e4d81a8c3082e775e06be4a2d994e65c1a 100644 (file)
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -429,7 +429,7 @@ elements.  For example, the @code{Voice} context contains a
 
 For a full a description of each plug-in, see
 @ifhtml
-@internalsref{Engravers}.
+@internalsref{Engravers and Performers}.
 @end ifhtml
 @ifnothtml
 Internals Reference @expansion{} Translation @expansion{} Engravers.

diff --git a/scm/document-backend.scm b/scm/document-backend.scm
index d291b2299cdad34e1d307931fd1fb8d1712dec4a..02a09736b0927715bde6dfe74458599d14d300e8 100644 (file)
--- a/scm/document-backend.scm
+++ b/scm/document-backend.scm
@@ -1,7 +1,7 @@
 ;;;; backend-documentation-lib.scm -- Functions for backend documentation
 ;;;;
 ;;;; source file of the GNU LilyPond music typesetter
-;;;; 
+;;;;
 ;;;; (c) 2000--2007 Han-Wen Nienhuys <hanwen@xs4all.nl>
 ;;;; Jan Nieuwenhuizen <janneke@gnu.org>
 
@@ -53,19 +53,26 @@
 
 ;; First level Interface description
 (define (interface-doc interface)
-  (let ((name (symbol->string (car interface))))
+  (let* ((name (symbol->string (car interface)))
+        (interface-list (human-listify
+                         (map ref-ify
+                              (sort
+                               (map symbol->string
+                                    (hashq-ref iface->grob-table
+                                               (car interface)
+                                               '()))
+                               string<?)))))
     (make <texi-node>
       #:name name
       #:text (string-append
              (interface-doc-string (cdr interface) '())
              "\n\n"
-             "This grob interface is used in the following graphical objects: "
-             (human-listify
-              (map ref-ify
-                   (sort 
-                    (map symbol->string
-                         (hashq-ref iface->grob-table (car interface) '()))
-                    string<?)))
+             "This grob interface "
+             (if (equal? interface-list "none")
+                 "is not used in any graphical object"
+                 (string-append
+                  "is used in the following graphical object(s): "
+                  interface-list))
              "."))))
 
 (define (grob-alist->texi alist)
@@ -92,21 +99,32 @@ node."
                              (ly:error (_ "pair expected in doc ~s") name)))
                        (reverse ifaces)))
         (engravers (filter
-                    (lambda (x) (engraver-makes-grob? name x)) all-engravers-list))
+                    (lambda (x) (engraver-makes-grob? name x))
+                    all-engravers-list))
         (namestr (symbol->string name))
-        (engraver-names (map symbol->string (map ly:translator-name engravers))))
+        (engraver-names (map symbol->string
+                             (map ly:translator-name engravers)))
+        (engraver-list (human-listify
+                        (map ref-ify
+                             (map engraver-name engraver-names)))))
 
     (make <texi-node>
       #:name namestr
       #:text
       (string-append
-       namestr " objects are created by: "
-       (human-listify (map ref-ify
-                          (map engraver-name engraver-names)))
+       namestr " objects "
+       (if (equal? engraver-list "none")
+          "are not created by any engraver"
+          (string-append
+           "are created by: "
+           engraver-list))
+       "."
+
        "\n\nStandard settings: \n\n"
        (grob-alist->texi description)
-       "\n\nThis object supports the following interfaces: \n"
-       (human-listify ifacedoc)))))
+       "\n\nThis object supports the following interface(s): \n"
+       (human-listify ifacedoc)
+       "."))))
 
 (define (all-grobs-doc)
   (make <texi-node>

diff --git a/scm/document-music.scm b/scm/document-music.scm
index 927c91fd94b1252cecc4ac2fb9c542432252c995..e0c9106f49d0a3e8096bf3012cce5f32808226f9 100644 (file)
--- a/scm/document-music.scm
+++ b/scm/document-music.scm
@@ -1,7 +1,7 @@
 ;;;; document-markup.scm -- part of generated backend documentation
 ;;;;
 ;;;;  source file of the GNU LilyPond music typesetter
-;;;; 
+;;;;
 ;;;; (c) 1998--2007 Han-Wen Nienhuys <hanwen@xs4all.nl>
 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
 
@@ -22,13 +22,14 @@
              (let* ((class (ly:camel-case->lisp-identifier (car entry)))
                     (classes (ly:make-event-class class)))
                (if classes
-                   (map (lambda (cl)
-                          (hashq-set! music-types->names cl
-                                      (cons (car entry)
-                                            (hashq-ref music-types->names cl '()))))
-                        classes)
+                   (map
+                    (lambda (cl)
+                      (hashq-set! music-types->names cl
+                                  (cons (car entry)
+                                        (hashq-ref music-types->names cl '()))))
+                    classes)
                    #f)))
-           
+       
            music-descriptions)
 
 (define (strip-description x)
@@ -36,33 +37,39 @@
        ""))
 
 (define (music-type-doc entry)
-  (make <texi-node>
-    #:name  (symbol->string (car entry))
-    #:text 
-    (string-append
-     "\nMusic event type @code{"
-     (symbol->string (car entry))
-     "} is in music objects of type "
-     (human-listify
-      (sort
-       (map (lambda (x) (ref-ify (symbol->string x)))
-           (cdr entry)) string<?))
-     "."
+  (let* ((accept-list (human-listify
+                      (map ref-ify
+                           (map symbol->string
+                                (map ly:translator-name
+                                     (filter
+                                      (lambda (x)
+                                        (engraver-accepts-music-type? (car entry) x))
+                                      all-engravers-list)))))))
+    (make <texi-node>
+      #:name (symbol->string (car entry))
+      #:text
+      (string-append
+       "\nMusic event type @code{"
+       (symbol->string (car entry))
+       "} is in music objects of type "
+       (human-listify
+       (sort
+        (map (lambda (x) (ref-ify (symbol->string x)))
+             (cdr entry)) string<?))
+       "."
 
-     "\n\nAccepted by: "
-     (human-listify
-      (map ref-ify
-          (map symbol->string
-               (map ly:translator-name
-                    (filter
-                     (lambda (x) (engraver-accepts-music-type? (car entry) x)) all-engravers-list)))))
-     "."
-     "\n\n")))
+       "\n\n"
+       (if (equal? accept-list "none")
+          "Not accepted by any engraver or performer"
+          (string-append
+           "Accepted by: "
+           accept-list))
+       "."))))
 
 (define (music-types-doc)
   (make <texi-node>
     #:name "Music classes"
-    #:children 
+    #:children
     (map music-type-doc
         (sort
          (hash-table->alist music-types->names) alist<?))))
@@ -72,18 +79,29 @@
         (props (cdr obj))
         (class (ly:camel-case->lisp-identifier namesym))
         (classes (ly:make-event-class class))
+        (accept-list (if classes
+                         (human-listify
+                          (map ref-ify
+                               (map symbol->string
+                                    (map ly:translator-name
+                                         (filter
+                                          (lambda (x)
+                                            (engraver-accepts-music-types? classes x))
+                                          all-engravers-list)))))
+                         ""))
         (event-texi (if classes
                         (string-append
                          "\n\nEvent classes:\n"
-                         (human-listify (map ref-ify (map symbol->string classes)))
+                         (human-listify
+                          (map ref-ify (map symbol->string classes)))
                          "."
 
-                         "\n\nAccepted by: "
-                         (human-listify
-                          (map ref-ify
-                               (map symbol->string (map ly:translator-name
-                                                        (filter
-                                                         (lambda (x) (engraver-accepts-music-types? classes x)) all-engravers-list)))))
+                         "\n\n"
+                         (if (equal? accept-list "none")
+                             "Not accepted by any engraver or performer"
+                             (string-append
+                              "Accepted by: "
+                              accept-list))
                          ".")
                         "")))
 

diff --git a/scm/document-translation.scm b/scm/document-translation.scm
index 2c11e163d8985729b1401e699b6130ac9bc37800..01ae8a777f31dd1c46ce859cec2ee11ebd0bd4d1 100644 (file)
--- a/scm/document-translation.scm
+++ b/scm/document-translation.scm
@@ -1,7 +1,7 @@
 ;;;; document-translation.scm -- Functions for engraver documentation
 ;;;;
 ;;;; source file of the GNU LilyPond music typesetter
-;;;; 
+;;;;
 ;;;; (c) 2000--2007 Han-Wen Nienhuys <hanwen@xs4all.nl>
 ;;;;                 Jan Nieuwenhuizen <janneke@gnu.org>
 
@@ -21,7 +21,7 @@
 (define (engraver-doc-string engraver in-which-contexts)
   (let* ((propsr (cdr (assoc 'properties-read (ly:translator-description engraver))))
         (propsw (cdr (assoc 'properties-written (ly:translator-description engraver))))
-        (accepted  (cdr (assoc 'events-accepted (ly:translator-description engraver)))) 
+        (accepted  (cdr (assoc 'events-accepted (ly:translator-description engraver))))
         (name-sym  (ly:translator-name engraver))
         (name-str (symbol->string name-sym))
         (desc (cdr (assoc 'description (ly:translator-description engraver))))
@@ -48,18 +48,18 @@
           (map (lambda (x) (property->texi 'translation x '())) propsr)
           #t))
         "")
-     
+
      (if (null? propsw)
         ""
         (string-append
-         "Properties (write)" 
+         "Properties (write)"
          (description-list->texi
           (map (lambda (x) (property->texi 'translation x '())) propsw)
           #t)))
      (if  (null? grobs)
          ""
          (string-append
-          "\n\nThis engraver creates the following layout objects:\n\n"
+          "\n\nThis engraver creates the following layout object(s):\n\n"
           (human-listify (map ref-ify (uniq-list (sort grobs string<?))))
           "."))
 
@@ -82,12 +82,19 @@
                             (if (member name-sym consists)
                                 (list context)
                                 '())))
-                        context-description-alist))))
+                        context-description-alist)))
+               (context-list (human-listify (map ref-ify
+                                                 (sort
+                                                  (map symbol->string contexts)
+                                                  string<?)))))
           (string-append
-           "@code{" name-str "} is part of contexts: "
-           (human-listify (map ref-ify
-                               (sort
-                                (map symbol->string contexts) string<?)))))
+           "@code{" name-str "} "
+           (if (equal? context-list "none")
+               "is not part of any context"
+               (string-append
+                "is part of the following context(s): "
+                context-list))
+           "."))
         ""))))
 
 ;; First level Engraver description
@@ -104,12 +111,12 @@
  (ly:get-all-translators))
 
 (define (find-engraver-by-name name)
-  "NAME is a symbol." 
+  "NAME is a symbol."
   (hash-ref name->engraver-table name #f))
 
 (define (document-engraver-by-name name)
   "NAME is a symbol."
-  
+
   (let* ((eg (find-engraver-by-name name)))
 
     (cons (string-append "@code{" (ref-ify (symbol->string name)) "}")
@@ -140,7 +147,7 @@
              context-sym
              (scm->texi (car args))))
      )))
-     
+
 
 (define (context-doc context-desc)
   (let* ((name-sym (cdr (assoc 'context-name context-desc)))
@@ -149,7 +156,7 @@
         (desc-handle (assoc 'description context-desc))
         (desc (if (and  (pair? desc-handle) (string? (cdr desc-handle)))
                   (cdr desc-handle) "(not documented)"))
-        
+       
         (accepts (cdr (assoc 'accepts context-desc)))
         (consists (cdr (assoc 'consists context-desc)))
         (props (cdr (assoc 'property-ops context-desc)))
@@ -159,7 +166,7 @@
     (make <texi-node>
       #:name name
       #:text
-      (string-append 
+      (string-append
        desc
        (if (pair? aliases)
           (string-append
@@ -168,7 +175,7 @@
            ".")
           "")
 
-       "\n\nThis context creates the following layout objects:\n\n"
+       "\n\nThis context creates the following layout object(s):\n\n"
        (human-listify (uniq-list (sort grob-refs string<?)))
        "."
 
@@ -183,7 +190,7 @@
                  str
                  "@end itemize\n")))
           "")
-       
+
        (if (null? accepts)
           "\n\nThis context is a `bottom' context; it cannot contain other contexts."
           (string-append
@@ -192,11 +199,11 @@
            " can contain\n"
            (human-listify (map ref-ify (map symbol->string accepts)))
            "."))
-       
+
        (if (null? consists)
           ""
           (string-append
-           "\n\nThis context is built from the following engravers:"
+           "\n\nThis context is built from the following engraver(s):"
            (description-list->texi
             (map document-engraver-by-name consists)
             #t)))))))
@@ -241,8 +248,8 @@
 
 (define (all-engravers-doc)
   (make <texi-node>
-    #:name "Engravers"
-    #:desc "All separate engravers."
+    #:name "Engravers and Performers"
+    #:desc "All separate engravers and performers."
     #:text "See @ruser{Modifying context plug-ins}."
     #:children
     (map engraver-doc all-engravers-list)))