From: Han-Wen Nienhuys Date: Mon, 21 Apr 2003 00:26:26 +0000 (+0000) Subject: * Documentation/user/GNUmakefile X-Git-Tag: release/1.7.17~3 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=2086beff8cd9949318c97a2a531edb8f04f45f8c;p=lilypond.git * Documentation/user/GNUmakefile ($(outdir)/lilypond-internals/lilypond-internals.html): copy ly files too. * scm/document-markup.scm: new file: document all markup functions. * scm/documentation-generate.scm: rename all documentation modules to document-*.scm * scripts/lilypond-book.py: generate link to .ly file iso. link to .png --- diff --git a/ChangeLog b/ChangeLog index de76c2ad0c..ee2eadd181 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,18 @@ 2003-04-21 Han-Wen Nienhuys + * Documentation/user/GNUmakefile + ($(outdir)/lilypond-internals/lilypond-internals.html): copy ly + files too. + + * scm/document-markup.scm: new file: document all markup + functions. + + * scm/documentation-generate.scm: rename all documentation modules + to document-*.scm + + * scripts/lilypond-book.py: generate link to .ly file iso. link to + .png + * input/test/divisiones.ly: added * input/regression/output-property.ly: new file diff --git a/Documentation/user/GNUmakefile b/Documentation/user/GNUmakefile index bb78b9dbf2..f0b566c5ff 100644 --- a/Documentation/user/GNUmakefile +++ b/Documentation/user/GNUmakefile @@ -64,14 +64,14 @@ extra-local-help: $(outdir)/lilypond/lilypond.html: $(outdir)/lilypond.texi mkdir -p $(dir $@) $(MAKEINFO) --output=$@ --html $< - -cp -f $(outdir)/*.png $(outdir)/lilypond + -cp -f $(outdir)/*.{png,ly} $(outdir)/lilypond -cp -f $(outdir)/lilypond/index.html $@ $(deep-footify) $(shell find $(outdir)/$(*F)/*.html) $(outdir)/lilypond-internals/lilypond-internals.html: $(outdir)/lilypond-internals.texi mkdir -p $(dir $@) $(MAKEINFO) --output=$@ --html $< - -cp -f $(outdir)/*.png $(outdir)/lilypond-internals + -cp -f $(outdir)/*.{png,ly} $(outdir)/lilypond-internals -cp -f $(outdir)/lilypond-internals/index.html $@ $(deep-footify) $(shell find $(outdir)/$(*F)/*.html) diff --git a/Documentation/user/macros.itexi b/Documentation/user/macros.itexi index eef33e29cc..85fd263d68 100644 --- a/Documentation/user/macros.itexi +++ b/Documentation/user/macros.itexi @@ -134,6 +134,8 @@ internals document, @internalsref{\NAME\} @macro refbugs @strong{BUGS} + + @end macro @macro seealso diff --git a/Documentation/user/refman.itely b/Documentation/user/refman.itely index 455ed4dfb6..4ecdcefc55 100644 --- a/Documentation/user/refman.itely +++ b/Documentation/user/refman.itely @@ -151,6 +151,11 @@ octave; each @code{,} lowers the pitch by an octave. c' c'' es' g' as' gisis' ais' @end lilypond + +@seealso + +@internalsref{NoteEvent}, @internalsref{NoteHead} + @node Chromatic alterations @subsection Chromatic alterations @@ -196,6 +201,7 @@ keyword appended. Rest collision testing will leave these rests alone. a'4\rest d'4\rest @end lilypond +@internalsref{RestEvent}, @internalsref{Rest} @c FIXME: naming. @@ -228,6 +234,9 @@ which will work outside of those two modes: The skip command is merely an empty musical placeholder. It does not produce any output, not even transparent output. +@seealso + +@internalsref{SkipEvent} @@ -369,8 +378,8 @@ give optimal results. @c FIXME: This subsection does not belong in @ref{Note entry}. LilyPond can automatically converting long notes to tied notes. This -is done by replacing the @code{Note_heads_engraver} by the -@code{Completion_heads_engraver}. +is done by replacing the @internalsref{Note_heads_engraver} by the +@internalsref{Completion_heads_engraver}. @lilypond[verbatim,noindent] \score{ @@ -3118,7 +3127,7 @@ print them as name. @menu * Chords mode:: -* Printing chord names:: +* Printing chord names:: @end menu @@ -4425,7 +4434,7 @@ The following example (from @inputfileref{input/regression,cluster.ly}) shows what the result looks like. -@lilypondfile{cluster.ly} +@lilypondfile[notexidoc]{cluster.ly} By default, @internalsref{Cluster_engraver} is in the @internalsref{Voice} context. This allows putting ordinary notes and @@ -4487,7 +4496,6 @@ music notation, are supported See @ref{Articulations} for general instructions how to apply scripts such as fermatas to a @code{\notes@{@}} block. - @node Tuning output @section Tuning output @@ -4508,8 +4516,9 @@ affecting a whole set of objects. Second, you can select one specific object, and set a object property in that object. @menu -* Tuning groups of objects :: * Tuning per object :: +* Tuning objects :: +* Outputproperty:: * Font selection:: * Text markup:: @end menu @@ -4676,7 +4685,7 @@ LilyPond may crash. @node Outputproperty - +@subsection Outputproperty @cindex \outputproperty @@ -4983,14 +4992,10 @@ their center lines. c1^\markup { \line << a b c >> } @end lilypond - - The markup mechanism is very flexible and extensible. Refer to @file{scm/new-markup.scm} for more information on extending the markup mode. -[TODO: generate markup doco automatically.] - @cindex metronome mark One practical application of complicated markup is to fake a metronome @@ -5012,6 +5017,10 @@ eighthNote = \markup } @end lilypond +@seealso + +@internalsref{Markup functions}, @file{scm/new-markup.scm} + @refbugs @cindex kerning @@ -5190,6 +5199,12 @@ must be overriden from the @code{\paper} block, e.g. @end example +@seealso + +@internalsref{SpacingSpanner}, @internalsref{NoteSpacing}, +@internalsref{StaffSpacing}, @internalsref{SeparationItem}, +@internalsref{SeparatingGroupSpanner}. + @refbugs Spacing is determined on a score wide basis. If you have a score that @@ -5215,6 +5230,7 @@ kneed stems. + @node Font Size @subsection Font size @cindex font size, setting @@ -5274,6 +5290,11 @@ If you want linebreaks at regular intervals, you can use the following: This makes the following 28 measures (assuming 4/4 time) be broken every 4 measures. +@seealso + +@internalsref{BreakEvent} + + @node Page layout @subsection Page layout diff --git a/ly/generate-documentation.ly b/ly/generate-documentation.ly index 2666360e23..5e0da04748 100644 --- a/ly/generate-documentation.ly +++ b/ly/generate-documentation.ly @@ -4,4 +4,4 @@ % Running LilyPond on this file generates the documentation % #(ly:set-option 'parse-protect #f) -#(load-from-path "generate-documentation.scm") +#(load-from-path "documentation-generate.scm") diff --git a/scm/backend-documentation-lib.scm b/scm/backend-documentation-lib.scm deleted file mode 100644 index 20a24dcc15..0000000000 --- a/scm/backend-documentation-lib.scm +++ /dev/null @@ -1,206 +0,0 @@ -;;; backend-documentation-lib.scm -- Functions for backend documentation -;;; -;;; source file of the GNU LilyPond music typesetter -;;; -;;; (c) 2000--2002 Han-Wen Nienhuys -;;; Jan Nieuwenhuizen - - -;;; This file generates documentation for the backend of lilypond. - -;; alist of property descriptions - -;; -" -TODO: - - -Grob bla - -Created by: - - * preset properties + explanation - -Interfaces: - - * properties available. - -" - - -(define (interface-doc-string interface grob-description) - (let* - ( - (name (car interface)) - (desc (cadr interface)) - (props (sort (caddr interface) symboltexi propdocs)) - - )) - - -(define iface->grob-table (make-vector 61 '())) -;; extract ifaces, and put grob into the hash table. -(map - (lambda (x) - (let* - ( - (metah (assoc 'meta (cdr x))) - (meta (cdr metah)) - (ifaces (cdr (assoc 'interfaces meta))) - ) - - (map (lambda (iface) - (hashq-set! - iface->grob-table iface - (cons (car x) - (hashq-ref iface->grob-table iface '()) - ))) - ifaces) - )) - all-grob-descriptions) - -;; First level Interface description -(define (interface-doc interface) - (let ((name (symbol->string (car interface)))) - (make - #:name name - #:text (string-append - (interface-doc-string (cdr interface) #f) - "\n\n" - "This grob interface is used in the following graphical objects: " - - (human-listify - (map ref-ify - (map symbol->string - (hashq-ref iface->grob-table (car interface) '() ))))) - - ))) - -(define (grob-doc description) - "Given a property alist DESCRIPTION, make a documentation -node." - - (let* - ( - (metah (assoc 'meta description)) - - (meta (cdr metah)) - (name (cdr (assoc 'name meta))) - (ifaces (map lookup-interface (cdr (assoc 'interfaces meta)))) - (ifacedoc (map (lambda (iface) - (string-append -"@html -
-@end html - -@subsubheading " -(ref-ify (symbol->string (car iface))) - -"\n\n" - (interface-doc-string iface description))) - (reverse ifaces))) - (engravers (filter-list - (lambda (x) (engraver-makes-grob? name x)) all-engravers-list)) - (namestr (symbol->string name)) - (engraver-names (map ly:translator-name engravers)) - ) - - (make - #:name namestr - #:text - (string-append - namestr " grobs are created by: " - (human-listify (map ref-ify - (map engraver-name engraver-names))) - (apply string-append ifacedoc) - )) - )) - -(define (all-grobs-doc) - (make - #:name "All Graphical objects" - #:desc "Description and defaults for all Grobs" - #:children - (map (lambda (x) (grob-doc (cdr x))) all-grob-descriptions))) - -(define interface-description-alist - (hash-fold - (lambda (key val prior) - (cons (cons key val) prior) - ) - '() (ly:all-grob-interfaces))) - -(set! interface-description-alist (sort interface-description-alist alist - #:name "Graphical Object Interfaces" - #:desc "Building blocks of graphical objects" - #:children - (map interface-doc interface-description-alist) - )) - -(define (all-backend-properties-doc) - (let* - ( - (ps (sort (map symbol->string all-backend-properties) stringsymbol prop) 'backend #f)) - ps)) - (texi (description-list->texi descs)) - ) - (make - #:name "backend properties" - #:desc "all the properties in use as grob properties" - #:text texi) - )) - -;(dump-node (grob-doc (cdadr all-grob-descriptions)) (current-output-port) 0 ) -(define (backend-doc-node) - (make - #:name "Backend" - #:desc "Reference for the layout engine" - #:children - (list - (all-grobs-doc) - (all-interfaces-doc) - (all-backend-properties-doc) - ) - )) diff --git a/scm/document-backend.scm b/scm/document-backend.scm new file mode 100644 index 0000000000..20a24dcc15 --- /dev/null +++ b/scm/document-backend.scm @@ -0,0 +1,206 @@ +;;; backend-documentation-lib.scm -- Functions for backend documentation +;;; +;;; source file of the GNU LilyPond music typesetter +;;; +;;; (c) 2000--2002 Han-Wen Nienhuys +;;; Jan Nieuwenhuizen + + +;;; This file generates documentation for the backend of lilypond. + +;; alist of property descriptions + +;; +" +TODO: + + +Grob bla + +Created by: + + * preset properties + explanation + +Interfaces: + + * properties available. + +" + + +(define (interface-doc-string interface grob-description) + (let* + ( + (name (car interface)) + (desc (cadr interface)) + (props (sort (caddr interface) symboltexi propdocs)) + + )) + + +(define iface->grob-table (make-vector 61 '())) +;; extract ifaces, and put grob into the hash table. +(map + (lambda (x) + (let* + ( + (metah (assoc 'meta (cdr x))) + (meta (cdr metah)) + (ifaces (cdr (assoc 'interfaces meta))) + ) + + (map (lambda (iface) + (hashq-set! + iface->grob-table iface + (cons (car x) + (hashq-ref iface->grob-table iface '()) + ))) + ifaces) + )) + all-grob-descriptions) + +;; First level Interface description +(define (interface-doc interface) + (let ((name (symbol->string (car interface)))) + (make + #:name name + #:text (string-append + (interface-doc-string (cdr interface) #f) + "\n\n" + "This grob interface is used in the following graphical objects: " + + (human-listify + (map ref-ify + (map symbol->string + (hashq-ref iface->grob-table (car interface) '() ))))) + + ))) + +(define (grob-doc description) + "Given a property alist DESCRIPTION, make a documentation +node." + + (let* + ( + (metah (assoc 'meta description)) + + (meta (cdr metah)) + (name (cdr (assoc 'name meta))) + (ifaces (map lookup-interface (cdr (assoc 'interfaces meta)))) + (ifacedoc (map (lambda (iface) + (string-append +"@html +
+@end html + +@subsubheading " +(ref-ify (symbol->string (car iface))) + +"\n\n" + (interface-doc-string iface description))) + (reverse ifaces))) + (engravers (filter-list + (lambda (x) (engraver-makes-grob? name x)) all-engravers-list)) + (namestr (symbol->string name)) + (engraver-names (map ly:translator-name engravers)) + ) + + (make + #:name namestr + #:text + (string-append + namestr " grobs are created by: " + (human-listify (map ref-ify + (map engraver-name engraver-names))) + (apply string-append ifacedoc) + )) + )) + +(define (all-grobs-doc) + (make + #:name "All Graphical objects" + #:desc "Description and defaults for all Grobs" + #:children + (map (lambda (x) (grob-doc (cdr x))) all-grob-descriptions))) + +(define interface-description-alist + (hash-fold + (lambda (key val prior) + (cons (cons key val) prior) + ) + '() (ly:all-grob-interfaces))) + +(set! interface-description-alist (sort interface-description-alist alist + #:name "Graphical Object Interfaces" + #:desc "Building blocks of graphical objects" + #:children + (map interface-doc interface-description-alist) + )) + +(define (all-backend-properties-doc) + (let* + ( + (ps (sort (map symbol->string all-backend-properties) stringsymbol prop) 'backend #f)) + ps)) + (texi (description-list->texi descs)) + ) + (make + #:name "backend properties" + #:desc "all the properties in use as grob properties" + #:text texi) + )) + +;(dump-node (grob-doc (cdadr all-grob-descriptions)) (current-output-port) 0 ) +(define (backend-doc-node) + (make + #:name "Backend" + #:desc "Reference for the layout engine" + #:children + (list + (all-grobs-doc) + (all-interfaces-doc) + (all-backend-properties-doc) + ) + )) diff --git a/scm/document-functions.scm b/scm/document-functions.scm new file mode 100644 index 0000000000..459cb08a61 --- /dev/null +++ b/scm/document-functions.scm @@ -0,0 +1,48 @@ +(use-modules + (ice-9 regex)) + +(define (format-c-header c-h) + (regexp-substitute/global + #f "," + (regexp-substitute/global #f "(SCM|\\)|\\() *" c-h 'pre "" 'post) + 'pre " " 'post) + ) + +(define (document-scheme-function name c-header doc-string) + (string-append + "@defun " (symbol->string name) " " (format-c-header c-header) "\n" + doc-string + "\n@end defun\n\n") + ) + +(define all-scheme-functions + (hash-fold + (lambda (key val prior) + (cons (cons key val) prior) + ) + '() (ly:get-all-function-documentation)) + ) + +(define (all-scheme-functions-doc) + (let* + ( + + (fdocs (map (lambda (x) + (document-scheme-function (car x) (cadr x) (cddr x)) + ) + all-scheme-functions) + ) + (sfdocs (sort fdocs string + #:name "Scheme functions" + #:desc "Primitive functions exported by LilyPond" + #:text + (apply string-append sfdocs) + ) + )) + + +; (dump-node (all-scheme-functions-doc) (current-output-port) 0 ) diff --git a/scm/document-markup.scm b/scm/document-markup.scm new file mode 100644 index 0000000000..1db87f01b0 --- /dev/null +++ b/scm/document-markup.scm @@ -0,0 +1,36 @@ + +(define (doc-markup-function func) + (let* + ( + (doc-str (procedure-documentation func) ) + (f-name (symbol->string (procedure-name func))) + (sig (object-property func 'markup-signature)) + (sig-str (string-join (map type-name sig) " ")) + ) + + + + (string-append + "\n\n@b{" + f-name + "}\n\n@findex " f-name "\n" + "\n\n@i{Argument types}: " sig-str + (if (string? doc-str) + (string-append + "\n\n@i{Description}: \n\n" + doc-str) + "") + + + ))) + + +(define (markup-doc-node) + (make + #:name "Markup functions" + #:desc "Definitions of the markup functions" + #:text (apply string-append + (map doc-markup-function markup-function-list) ) + )) + + diff --git a/scm/document-music.scm b/scm/document-music.scm new file mode 100644 index 0000000000..bd6a8ea7ef --- /dev/null +++ b/scm/document-music.scm @@ -0,0 +1,130 @@ + +(define (music-props-doc) + (make + #:name "Music properties" + #:desc "All music properties, including descriptions" + #:text + (let* ( + (ps (sort (map symbol->string all-music-properties) stringtexi 'music (string->symbol prop))) + ps)) + (texi (description-list->texi descs)) + ) + texi) + )) + +(define music-types->names (make-vector 61 '())) +(map (lambda (entry) + (let* + ( + (types (cdr (assoc 'types (cdr entry) ))) + ) + (map (lambda (type) + (hashq-set! music-types->names type + (cons (car entry) + (hashq-ref music-types->names type '()))) + + ) types) + + )) + music-descriptions) + + +(define (hash-table->alist t) + "Convert table t to list" + (apply append + (vector->list t) + )) + +(define (strip-description x) + (cons (symbol->string (car x)) + "")) + +(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)) string + #:name "Music classes" + #:children + (map music-type-doc + (sort + (hash-table->alist music-types->names) aliststring types))) + "\n\n" + "\n\nAccepted by: " + (human-listify + (map ref-ify + (map ly:translator-name + (filter-list + (lambda (x) (engraver-accepts-music-types? types x)) all-engravers-list)))) + "\n\nProperties: \n" + (description-list->texi + (map + (lambda (x) (document-property x 'music props)) + (map car props))) + + ) + )) + +(define (music-object-doc obj) + (make + #:name (symbol->string (car obj)) + #:text (music-doc-str obj) + )) + +(define (music-expressions-doc) + (make + #:name "Music expressions" + #:desc "Objects that represent music." + #:children + (map music-object-doc music-descriptions) + )) + +(define (music-doc-node) + (make + #:name "Music definitions" + #:desc "Definition of the Input data structures" + #:children + (list + (music-expressions-doc) + (music-types-doc) + (music-props-doc)) + )) + + + + diff --git a/scm/document-translation.scm b/scm/document-translation.scm new file mode 100644 index 0000000000..dd2fd71b81 --- /dev/null +++ b/scm/document-translation.scm @@ -0,0 +1,311 @@ + +;;; engraver-doumentation-lib.scm -- Functions for engraver documentation +;;; +;;; source file of the GNU LilyPond music typesetter +;;; +;;; (c) 2000--2002 Han-Wen Nienhuys +;;; Jan Nieuwenhuizen + + +(define (engraver-makes-grob? name-symbol grav) + (memq name-symbol (assoc 'grobs-created (ly:translator-description grav))) + ) + +(define (engraver-accepts-music-type? name-symbol grav) + (memq name-symbol (assoc 'events-accepted (ly:translator-description grav))) + + ) + +(define (engraver-accepts-music-types? types grav) + (if (null? types) + #f + (or + (engraver-accepts-music-type? (car types) grav) + (engraver-accepts-music-types? (cdr types) grav))) + ) + +(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)))) + (name (ly:translator-name engraver)) + (name-sym (string->symbol name)) + (desc (cdr (assoc 'description (ly:translator-description engraver)))) + (grobs (engraver-grobs engraver)) + ) + + (string-append + desc + "\n\n" + (if (pair? accepted) + (string-append + "Music types accepted:\n\n" + (human-listify + (map (lambda (x) + (string-append + "@ref{" + (symbol->string x) + "}")) accepted) + )) + "") + "\n\n" + (if (pair? propsr) + (string-append + "Properties (read)" + (description-list->texi + (map (lambda (x) (document-property x 'translation #f)) propsr))) + "") + + (if (null? propsw) + "" + (string-append + "Properties (write)" + (description-list->texi + (map (lambda (x) (document-property x 'translation #f)) propsw)))) + (if (null? grobs) + "" + (string-append + "This engraver creates the following grobs: \n " + (human-listify (map ref-ify (uniq-list (sort grobs string + #:name (ly:translator-name grav) + #:text (engraver-doc-string grav #t) + )) + +;; Second level, part of Context description + +(define name->engraver-table (make-vector 61 '())) +(map + (lambda (x) + (hash-set! name->engraver-table (ly:translator-name x) x)) + (ly:get-all-translators)) + +(define (find-engraver-by-name name) + (hash-ref name->engraver-table name #f)) + +(define (document-engraver-by-name name) + (let* + ( + (eg (find-engraver-by-name name )) + ) + + (cons name + (engraver-doc-string eg #f) + + ) + )) + +(define (document-property-operation op) + (let + ((tag (car op)) + (body (cdr op)) + (sym (cadr op)) + ) + + (cond + ((equal? tag 'push) + (string-append + "@item " + (if (null? (cddr body)) + "Revert " + "Set " + ) + "grob-property " + (symbol->string (cadr body)) + " in " (symbol->string sym) + (if (not (null? (cddr body))) + (string-append " to " (scm->texi (cadr (cdr body)))) + ) + "\n" + ) + + ) + ((equal? (object-property sym 'is-grob?) #t) "") + ((equal? (car op) 'assign) + (string-append + "@item Set translator property " + (symbol->string (car body)) + " to " + (scm->texi (cadr body)) + "\n" + ) + ) + ) + )) + + +(define (context-doc context-desc) + (let* + ( + (name (cdr (assoc 'type-name context-desc))) + (desc-handle (assoc (string->symbol name) context-description-alist)) + (desc (if (pair? desc-handle) (cdr desc-handle) "")) + + (accepts (cdr (assoc 'accepts context-desc))) + (consists (append + (list (cdr (assoc 'group-type context-desc))) + (cdr (assoc 'consists context-desc)) + (cdr (assoc 'end-consists context-desc)) + )) + (props (cdr (assoc 'property-ops context-desc))) + (grobs (context-grobs context-desc)) + (grob-refs (map (lambda (x) (ref-ify x)) grobs)) + ) + (make + #:name name + #:text + (string-append + desc + "\n\nThis context creates the following grobs: \n\n" + (human-listify (uniq-list (sort grob-refs stringtexi + (map document-engraver-by-name consists)) + )))) + +(define (engraver-grobs grav) + (let* ( + (eg (if (string? grav) + (find-engraver-by-name grav) + grav)) + + ) + + (if (eq? eg #f) + '() + (map symbol->string (cdr (assoc 'grobs-created (ly:translator-description eg)))) + ) + )) + +(define (context-grobs context-desc) + (let* ( + (consists (append + (list (cdr (assoc 'group-type context-desc))) + (cdr (assoc 'consists context-desc)) + (cdr (assoc 'end-consists context-desc)) + )) + (grobs (apply append + (map engraver-grobs consists)) + ) + ) + grobs + )) + +(define (symbolstring l) (symbol->string r))) + +(define (all-contexts-doc) + (let* ( + (paper-alist + (sort (My_lily_parser::paper_description) + (lambda (x y) (symbolstring (map car paper-alist)) string + #:name "Contexts" + #:desc "Complete descriptions of all contexts" + #:children + (map context-doc contexts) + ) + )) + + +(define all-engravers-list (ly:get-all-translators)) +(set! all-engravers-list + (sort all-engravers-list + (lambda (a b) (string + #:name "Engravers" + #:desc "All separate engravers" + #:children + (map engraver-doc all-engravers-list))) + +(define (all-translation-properties-doc) + + (let* + ( + (ps (sort (map symbol->string all-translation-properties) stringsymbol ps)) + (propdescs + (map + (lambda (x) (document-property x 'translation #f)) + sortedsyms)) + (texi (description-list->texi propdescs)) + ) + + (make + #:name "Translation properties" + #:desc "All translation properties" + #:text texi) + )) + + +;(dump-node (all-contexts-doc) (current-output-port) 0 ) + +(define (translation-doc-node) + (make + #:name "Translation" + #:desc "From music to layout" + #:children + (list + (all-contexts-doc) + (all-engravers-doc) + (all-translation-properties-doc) + ) + )) diff --git a/scm/documentation-generate.scm b/scm/documentation-generate.scm new file mode 100644 index 0000000000..0575f483a4 --- /dev/null +++ b/scm/documentation-generate.scm @@ -0,0 +1,123 @@ +;;; generate-documentation.scm -- Generate documentation +;;; +;;; source file of the GNU LilyPond music typesetter +;;; +;;; (c) 2000--2002 Han-Wen Nienhuys +;;; Jan Nieuwenhuizen + +;;; File entry point for generated documentation + +;;; Running LilyPond on this file generates the documentation + +(debug-enable 'debug) +(debug-enable 'backtrace) +(read-enable 'positions) + +;;;;;;;;;;;;;;;; +;;;;;;;;;;;;;;;; TODO : make modules of these! +;;;;;;;;;;;;;;;; + +(define load-files '("documentation-lib.scm" + "document-functions.scm" + "document-translation.scm" + "document-music.scm" + "document-backend.scm" + "document-markup.scm" + )) +(map ly:load load-files) + + +;;(define no-copies #t) ; from 490 to 410K, but doesn't look nice yet +;; +;; Also, copies of interfaces use up lots more space, but that's +;; functional because the default property values of the interfaces +;; are described... +(define no-copies #f) + +(define file-name "lilypond-internals") +(define outname (string-append file-name ".texi")) +(define out-port (open-output-file outname)) + +(writing-wip outname) + +(display + (string-append + "@c -*-texinfo-*-" + (texi-file-head "LilyPond internals" outname "(lilypond.info)") + " + +@ifhtml +@macro usermanref{NAME} +@uref{../lilypond/\\NAME\\.html,\\NAME\\} +@cindex \\NAME\\ +@end macro +@end ifhtml + +@ifinfo +@macro usermanref{NAME} +@inforef{\\NAME\\,,lilypond} +@cindex \\NAME\\ +@end macro +@end ifinfo + +@ifhtml +@macro glossaryref{NAME} +@uref{../music-glossary/\\NAME\\.html,\\NAME\\} +@cindex \\NAME\\ +@end macro +@end ifhtml + +@ifinfo +@macro glossaryref{NAME} +@inforef{\\NAME\\,,music-glossary} +@cindex \\NAME\\ +@end macro +@end ifinfo + + +@ignore +@omftitle LilyPond internals +@omfcreator Han-Wen Nienhuys and Jan Nieuwenhuizen +@omfdescription Programmer's reference of the LilyPond music engraving system +@omftype user's guide +@omflanguage English +@omfcategory Music +@end ignore + + +") out-port) + +(define top-node + (make + #:name "Top" + #:children + (list + (music-doc-node) + (translation-doc-node) + (backend-doc-node) + (all-scheme-functions-doc) + (markup-doc-node) + (make + #:name "Index" + #:text " +@unnumbered Concept index + +@printindex cp + +@unnumbered Variable index + +@printindex vr + +@unnumbered Function index + +@printindex fn + +\n@bye" + + + ) + ))) + + +(dump-node top-node out-port 0) +(newline (current-error-port)) diff --git a/scm/engraver-documentation-lib.scm b/scm/engraver-documentation-lib.scm deleted file mode 100644 index dd2fd71b81..0000000000 --- a/scm/engraver-documentation-lib.scm +++ /dev/null @@ -1,311 +0,0 @@ - -;;; engraver-doumentation-lib.scm -- Functions for engraver documentation -;;; -;;; source file of the GNU LilyPond music typesetter -;;; -;;; (c) 2000--2002 Han-Wen Nienhuys -;;; Jan Nieuwenhuizen - - -(define (engraver-makes-grob? name-symbol grav) - (memq name-symbol (assoc 'grobs-created (ly:translator-description grav))) - ) - -(define (engraver-accepts-music-type? name-symbol grav) - (memq name-symbol (assoc 'events-accepted (ly:translator-description grav))) - - ) - -(define (engraver-accepts-music-types? types grav) - (if (null? types) - #f - (or - (engraver-accepts-music-type? (car types) grav) - (engraver-accepts-music-types? (cdr types) grav))) - ) - -(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)))) - (name (ly:translator-name engraver)) - (name-sym (string->symbol name)) - (desc (cdr (assoc 'description (ly:translator-description engraver)))) - (grobs (engraver-grobs engraver)) - ) - - (string-append - desc - "\n\n" - (if (pair? accepted) - (string-append - "Music types accepted:\n\n" - (human-listify - (map (lambda (x) - (string-append - "@ref{" - (symbol->string x) - "}")) accepted) - )) - "") - "\n\n" - (if (pair? propsr) - (string-append - "Properties (read)" - (description-list->texi - (map (lambda (x) (document-property x 'translation #f)) propsr))) - "") - - (if (null? propsw) - "" - (string-append - "Properties (write)" - (description-list->texi - (map (lambda (x) (document-property x 'translation #f)) propsw)))) - (if (null? grobs) - "" - (string-append - "This engraver creates the following grobs: \n " - (human-listify (map ref-ify (uniq-list (sort grobs string - #:name (ly:translator-name grav) - #:text (engraver-doc-string grav #t) - )) - -;; Second level, part of Context description - -(define name->engraver-table (make-vector 61 '())) -(map - (lambda (x) - (hash-set! name->engraver-table (ly:translator-name x) x)) - (ly:get-all-translators)) - -(define (find-engraver-by-name name) - (hash-ref name->engraver-table name #f)) - -(define (document-engraver-by-name name) - (let* - ( - (eg (find-engraver-by-name name )) - ) - - (cons name - (engraver-doc-string eg #f) - - ) - )) - -(define (document-property-operation op) - (let - ((tag (car op)) - (body (cdr op)) - (sym (cadr op)) - ) - - (cond - ((equal? tag 'push) - (string-append - "@item " - (if (null? (cddr body)) - "Revert " - "Set " - ) - "grob-property " - (symbol->string (cadr body)) - " in " (symbol->string sym) - (if (not (null? (cddr body))) - (string-append " to " (scm->texi (cadr (cdr body)))) - ) - "\n" - ) - - ) - ((equal? (object-property sym 'is-grob?) #t) "") - ((equal? (car op) 'assign) - (string-append - "@item Set translator property " - (symbol->string (car body)) - " to " - (scm->texi (cadr body)) - "\n" - ) - ) - ) - )) - - -(define (context-doc context-desc) - (let* - ( - (name (cdr (assoc 'type-name context-desc))) - (desc-handle (assoc (string->symbol name) context-description-alist)) - (desc (if (pair? desc-handle) (cdr desc-handle) "")) - - (accepts (cdr (assoc 'accepts context-desc))) - (consists (append - (list (cdr (assoc 'group-type context-desc))) - (cdr (assoc 'consists context-desc)) - (cdr (assoc 'end-consists context-desc)) - )) - (props (cdr (assoc 'property-ops context-desc))) - (grobs (context-grobs context-desc)) - (grob-refs (map (lambda (x) (ref-ify x)) grobs)) - ) - (make - #:name name - #:text - (string-append - desc - "\n\nThis context creates the following grobs: \n\n" - (human-listify (uniq-list (sort grob-refs stringtexi - (map document-engraver-by-name consists)) - )))) - -(define (engraver-grobs grav) - (let* ( - (eg (if (string? grav) - (find-engraver-by-name grav) - grav)) - - ) - - (if (eq? eg #f) - '() - (map symbol->string (cdr (assoc 'grobs-created (ly:translator-description eg)))) - ) - )) - -(define (context-grobs context-desc) - (let* ( - (consists (append - (list (cdr (assoc 'group-type context-desc))) - (cdr (assoc 'consists context-desc)) - (cdr (assoc 'end-consists context-desc)) - )) - (grobs (apply append - (map engraver-grobs consists)) - ) - ) - grobs - )) - -(define (symbolstring l) (symbol->string r))) - -(define (all-contexts-doc) - (let* ( - (paper-alist - (sort (My_lily_parser::paper_description) - (lambda (x y) (symbolstring (map car paper-alist)) string - #:name "Contexts" - #:desc "Complete descriptions of all contexts" - #:children - (map context-doc contexts) - ) - )) - - -(define all-engravers-list (ly:get-all-translators)) -(set! all-engravers-list - (sort all-engravers-list - (lambda (a b) (string - #:name "Engravers" - #:desc "All separate engravers" - #:children - (map engraver-doc all-engravers-list))) - -(define (all-translation-properties-doc) - - (let* - ( - (ps (sort (map symbol->string all-translation-properties) stringsymbol ps)) - (propdescs - (map - (lambda (x) (document-property x 'translation #f)) - sortedsyms)) - (texi (description-list->texi propdescs)) - ) - - (make - #:name "Translation properties" - #:desc "All translation properties" - #:text texi) - )) - - -;(dump-node (all-contexts-doc) (current-output-port) 0 ) - -(define (translation-doc-node) - (make - #:name "Translation" - #:desc "From music to layout" - #:children - (list - (all-contexts-doc) - (all-engravers-doc) - (all-translation-properties-doc) - ) - )) diff --git a/scm/function-documentation.scm b/scm/function-documentation.scm deleted file mode 100644 index 459cb08a61..0000000000 --- a/scm/function-documentation.scm +++ /dev/null @@ -1,48 +0,0 @@ -(use-modules - (ice-9 regex)) - -(define (format-c-header c-h) - (regexp-substitute/global - #f "," - (regexp-substitute/global #f "(SCM|\\)|\\() *" c-h 'pre "" 'post) - 'pre " " 'post) - ) - -(define (document-scheme-function name c-header doc-string) - (string-append - "@defun " (symbol->string name) " " (format-c-header c-header) "\n" - doc-string - "\n@end defun\n\n") - ) - -(define all-scheme-functions - (hash-fold - (lambda (key val prior) - (cons (cons key val) prior) - ) - '() (ly:get-all-function-documentation)) - ) - -(define (all-scheme-functions-doc) - (let* - ( - - (fdocs (map (lambda (x) - (document-scheme-function (car x) (cadr x) (cddr x)) - ) - all-scheme-functions) - ) - (sfdocs (sort fdocs string - #:name "Scheme functions" - #:desc "Primitive functions exported by LilyPond" - #:text - (apply string-append sfdocs) - ) - )) - - -; (dump-node (all-scheme-functions-doc) (current-output-port) 0 ) diff --git a/scm/generate-documentation.scm b/scm/generate-documentation.scm deleted file mode 100644 index 4e84ab7aec..0000000000 --- a/scm/generate-documentation.scm +++ /dev/null @@ -1,121 +0,0 @@ -;;; generate-documentation.scm -- Generate documentation -;;; -;;; source file of the GNU LilyPond music typesetter -;;; -;;; (c) 2000--2002 Han-Wen Nienhuys -;;; Jan Nieuwenhuizen - -;;; File entry point for generated documentation - -;;; Running LilyPond on this file generates the documentation - -(debug-enable 'debug) -(debug-enable 'backtrace) -(read-enable 'positions) - -;;;;;;;;;;;;;;;; -;;;;;;;;;;;;;;;; TODO : make modules of these! -;;;;;;;;;;;;;;;; - -(define load-files '("documentation-lib.scm" - "function-documentation.scm" - "engraver-documentation-lib.scm" - "music-documentation-lib.scm" - "backend-documentation-lib.scm" - )) -(map ly:load load-files) - - -;;(define no-copies #t) ; from 490 to 410K, but doesn't look nice yet -;; -;; Also, copies of interfaces use up lots more space, but that's -;; functional because the default property values of the interfaces -;; are described... -(define no-copies #f) - -(define file-name "lilypond-internals") -(define outname (string-append file-name ".texi")) -(define out-port (open-output-file outname)) - -(writing-wip outname) - -(display - (string-append - "@c -*-texinfo-*-" - (texi-file-head "LilyPond internals" outname "(lilypond.info)") - " - -@ifhtml -@macro usermanref{NAME} -@uref{../lilypond/\\NAME\\.html,\\NAME\\} -@cindex \\NAME\\ -@end macro -@end ifhtml - -@ifinfo -@macro usermanref{NAME} -@inforef{\\NAME\\,,lilypond} -@cindex \\NAME\\ -@end macro -@end ifinfo - -@ifhtml -@macro glossaryref{NAME} -@uref{../music-glossary/\\NAME\\.html,\\NAME\\} -@cindex \\NAME\\ -@end macro -@end ifhtml - -@ifinfo -@macro glossaryref{NAME} -@inforef{\\NAME\\,,music-glossary} -@cindex \\NAME\\ -@end macro -@end ifinfo - - -@ignore -@omftitle LilyPond internals -@omfcreator Han-Wen Nienhuys and Jan Nieuwenhuizen -@omfdescription Programmer's reference of the LilyPond music engraving system -@omftype user's guide -@omflanguage English -@omfcategory Music -@end ignore - - -") out-port) - -(define top-node - (make - #:name "Top" - #:children - (list - (music-doc-node) - (translation-doc-node) - (backend-doc-node) - (all-scheme-functions-doc) - (make - #:name "Index" - #:text " -@unnumbered Concept index - -@printindex cp - -@unnumbered Variable index - -@printindex vr - -@unnumbered Function index - -@printindex fn - -\n@bye" - - - ) - ))) - - -(dump-node top-node out-port 0) -(newline (current-error-port)) diff --git a/scm/lily.scm b/scm/lily.scm index df687d0f6b..65c861cca7 100644 --- a/scm/lily.scm +++ b/scm/lily.scm @@ -288,8 +288,11 @@ is the first to satisfy CRIT ;;;;;;;;;;;;;;;; ; strings. + +;; TODO : make sep optional. (define-public (string-join str-list sep) "append the list of strings in STR-LIST, joining them with SEP" + (apply string-append (list-insert-separator str-list sep)) ) diff --git a/scm/music-documentation-lib.scm b/scm/music-documentation-lib.scm deleted file mode 100644 index bd6a8ea7ef..0000000000 --- a/scm/music-documentation-lib.scm +++ /dev/null @@ -1,130 +0,0 @@ - -(define (music-props-doc) - (make - #:name "Music properties" - #:desc "All music properties, including descriptions" - #:text - (let* ( - (ps (sort (map symbol->string all-music-properties) stringtexi 'music (string->symbol prop))) - ps)) - (texi (description-list->texi descs)) - ) - texi) - )) - -(define music-types->names (make-vector 61 '())) -(map (lambda (entry) - (let* - ( - (types (cdr (assoc 'types (cdr entry) ))) - ) - (map (lambda (type) - (hashq-set! music-types->names type - (cons (car entry) - (hashq-ref music-types->names type '()))) - - ) types) - - )) - music-descriptions) - - -(define (hash-table->alist t) - "Convert table t to list" - (apply append - (vector->list t) - )) - -(define (strip-description x) - (cons (symbol->string (car x)) - "")) - -(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)) string - #:name "Music classes" - #:children - (map music-type-doc - (sort - (hash-table->alist music-types->names) aliststring types))) - "\n\n" - "\n\nAccepted by: " - (human-listify - (map ref-ify - (map ly:translator-name - (filter-list - (lambda (x) (engraver-accepts-music-types? types x)) all-engravers-list)))) - "\n\nProperties: \n" - (description-list->texi - (map - (lambda (x) (document-property x 'music props)) - (map car props))) - - ) - )) - -(define (music-object-doc obj) - (make - #:name (symbol->string (car obj)) - #:text (music-doc-str obj) - )) - -(define (music-expressions-doc) - (make - #:name "Music expressions" - #:desc "Objects that represent music." - #:children - (map music-object-doc music-descriptions) - )) - -(define (music-doc-node) - (make - #:name "Music definitions" - #:desc "Definition of the Input data structures" - #:children - (list - (music-expressions-doc) - (music-types-doc) - (music-props-doc)) - )) - - - - diff --git a/scm/new-markup.scm b/scm/new-markup.scm index 5cccdc2697..cafc755904 100644 --- a/scm/new-markup.scm +++ b/scm/new-markup.scm @@ -411,7 +411,7 @@ for the reader. ;; (define markup? cheap-markup?) -(define markup-function-list +(define markup-functions-and-signatures (list ;; abs size @@ -470,7 +470,9 @@ for the reader. (set-object-property! (car x) 'markup-signature (cdr x)) (set-object-property! (car x) 'markup-keyword (markup-signature-to-keyword (cdr x))) ) - markup-function-list) + markup-functions-and-signatures) + +(define-public markup-function-list (map car markup-functions-and-signatures)) ;; construct a @@ -560,7 +562,7 @@ against SIGNATURE, reporting MAKE-NAME as the user-invoked function. ) (eval - (cons 'begin (map make-markup-maker markup-function-list)) + (cons 'begin (map make-markup-maker markup-functions-and-signatures)) markup-module ) diff --git a/scripts/lilypond-book.py b/scripts/lilypond-book.py index 248c2905ad..7578ef81a4 100644 --- a/scripts/lilypond-book.py +++ b/scripts/lilypond-book.py @@ -366,7 +366,7 @@ output_dict= { ## inline music doesn't. ## possibly other center options? 'output-html': r''' - + [picture of music] ''', }, @@ -448,7 +448,7 @@ output_dict= { \catcode`\@=0 @end tex @html -

+

[picture of music]

@end html @@ -461,7 +461,7 @@ output_dict= { \catcode`\@=0 @end tex @html - + [picture of music] @end html