From 3f43309ace290fc86c4fafb4e2841028d04e2c4e Mon Sep 17 00:00:00 2001 From: Werner Lemberg Date: Tue, 18 Mar 2008 16:19:46 +0100 Subject: [PATCH] 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. --- scm/document-backend.scm | 9 +++--- scm/document-identifiers.scm | 60 +++++++++++++++++++----------------- scm/document-music.scm | 5 +-- scm/document-translation.scm | 12 +++++--- scm/documentation-lib.scm | 16 +++++----- 5 files changed, 54 insertions(+), 48 deletions(-) diff --git a/scm/document-backend.scm b/scm/document-backend.scm index 610f7c094a..d291b2299c 100644 --- 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) stringtexi '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 736da24904..67e282bd86 100644 --- 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 -;; - +;; (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 (identifierstring (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)) + identifiertexi '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 diff --git a/scm/document-translation.scm b/scm/document-translation.scm index 38b74e25d8..2c11e163d8 100644 --- 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 5239ce7891..2576dd223b 100644 --- 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"))) -- 2.39.5