From: Graham Percival <graham@percival-music.ca>
Date: Sun, 4 Oct 2009 12:02:23 +0000 (+0100)
Subject: Doc: add Extending manual.
X-Git-Tag: release/2.13.6-1~63
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=3357772d4e9da87c1bcd99855d9b4055f590c806;p=lilypond.git

Doc: add Extending manual.
---

diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index d748db860a..9d3928558d 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -9,7 +9,8 @@ depth = ..
 
 NAME = documentation
 LANGS = $(shell $(PYTHON) $(top-src-dir)/python/langdefs.py)
-MANUALS_SUBDIRS = usage automated-engraving contributor essay general learning notation
+MANUALS_SUBDIRS = usage automated-engraving contributor essay \
+  general learning notation extending
 SUBDIRS = $(MANUALS_SUBDIRS) snippets logo pictures misc po css topdocs $(LANGS)
 STEPMAKE_TEMPLATES = documentation texinfo tex omf
 LOCALSTEPMAKE_TEMPLATES = lilypond ly
@@ -74,7 +75,7 @@ OUT_HTML_FILES += $(HTML_PAGE_NAMES:%=$(outdir)/%.html)
 MAIN_INFO_DOC = lilypond-notation
 INFO_DOCS = lilypond-usage lilypond-changes lilypond-contributor lilypond-internals \
  lilypond-essay lilypond-learning lilypond-notation music-glossary \
- lilypond-general
+ lilypond-general lilypond-extending
 ifeq ($(out),www)
 INFO_DOCS += lilypond-snippets 
 endif
diff --git a/Documentation/extending.tely b/Documentation/extending.tely
new file mode 100644
index 0000000000..5f374fc465
--- /dev/null
+++ b/Documentation/extending.tely
@@ -0,0 +1,71 @@
+\input texinfo @c -*- coding: utf-8; mode: texinfo; -*-
+@ignore
+    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+    When revising a translation, copy the HEAD committish of the
+    version that you are working on.  See TRANSLATION for details.
+@end ignore
+
+@setfilename lilypond-extending.info
+@settitle Extending LilyPond
+@documentencoding UTF-8
+@documentlanguage en
+@afourpaper
+
+@macro manualIntro
+This file explains how to extend the functionality of
+LilyPond version @version{}.
+@end macro
+
+@macro copyrightDeclare
+Copyright @copyright{} 
+1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+by the authors.
+@end macro
+
+@set FDL
+@include macros.itexi
+
+
+@c don't remove this comment.
+@ignore
+@omfcreator Han-Wen Nienhuys, Jan Nieuwenhuizen and Graham Percival
+@omfdescription Programming extensions for the LilyPond music engraving system
+@omftype program usage
+@omfcategory Applications|Publishing
+@omflanguage English
+@end ignore
+
+
+@lilyTitlePage{Extending}
+
+
+@c TOC -- non-tex
+@ifnottex
+
+@menu
+* Scheme tutorial::                Programming inside LilyPond.
+
+Appendices
+
+* GNU Free Documentation License:: License of this document.
+* LilyPond index::
+@end menu
+
+@docMain
+@end ifnottex
+
+
+@contents
+
+
+@include extending/scheme-tutorial.itely
+
+@include fdl.itexi
+
+@node LilyPond index
+@appendix LilyPond index
+
+@printindex cp
+
+@bye
diff --git a/Documentation/extending/GNUmakefile b/Documentation/extending/GNUmakefile
new file mode 100644
index 0000000000..cab24d6a17
--- /dev/null
+++ b/Documentation/extending/GNUmakefile
@@ -0,0 +1,7 @@
+depth = ../..
+
+LOCALSTEPMAKE_TEMPLATES = ly
+
+include $(depth)/make/stepmake.make
+
+
diff --git a/Documentation/extending/scheme-tutorial.itely b/Documentation/extending/scheme-tutorial.itely
new file mode 100644
index 0000000000..fbd8879a11
--- /dev/null
+++ b/Documentation/extending/scheme-tutorial.itely
@@ -0,0 +1,337 @@
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@ignore
+    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+    When revising a translation, copy the HEAD committish of the
+    version that you are working on.  See TRANSLATION for details.
+@end ignore
+
+@c \version "2.12.0"
+
+@node Scheme tutorial
+@chapter Scheme tutorial
+
+@funindex #
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+@cindex accessing Scheme
+@cindex evaluating Scheme
+@cindex LISP
+
+LilyPond uses the Scheme programming language, both as part of the
+input syntax, and as internal mechanism to glue modules of the program
+together.  This section is a very brief overview of entering data in
+Scheme.  If you want to know more about Scheme, see
+@uref{http://@/www@/.schemers@/.org}.
+
+LilyPond uses the GNU Guile implementation of Scheme, which is
+based on the Scheme @qq{R5RS} standard. If you are learning Scheme
+to use with LilyPond, working with a different implementation (or
+referring to a different standard) is not recommended. Information
+on guile can be found at @uref{http://www.gnu.org/software/guile/}.
+The @qq{R5RS} Scheme standard is located at
+@uref{http://www.schemers.org/Documents/Standards/R5RS/}.
+
+The LilyPond installation also includes the Guile implementation of
+Scheme.  On most systems you can experiment in a Scheme sandbox by
+opening a terminal window and typing @q{guile}.  On some systems,
+notably Windows, you may need to set the environment variable
+@code{GUILE_LOAD_PATH} to the directory @code{../usr/shr/guile/1.8}
+in the LilyPond installation (for the full path to this directory
+see @rlearning{Other sources of information}).  Alternatively, Windows
+users may simply choose @q{Run} from the Start menu and enter
+@q{guile}.
+
+The most basic concept in a language is data typing: numbers, character
+strings, lists, etc.  Here is a list of data types that are relevant to
+LilyPond input.
+
+@table @asis
+@item Booleans
+Boolean values are True or False.  The Scheme for True is @code{#t}
+and False is @code{#f}.
+@funindex ##t
+@funindex ##f
+
+@item Numbers
+Numbers are entered in the standard fashion,
+@code{1} is the (integer) number one, while @code{-1.5} is a
+floating point number (a non-integer number).
+
+@item Strings
+Strings are enclosed in double quotes,
+
+@example
+"this is a string"
+@end example
+
+Strings may span several lines
+
+@example
+"this
+is
+a string"
+@end example
+
+Quotation marks and newlines can also be added with so-called escape
+sequences.  The string @code{a said "b"} is entered as
+
+@example
+"a said \"b\""
+@end example
+
+Newlines and backslashes are escaped with @code{\n} and @code{\\}
+respectively.
+@end table
+
+
+In a music file, snippets of Scheme code are introduced with the hash
+mark @code{#}.  So, the previous examples translated to LilyPond are
+
+@example
+##t ##f
+#1 #-1.5
+#"this is a string"
+#"this
+is
+a string"
+@end example
+
+Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
+be used within Scheme code.  Comments in Guile Scheme are entered
+as follows:
+
+@example
+; this is a single-line comment
+
+#!
+  This a (non-nestable) Guile-style block comment
+  But these are rarely used by Schemers and never in
+  LilyPond source code
+!#
+@end example
+
+Multiple consecutive scheme expressions in a music file can be
+combined using the @code{begin} operator. This permits the number
+of hash marks to be reduced to one.
+
+@example
+#(begin
+  (define foo 0)
+  (define bar 1))
+@end example
+
+If @code{#} is followed by an opening bracket, @code{(}, as in
+the example above, the parser will remain in Scheme mode until
+a matching closing bracket, @code{)}, is found, so further
+@code{#} symbols to introduce a Scheme section are not required.
+
+For the rest of this section, we will assume that the data is entered
+in a music file, so we add @code{#}s everywhere.
+
+Scheme can be used to do calculations.  It uses @emph{prefix}
+syntax.  Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
+traditional @math{1+2}.
+
+@lisp
+#(+ 1 2)
+  @result{} #3
+@end lisp
+
+The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
+is@tie{}@code{3}.  Calculations may be nested; the result of a function may
+be used for another calculation.
+
+@lisp
+#(+ 1 (* 3 4))
+  @result{} #(+ 1 12)
+  @result{} #13
+@end lisp
+
+These calculations are examples of evaluations; an expression like
+@code{(* 3 4)} is replaced by its value @code{12}.  A similar thing
+happens with variables.  After defining a variable
+
+@example
+twelve = #12
+@end example
+
+@noindent
+variables can also be used in expressions, here
+
+@example
+twentyFour = #(* 2 twelve)
+@end example
+
+@noindent
+the number 24 is stored in the variable @code{twentyFour}.
+The same assignment can be done in completely in Scheme as well,
+
+@example
+#(define twentyFour (* 2 twelve))
+@end example
+
+The @emph{name} of a variable is also an expression, similar to a
+number or a string.  It is entered as
+
+@example
+#'twentyFour
+@end example
+
+@funindex #'symbol
+@cindex quoting in Scheme
+
+The quote mark @code{'} prevents the Scheme interpreter from substituting
+@code{24} for the @code{twentyFour}.  Instead, we get the name
+@code{twentyFour}.
+
+This syntax will be used very frequently, since many of the layout
+tweaks involve assigning (Scheme) values to internal variables, for
+example
+
+@example
+\override Stem #'thickness = #2.6
+@end example
+
+This instruction adjusts the appearance of stems.  The value @code{2.6}
+is put into the @code{thickness} variable of a @code{Stem}
+object.  @code{thickness} is measured relative to the thickness of
+staff lines, so these stem lines will be @code{2.6} times the
+width of staff lines.  This makes stems almost twice as thick as their
+normal size.  To distinguish between variables defined in input files (like
+@code{twentyFour} in the example above) and variables of internal
+objects, we will call the latter @q{properties} and the former
+@q{variables.}  So, the stem object has a @code{thickness} property,
+while @code{twentyFour} is an variable.
+
+@cindex properties vs. variables
+@cindex variables vs. properties
+
+Two-dimensional offsets (X and Y coordinates) as well as object sizes
+(intervals with a left and right point) are entered as @code{pairs}.  A
+pair@footnote{In Scheme terminology, the pair is called @code{cons},
+and its two elements are called @code{car} and @code{cdr} respectively.}
+is entered as @code{(first . second)} and, like symbols, they must be quoted,
+
+@example
+\override TextScript #'extra-offset = #'(1 . 2)
+@end example
+
+This assigns the pair (1, 2) to the @code{extra-offset} property of the
+TextScript object.  These numbers are measured in staff-spaces, so
+this command moves the object 1 staff space to the right, and 2 spaces up.
+
+The two elements of a pair may be arbitrary values, for example
+
+@example
+#'(1 . 2)
+#'(#t . #f)
+#'("blah-blah" . 3.14159265)
+@end example
+
+A list is entered by enclosing its elements in parentheses, and adding
+a quote.  For example,
+
+@example
+#'(1 2 3)
+#'(1 2 "string" #f)
+@end example
+
+We have been using lists all along.  A calculation, like @code{(+ 1 2)}
+is also a list (containing the symbol @code{+} and the numbers 1
+and@tie{}2).  Normally lists are interpreted as calculations, and the
+Scheme interpreter substitutes the outcome of the calculation.  To enter a
+list, we stop the evaluation.  This is done by quoting the list with a
+quote @code{'} symbol.  So, for calculations do not use a quote.
+
+Inside a quoted list or pair, there is no need to quote anymore.  The
+following is a pair of symbols, a list of symbols and a list of lists
+respectively,
+
+@example
+#'(stem . head)
+#'(staff clef key-signature)
+#'((1) (2))
+@end example
+
+
+@menu
+* Tweaking with Scheme::
+@end menu
+
+@node Tweaking with Scheme
+@section Tweaking with Scheme
+
+We have seen how LilyPond output can be heavily modified using
+commands like
+@code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
+we have even more power if we use Scheme.  For a full explanation
+of this, see the @ref{Scheme tutorial}, and
+@ruser{Interfaces for programmers}.
+
+We can use Scheme to simply @code{\override} commands,
+
+TODO Find a simple example
+@c This isn't a valid example with skylining
+@c It works fine without padText  -td
+
+@ignore
+@lilypond[quote,verbatim,ragged-right]
+padText = #(define-music-function (parser location padding) (number?)
+#{
+  \once \override TextScript #'padding = #$padding
+#})
+
+\relative c''' {
+  c4^"piu mosso" b a b
+  \padText #1.8
+  c4^"piu mosso" d e f
+  \padText #2.6
+  c4^"piu mosso" fis a g
+}
+@end lilypond
+@end ignore
+
+We can use it to create new commands:
+
+@c Check this is a valid example with skylining
+@c It is - 'padding still works
+
+
+@lilypond[quote,verbatim,ragged-right]
+tempoPadded = #(define-music-function (parser location padding tempotext)
+  (number? string?)
+#{
+  \once \override Score.MetronomeMark #'padding = $padding
+  \tempo \markup { \bold $tempotext }
+#})
+
+\relative c'' {
+  \tempo \markup { "Low tempo" }
+  c4 d e f g1
+  \tempoPadded #4.0 #"High tempo"
+  g4 f e d c1
+}
+@end lilypond
+
+
+Even music expressions can be passed in:
+
+@lilypond[quote,verbatim,ragged-right]
+pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
+#{
+  $x e8 a b $y b a e
+#})
+
+\relative c''{
+  \pattern c8 c8\f
+  \pattern {d16 dis} { ais16-> b\p }
+}
+@end lilypond
+
+
+
+
+
diff --git a/Documentation/learning/scheme-tutorial.itely b/Documentation/learning/scheme-tutorial.itely
deleted file mode 100644
index 20455abcc5..0000000000
--- a/Documentation/learning/scheme-tutorial.itely
+++ /dev/null
@@ -1,337 +0,0 @@
-@c -*- coding: utf-8; mode: texinfo; -*-
-
-@ignore
-    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-
-    When revising a translation, copy the HEAD committish of the
-    version that you are working on.  See TRANSLATION for details.
-@end ignore
-
-@c \version "2.12.0"
-
-@node Scheme tutorial
-@appendix Scheme tutorial
-
-@funindex #
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
-
-LilyPond uses the Scheme programming language, both as part of the
-input syntax, and as internal mechanism to glue modules of the program
-together.  This section is a very brief overview of entering data in
-Scheme.  If you want to know more about Scheme, see
-@uref{http://@/www@/.schemers@/.org}.
-
-LilyPond uses the GNU Guile implementation of Scheme, which is
-based on the Scheme @qq{R5RS} standard. If you are learning Scheme
-to use with LilyPond, working with a different implementation (or
-referring to a different standard) is not recommended. Information
-on guile can be found at @uref{http://www.gnu.org/software/guile/}.
-The @qq{R5RS} Scheme standard is located at
-@uref{http://www.schemers.org/Documents/Standards/R5RS/}.
-
-The LilyPond installation also includes the Guile implementation of
-Scheme.  On most systems you can experiment in a Scheme sandbox by
-opening a terminal window and typing @q{guile}.  On some systems,
-notably Windows, you may need to set the environment variable
-@code{GUILE_LOAD_PATH} to the directory @code{../usr/shr/guile/1.8}
-in the LilyPond installation (for the full path to this directory
-see @ref{Other sources of information}).  Alternatively, Windows
-users may simply choose @q{Run} from the Start menu and enter
-@q{guile}.
-
-The most basic concept in a language is data typing: numbers, character
-strings, lists, etc.  Here is a list of data types that are relevant to
-LilyPond input.
-
-@table @asis
-@item Booleans
-Boolean values are True or False.  The Scheme for True is @code{#t}
-and False is @code{#f}.
-@funindex ##t
-@funindex ##f
-
-@item Numbers
-Numbers are entered in the standard fashion,
-@code{1} is the (integer) number one, while @code{-1.5} is a
-floating point number (a non-integer number).
-
-@item Strings
-Strings are enclosed in double quotes,
-
-@example
-"this is a string"
-@end example
-
-Strings may span several lines
-
-@example
-"this
-is
-a string"
-@end example
-
-Quotation marks and newlines can also be added with so-called escape
-sequences.  The string @code{a said "b"} is entered as
-
-@example
-"a said \"b\""
-@end example
-
-Newlines and backslashes are escaped with @code{\n} and @code{\\}
-respectively.
-@end table
-
-
-In a music file, snippets of Scheme code are introduced with the hash
-mark @code{#}.  So, the previous examples translated to LilyPond are
-
-@example
-##t ##f
-#1 #-1.5
-#"this is a string"
-#"this
-is
-a string"
-@end example
-
-Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
-be used within Scheme code.  Comments in Guile Scheme are entered
-as follows:
-
-@example
-; this is a single-line comment
-
-#!
-  This a (non-nestable) Guile-style block comment
-  But these are rarely used by Schemers and never in
-  LilyPond source code
-!#
-@end example
-
-Multiple consecutive scheme expressions in a music file can be
-combined using the @code{begin} operator. This permits the number
-of hash marks to be reduced to one.
-
-@example
-#(begin
-  (define foo 0)
-  (define bar 1))
-@end example
-
-If @code{#} is followed by an opening bracket, @code{(}, as in
-the example above, the parser will remain in Scheme mode until
-a matching closing bracket, @code{)}, is found, so further
-@code{#} symbols to introduce a Scheme section are not required.
-
-For the rest of this section, we will assume that the data is entered
-in a music file, so we add @code{#}s everywhere.
-
-Scheme can be used to do calculations.  It uses @emph{prefix}
-syntax.  Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
-traditional @math{1+2}.
-
-@lisp
-#(+ 1 2)
-  @result{} #3
-@end lisp
-
-The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
-is@tie{}@code{3}.  Calculations may be nested; the result of a function may
-be used for another calculation.
-
-@lisp
-#(+ 1 (* 3 4))
-  @result{} #(+ 1 12)
-  @result{} #13
-@end lisp
-
-These calculations are examples of evaluations; an expression like
-@code{(* 3 4)} is replaced by its value @code{12}.  A similar thing
-happens with variables.  After defining a variable
-
-@example
-twelve = #12
-@end example
-
-@noindent
-variables can also be used in expressions, here
-
-@example
-twentyFour = #(* 2 twelve)
-@end example
-
-@noindent
-the number 24 is stored in the variable @code{twentyFour}.
-The same assignment can be done in completely in Scheme as well,
-
-@example
-#(define twentyFour (* 2 twelve))
-@end example
-
-The @emph{name} of a variable is also an expression, similar to a
-number or a string.  It is entered as
-
-@example
-#'twentyFour
-@end example
-
-@funindex #'symbol
-@cindex quoting in Scheme
-
-The quote mark @code{'} prevents the Scheme interpreter from substituting
-@code{24} for the @code{twentyFour}.  Instead, we get the name
-@code{twentyFour}.
-
-This syntax will be used very frequently, since many of the layout
-tweaks involve assigning (Scheme) values to internal variables, for
-example
-
-@example
-\override Stem #'thickness = #2.6
-@end example
-
-This instruction adjusts the appearance of stems.  The value @code{2.6}
-is put into the @code{thickness} variable of a @code{Stem}
-object.  @code{thickness} is measured relative to the thickness of
-staff lines, so these stem lines will be @code{2.6} times the
-width of staff lines.  This makes stems almost twice as thick as their
-normal size.  To distinguish between variables defined in input files (like
-@code{twentyFour} in the example above) and variables of internal
-objects, we will call the latter @q{properties} and the former
-@q{variables.}  So, the stem object has a @code{thickness} property,
-while @code{twentyFour} is an variable.
-
-@cindex properties vs. variables
-@cindex variables vs. properties
-
-Two-dimensional offsets (X and Y coordinates) as well as object sizes
-(intervals with a left and right point) are entered as @code{pairs}.  A
-pair@footnote{In Scheme terminology, the pair is called @code{cons},
-and its two elements are called @code{car} and @code{cdr} respectively.}
-is entered as @code{(first . second)} and, like symbols, they must be quoted,
-
-@example
-\override TextScript #'extra-offset = #'(1 . 2)
-@end example
-
-This assigns the pair (1, 2) to the @code{extra-offset} property of the
-TextScript object.  These numbers are measured in staff-spaces, so
-this command moves the object 1 staff space to the right, and 2 spaces up.
-
-The two elements of a pair may be arbitrary values, for example
-
-@example
-#'(1 . 2)
-#'(#t . #f)
-#'("blah-blah" . 3.14159265)
-@end example
-
-A list is entered by enclosing its elements in parentheses, and adding
-a quote.  For example,
-
-@example
-#'(1 2 3)
-#'(1 2 "string" #f)
-@end example
-
-We have been using lists all along.  A calculation, like @code{(+ 1 2)}
-is also a list (containing the symbol @code{+} and the numbers 1
-and@tie{}2).  Normally lists are interpreted as calculations, and the
-Scheme interpreter substitutes the outcome of the calculation.  To enter a
-list, we stop the evaluation.  This is done by quoting the list with a
-quote @code{'} symbol.  So, for calculations do not use a quote.
-
-Inside a quoted list or pair, there is no need to quote anymore.  The
-following is a pair of symbols, a list of symbols and a list of lists
-respectively,
-
-@example
-#'(stem . head)
-#'(staff clef key-signature)
-#'((1) (2))
-@end example
-
-
-@menu
-* Tweaking with Scheme::
-@end menu
-
-@node Tweaking with Scheme
-@appendixsec Tweaking with Scheme
-
-We have seen how LilyPond output can be heavily modified using
-commands like
-@code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
-we have even more power if we use Scheme.  For a full explanation
-of this, see the @ref{Scheme tutorial}, and
-@ruser{Interfaces for programmers}.
-
-We can use Scheme to simply @code{\override} commands,
-
-TODO Find a simple example
-@c This isn't a valid example with skylining
-@c It works fine without padText  -td
-
-@ignore
-@lilypond[quote,verbatim,ragged-right]
-padText = #(define-music-function (parser location padding) (number?)
-#{
-  \once \override TextScript #'padding = #$padding
-#})
-
-\relative c''' {
-  c4^"piu mosso" b a b
-  \padText #1.8
-  c4^"piu mosso" d e f
-  \padText #2.6
-  c4^"piu mosso" fis a g
-}
-@end lilypond
-@end ignore
-
-We can use it to create new commands:
-
-@c Check this is a valid example with skylining
-@c It is - 'padding still works
-
-
-@lilypond[quote,verbatim,ragged-right]
-tempoPadded = #(define-music-function (parser location padding tempotext)
-  (number? string?)
-#{
-  \once \override Score.MetronomeMark #'padding = $padding
-  \tempo \markup { \bold $tempotext }
-#})
-
-\relative c'' {
-  \tempo \markup { "Low tempo" }
-  c4 d e f g1
-  \tempoPadded #4.0 #"High tempo"
-  g4 f e d c1
-}
-@end lilypond
-
-
-Even music expressions can be passed in:
-
-@lilypond[quote,verbatim,ragged-right]
-pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
-#{
-  $x e8 a b $y b a e
-#})
-
-\relative c''{
-  \pattern c8 c8\f
-  \pattern {d16 dis} { ais16-> b\p }
-}
-@end lilypond
-
-
-
-
-