From a010a8e33a55d7b7c592804a2a30c90a33c9884d Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Tue, 18 Mar 2008 21:25:20 +0100 Subject: [PATCH] Avoid `blabla: none' messages in internal documentation. Make generated documentation even more pretty. --- Documentation/user/changing-defaults.itely | 2 +- scm/document-backend.scm | 50 ++++++++---- scm/document-music.scm | 90 +++++++++++++--------- scm/document-translation.scm | 49 +++++++----- 4 files changed, 117 insertions(+), 74 deletions(-) diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely index ef4e30d80f..6f9c02e4d8 100644 --- 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 d291b2299c..02a09736b0 100644 --- 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 ;;;; Jan Nieuwenhuizen @@ -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 #: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) '())) - stringtexi 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 #: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 diff --git a/scm/document-music.scm b/scm/document-music.scm index 927c91fd94..e0c9106f49 100644 --- 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 ;;;; Jan Nieuwenhuizen @@ -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 - #: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)) stringstring + (map ly:translator-name + (filter + (lambda (x) + (engraver-accepts-music-type? (car entry) x)) + all-engravers-list))))))) + (make + #: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)) stringstring - (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 #:name "Music classes" - #:children + #:children (map music-type-doc (sort (hash-table->alist music-types->names) alistlisp-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 2c11e163d8..01ae8a777f 100644 --- 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 ;;;; Jan Nieuwenhuizen @@ -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 stringstring contexts) + stringstring contexts) stringengraver-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 #: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 stringstring 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 - #: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))) -- 2.39.2