2003-04-21 Han-Wen Nienhuys <hanwen@cs.uu.nl>
+ * 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
$(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)
@macro refbugs
@strong{BUGS}
+
+
@end macro
@macro seealso
c' c'' es' g' as' gisis' ais'
@end lilypond
+
+@seealso
+
+@internalsref{NoteEvent}, @internalsref{NoteHead}
+
@node Chromatic alterations
@subsection Chromatic alterations
a'4\rest d'4\rest
@end lilypond
+@internalsref{RestEvent}, @internalsref{Rest}
@c FIXME: naming.
The skip command is merely an empty musical placeholder. It does not
produce any output, not even transparent output.
+@seealso
+
+@internalsref{SkipEvent}
@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{
@menu
* Chords mode::
-* Printing chord names::
+* Printing chord names::
@end menu
@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
See @ref{Articulations} for general instructions how to apply scripts
such as fermatas to a @code{\notes@{@}} block.
-
@node Tuning output
@section Tuning output
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
@node Outputproperty
-
+@subsection Outputproperty
@cindex \outputproperty
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
}
@end lilypond
+@seealso
+
+@internalsref{Markup functions}, @file{scm/new-markup.scm}
+
@refbugs
@cindex kerning
@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
+
@node Font Size
@subsection Font size
@cindex font size, setting
This makes the following 28 measures (assuming 4/4 time) be broken every
4 measures.
+@seealso
+
+@internalsref{BreakEvent}
+
+
@node Page layout
@subsection Page layout
% 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")
+++ /dev/null
-;;; backend-documentation-lib.scm -- Functions for backend documentation
-;;;
-;;; source file of the GNU LilyPond music typesetter
-;;;
-;;; (c) 2000--2002 Han-Wen Nienhuys <hanwen@cs.uu.nl>
-;;; Jan Nieuwenhuizen <janneke@gnu.org>
-
-
-;;; 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) symbol<?))
- (docfunc (lambda (pr)
- (document-property
- pr 'backend grob-description )))
- (propdocs (map docfunc props))
- )
-
- (string-append
- desc
- "\n\n"
- (description-list->texi 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 <texi-node>
- #: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
-<hr>
-@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 <texi-node>
- #: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 <texi-node>
- #: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<?))
-
-
-;;;;;;;;;; check for dangling backend properties.
-(define (mark-interface-properties entry)
- (map (lambda (x) (set-object-property! x 'iface-marked #t)) (caddr (cdr entry)))
- )
-
-(map mark-interface-properties interface-description-alist)
-
-(define (check-dangling-properties prop)
- (if (not (object-property prop 'iface-marked))
- (error "\ngrob-property-description.scm: Can't find interface for property:" prop)))
-
-(map check-dangling-properties all-backend-properties)
-
-;;;;;;;;;;;;;;;;
-
-(define (lookup-interface name)
- (let* (
- (entry (hashq-ref (ly:all-grob-interfaces) name #f))
- )
-
- (if (equal? entry #f)
- (error "Unknown interface" name))
-
- entry
-))
-
-(define (all-interfaces-doc)
- (make <texi-node>
- #: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) string<?))
- (descs (map (lambda (prop)
- (document-property (string->symbol prop) 'backend #f))
- ps))
- (texi (description-list->texi descs))
- )
- (make <texi-node>
- #: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 <texi-node>
- #:name "Backend"
- #:desc "Reference for the layout engine"
- #:children
- (list
- (all-grobs-doc)
- (all-interfaces-doc)
- (all-backend-properties-doc)
- )
- ))
--- /dev/null
+;;; backend-documentation-lib.scm -- Functions for backend documentation
+;;;
+;;; source file of the GNU LilyPond music typesetter
+;;;
+;;; (c) 2000--2002 Han-Wen Nienhuys <hanwen@cs.uu.nl>
+;;; Jan Nieuwenhuizen <janneke@gnu.org>
+
+
+;;; 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) symbol<?))
+ (docfunc (lambda (pr)
+ (document-property
+ pr 'backend grob-description )))
+ (propdocs (map docfunc props))
+ )
+
+ (string-append
+ desc
+ "\n\n"
+ (description-list->texi 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 <texi-node>
+ #: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
+<hr>
+@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 <texi-node>
+ #: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 <texi-node>
+ #: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<?))
+
+
+;;;;;;;;;; check for dangling backend properties.
+(define (mark-interface-properties entry)
+ (map (lambda (x) (set-object-property! x 'iface-marked #t)) (caddr (cdr entry)))
+ )
+
+(map mark-interface-properties interface-description-alist)
+
+(define (check-dangling-properties prop)
+ (if (not (object-property prop 'iface-marked))
+ (error "\ngrob-property-description.scm: Can't find interface for property:" prop)))
+
+(map check-dangling-properties all-backend-properties)
+
+;;;;;;;;;;;;;;;;
+
+(define (lookup-interface name)
+ (let* (
+ (entry (hashq-ref (ly:all-grob-interfaces) name #f))
+ )
+
+ (if (equal? entry #f)
+ (error "Unknown interface" name))
+
+ entry
+))
+
+(define (all-interfaces-doc)
+ (make <texi-node>
+ #: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) string<?))
+ (descs (map (lambda (prop)
+ (document-property (string->symbol prop) 'backend #f))
+ ps))
+ (texi (description-list->texi descs))
+ )
+ (make <texi-node>
+ #: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 <texi-node>
+ #:name "Backend"
+ #:desc "Reference for the layout engine"
+ #:children
+ (list
+ (all-grobs-doc)
+ (all-interfaces-doc)
+ (all-backend-properties-doc)
+ )
+ ))
--- /dev/null
+(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<?))
+ )
+
+
+ (make <texi-node>
+ #:name "Scheme functions"
+ #:desc "Primitive functions exported by LilyPond"
+ #:text
+ (apply string-append sfdocs)
+ )
+ ))
+
+
+; (dump-node (all-scheme-functions-doc) (current-output-port) 0 )
--- /dev/null
+
+(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 <texi-node>
+ #:name "Markup functions"
+ #:desc "Definitions of the markup functions"
+ #:text (apply string-append
+ (map doc-markup-function markup-function-list) )
+ ))
+
+
--- /dev/null
+
+(define (music-props-doc)
+ (make <texi-node>
+ #:name "Music properties"
+ #:desc "All music properties, including descriptions"
+ #:text
+ (let* (
+ (ps (sort (map symbol->string all-music-properties) string<?))
+ (descs (map (lambda (prop)
+ (property->texi '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 <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 ly:translator-name
+ (filter-list
+ (lambda (x) (engraver-accepts-music-type? (car entry) x)) all-engravers-list))))
+ "\n\n"
+ )))
+
+(define (music-types-doc)
+ (make <texi-node>
+ #:name "Music classes"
+ #:children
+ (map music-type-doc
+ (sort
+ (hash-table->alist music-types->names) alist<?))
+ ))
+
+(define (music-doc-str obj)
+ (let*
+ (
+ (namesym (car obj))
+ (props (cdr obj))
+ (types (cdr (assoc 'types props)))
+ )
+
+ (string-append
+ (object-property namesym 'music-description)
+ "\n\nMusic types:\n"
+ (human-listify (map ref-ify (map symbol->string 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 <texi-node>
+ #:name (symbol->string (car obj))
+ #:text (music-doc-str obj)
+ ))
+
+(define (music-expressions-doc)
+ (make <texi-node>
+ #:name "Music expressions"
+ #:desc "Objects that represent music."
+ #:children
+ (map music-object-doc music-descriptions)
+ ))
+
+(define (music-doc-node)
+ (make <texi-node>
+ #:name "Music definitions"
+ #:desc "Definition of the Input data structures"
+ #:children
+ (list
+ (music-expressions-doc)
+ (music-types-doc)
+ (music-props-doc))
+ ))
+
+
+
+
--- /dev/null
+
+;;; engraver-doumentation-lib.scm -- Functions for engraver documentation
+;;;
+;;; source file of the GNU LilyPond music typesetter
+;;;
+;;; (c) 2000--2002 Han-Wen Nienhuys <hanwen@cs.uu.nl>
+;;; Jan Nieuwenhuizen <janneke@gnu.org>
+
+
+(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<? ))))
+ ".")
+ )
+
+ "\n\n"
+
+ (if in-which-contexts
+ (let* ((paper-alist (My_lily_parser::paper_description))
+ (context-description-alist (map cdr paper-alist))
+ (contexts
+ (apply append
+ (map (lambda (x)
+ (let ((context (cdr (assoc 'type-name x)))
+ (consists (append
+ (list (cdr (assoc 'group-type x)))
+ (cdr (assoc 'consists x))
+ (cdr (assoc 'end-consists x)))))
+
+ (if (member name consists)
+ (list context)
+ '())))
+ context-description-alist))))
+ (string-append
+ name " is part of contexts: "
+ (human-listify (map ref-ify (map context-name contexts)))))
+ ""
+ ))))
+
+
+
+
+;; First level Engraver description
+(define (engraver-doc grav)
+ (make <texi-node>
+ #: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 <texi-node>
+ #:name name
+ #:text
+ (string-append
+ desc
+ "\n\nThis context creates the following grobs: \n\n"
+ (human-listify (uniq-list (sort grob-refs string<? )))
+ "."
+ (if (pair? props)
+ (string-append
+ "\n\nThis context sets the following properties:\n"
+ "@itemize @bullet\n"
+ (apply string-append (map document-property-operation props))
+ "@end itemize\n"
+ )
+ ""
+ )
+
+ (if (null? accepts)
+ "\n\nThis context is a `bottom' context; it can not contain other contexts."
+ (string-append
+ "\n\nContext "
+ name " can contain \n"
+ (human-listify (map ref-ify (map context-name accepts)))))
+
+ "\n\nThis context is built from the following engravers: "
+ (description-list->texi
+ (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 (symbol<? l r)
+ (string<? (symbol->string l) (symbol->string r)))
+
+(define (all-contexts-doc)
+ (let* (
+ (paper-alist
+ (sort (My_lily_parser::paper_description)
+ (lambda (x y) (symbol<? (car x) (car y)))))
+ (names (sort (map symbol->string (map car paper-alist)) string<?))
+ (contexts (map cdr paper-alist))
+ )
+
+ (make <texi-node>
+ #: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<? (ly:translator-name a)
+ (ly:translator-name b)))))
+
+(define (all-engravers-doc)
+ (make <texi-node>
+ #: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) string<?))
+ (sortedsyms (map string->symbol ps))
+ (propdescs
+ (map
+ (lambda (x) (document-property x 'translation #f))
+ sortedsyms))
+ (texi (description-list->texi propdescs))
+ )
+
+ (make <texi-node>
+ #:name "Translation properties"
+ #:desc "All translation properties"
+ #:text texi)
+ ))
+
+
+;(dump-node (all-contexts-doc) (current-output-port) 0 )
+
+(define (translation-doc-node)
+ (make <texi-node>
+ #:name "Translation"
+ #:desc "From music to layout"
+ #:children
+ (list
+ (all-contexts-doc)
+ (all-engravers-doc)
+ (all-translation-properties-doc)
+ )
+ ))
--- /dev/null
+;;; generate-documentation.scm -- Generate documentation
+;;;
+;;; source file of the GNU LilyPond music typesetter
+;;;
+;;; (c) 2000--2002 Han-Wen Nienhuys <hanwen@cs.uu.nl>
+;;; Jan Nieuwenhuizen <janneke@gnu.org>
+
+;;; 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 <texi-node>
+ #:name "Top"
+ #:children
+ (list
+ (music-doc-node)
+ (translation-doc-node)
+ (backend-doc-node)
+ (all-scheme-functions-doc)
+ (markup-doc-node)
+ (make <texi-node>
+ #: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))
+++ /dev/null
-
-;;; engraver-doumentation-lib.scm -- Functions for engraver documentation
-;;;
-;;; source file of the GNU LilyPond music typesetter
-;;;
-;;; (c) 2000--2002 Han-Wen Nienhuys <hanwen@cs.uu.nl>
-;;; Jan Nieuwenhuizen <janneke@gnu.org>
-
-
-(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<? ))))
- ".")
- )
-
- "\n\n"
-
- (if in-which-contexts
- (let* ((paper-alist (My_lily_parser::paper_description))
- (context-description-alist (map cdr paper-alist))
- (contexts
- (apply append
- (map (lambda (x)
- (let ((context (cdr (assoc 'type-name x)))
- (consists (append
- (list (cdr (assoc 'group-type x)))
- (cdr (assoc 'consists x))
- (cdr (assoc 'end-consists x)))))
-
- (if (member name consists)
- (list context)
- '())))
- context-description-alist))))
- (string-append
- name " is part of contexts: "
- (human-listify (map ref-ify (map context-name contexts)))))
- ""
- ))))
-
-
-
-
-;; First level Engraver description
-(define (engraver-doc grav)
- (make <texi-node>
- #: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 <texi-node>
- #:name name
- #:text
- (string-append
- desc
- "\n\nThis context creates the following grobs: \n\n"
- (human-listify (uniq-list (sort grob-refs string<? )))
- "."
- (if (pair? props)
- (string-append
- "\n\nThis context sets the following properties:\n"
- "@itemize @bullet\n"
- (apply string-append (map document-property-operation props))
- "@end itemize\n"
- )
- ""
- )
-
- (if (null? accepts)
- "\n\nThis context is a `bottom' context; it can not contain other contexts."
- (string-append
- "\n\nContext "
- name " can contain \n"
- (human-listify (map ref-ify (map context-name accepts)))))
-
- "\n\nThis context is built from the following engravers: "
- (description-list->texi
- (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 (symbol<? l r)
- (string<? (symbol->string l) (symbol->string r)))
-
-(define (all-contexts-doc)
- (let* (
- (paper-alist
- (sort (My_lily_parser::paper_description)
- (lambda (x y) (symbol<? (car x) (car y)))))
- (names (sort (map symbol->string (map car paper-alist)) string<?))
- (contexts (map cdr paper-alist))
- )
-
- (make <texi-node>
- #: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<? (ly:translator-name a)
- (ly:translator-name b)))))
-
-(define (all-engravers-doc)
- (make <texi-node>
- #: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) string<?))
- (sortedsyms (map string->symbol ps))
- (propdescs
- (map
- (lambda (x) (document-property x 'translation #f))
- sortedsyms))
- (texi (description-list->texi propdescs))
- )
-
- (make <texi-node>
- #:name "Translation properties"
- #:desc "All translation properties"
- #:text texi)
- ))
-
-
-;(dump-node (all-contexts-doc) (current-output-port) 0 )
-
-(define (translation-doc-node)
- (make <texi-node>
- #:name "Translation"
- #:desc "From music to layout"
- #:children
- (list
- (all-contexts-doc)
- (all-engravers-doc)
- (all-translation-properties-doc)
- )
- ))
+++ /dev/null
-(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<?))
- )
-
-
- (make <texi-node>
- #:name "Scheme functions"
- #:desc "Primitive functions exported by LilyPond"
- #:text
- (apply string-append sfdocs)
- )
- ))
-
-
-; (dump-node (all-scheme-functions-doc) (current-output-port) 0 )
+++ /dev/null
-;;; generate-documentation.scm -- Generate documentation
-;;;
-;;; source file of the GNU LilyPond music typesetter
-;;;
-;;; (c) 2000--2002 Han-Wen Nienhuys <hanwen@cs.uu.nl>
-;;; Jan Nieuwenhuizen <janneke@gnu.org>
-
-;;; 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 <texi-node>
- #:name "Top"
- #:children
- (list
- (music-doc-node)
- (translation-doc-node)
- (backend-doc-node)
- (all-scheme-functions-doc)
- (make <texi-node>
- #: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))
;;;;;;;;;;;;;;;;
; 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))
)
+++ /dev/null
-
-(define (music-props-doc)
- (make <texi-node>
- #:name "Music properties"
- #:desc "All music properties, including descriptions"
- #:text
- (let* (
- (ps (sort (map symbol->string all-music-properties) string<?))
- (descs (map (lambda (prop)
- (property->texi '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 <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 ly:translator-name
- (filter-list
- (lambda (x) (engraver-accepts-music-type? (car entry) x)) all-engravers-list))))
- "\n\n"
- )))
-
-(define (music-types-doc)
- (make <texi-node>
- #:name "Music classes"
- #:children
- (map music-type-doc
- (sort
- (hash-table->alist music-types->names) alist<?))
- ))
-
-(define (music-doc-str obj)
- (let*
- (
- (namesym (car obj))
- (props (cdr obj))
- (types (cdr (assoc 'types props)))
- )
-
- (string-append
- (object-property namesym 'music-description)
- "\n\nMusic types:\n"
- (human-listify (map ref-ify (map symbol->string 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 <texi-node>
- #:name (symbol->string (car obj))
- #:text (music-doc-str obj)
- ))
-
-(define (music-expressions-doc)
- (make <texi-node>
- #:name "Music expressions"
- #:desc "Objects that represent music."
- #:children
- (map music-object-doc music-descriptions)
- ))
-
-(define (music-doc-node)
- (make <texi-node>
- #:name "Music definitions"
- #:desc "Definition of the Input data structures"
- #:children
- (list
- (music-expressions-doc)
- (music-types-doc)
- (music-props-doc))
- ))
-
-
-
-
;;
(define markup? cheap-markup?)
-(define markup-function-list
+(define markup-functions-and-signatures
(list
;; abs size
(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
)
(eval
- (cons 'begin (map make-markup-maker markup-function-list))
+ (cons 'begin (map make-markup-maker markup-functions-and-signatures))
markup-module
)
## inline music doesn't.
## possibly other center options?
'output-html': r'''
-<a href="%(fn)s.png">
+<a href="%(fn)s.ly">
<img align="center" valign="center" border="0" src="%(fn)s.png" alt="[picture of music]"></a>
''',
},
\catcode`\@=0
@end tex
@html
-<p><a href="%(fn)s.png">
+<p><a href="%(fn)s.ly">
<img border=0 src="%(fn)s.png" alt="[picture of music]">
</a><p>
@end html
\catcode`\@=0
@end tex
@html
-<a href="%(fn)s.png">
+<a href="%(fn)s.ly">
<img border=0 src="%(fn)s.png" alt="[picture of music]">
</a>
@end html
projects / lilypond.git / commitdiff