From 9208be1ab745d2cf05b8fd4176924ef3f092e6b5 Mon Sep 17 00:00:00 2001
From: hanwen <hanwen>
Date: Sun, 7 Mar 2004 00:13:44 +0000
Subject: [PATCH] * Documentation/user/changing-defaults.itely (Changing
defaults): new file.
* Documentation/user/notation.itely (Notation manual): rename from
refman.itely
* Documentation/user/notation-appendices.itely (The Feta font):
new file.
* Documentation/user/advanced.itely: add aborted attempt for
advanced topics manual.
---
ChangeLog | 19 +
Documentation/user/advanced.itely | 175 ++++
...{running.itely => changing-defaults.itely} | 762 ++++++++------
Documentation/user/internals.itely | 966 ------------------
Documentation/user/introduction.itely | 5 +-
Documentation/user/invoking.itexi | 1 +
Documentation/user/lilypond.tely | 20 +-
Documentation/user/literature.itely | 2 +-
Documentation/user/music-glossary.tely | 2 +-
...ndices.itely => notation-appendices.itely} | 38 +-
.../user/{refman.itely => notation.itely} | 94 +-
.../user/programming-interface.itely | 510 +++++++++
Documentation/user/tutorial.itely | 4 +-
make/lilypond.redhat.spec.in | 4 +-
scm/define-markup-commands.scm | 2 +-
scm/documentation-generate.scm | 51 +-
scm/new-markup.scm | 37 +
17 files changed, 1332 insertions(+), 1360 deletions(-)
create mode 100644 Documentation/user/advanced.itely
rename Documentation/user/{running.itely => changing-defaults.itely} (71%)
delete mode 100644 Documentation/user/internals.itely
rename Documentation/user/{appendices.itely => notation-appendices.itely} (83%)
rename Documentation/user/{refman.itely => notation.itely} (98%)
create mode 100644 Documentation/user/programming-interface.itely
diff --git a/ChangeLog b/ChangeLog
index dcf795a3d0..d5b68ddb60 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,22 @@
+2004-03-07 Han-Wen Nienhuys <hanwen@xs4all.nl>
+
+ * Documentation/user/changing-defaults.itely (Changing defaults):
+ new file.
+
+ * Documentation/user/notation.itely (Notation manual): rename from
+ refman.itely
+
+ * Documentation/user/notation-appendices.itely (The Feta font):
+ new file.
+
+ * Documentation/user/advanced.itely: add aborted attempt for
+ advanced topics manual.
+
+2004-03-06 Han-Wen Nienhuys <hanwen@xs4all.nl>
+
+ * scm/new-markup.scm: display Markups in sane format. Patch by
+ Nicolas Sceaux.
+
2004-03-05 Jan Nieuwenhuizen <janneke@gnu.org>
* lily/main.cc: Cleanups.
diff --git a/Documentation/user/advanced.itely b/Documentation/user/advanced.itely
new file mode 100644
index 0000000000..33b0df372a
--- /dev/null
+++ b/Documentation/user/advanced.itely
@@ -0,0 +1,175 @@
+@c UNUSED !! -*-texinfo-*-
+
+@node Advanced concepts
+@section Advanced concepts
+
+
+Although LilyPond was designed to produce standard music notation, its
+architecture is flexible, and it is possible to manipulate the
+translation from a @file{.ly} file to a PDF file in many ways. This
+chapter discusses outlines the options for customization.
+
+Before we can explain what is possible, it it is necessary to
+understand the general architecture of LilyPond. The following
+diagram shows the different steps in producing a PDF file:
+
+@verbatim
+
+ Parsing Interpretation Formatting
+
+.ly file -> Music -> Notation ->
+
+
+ Formatting Dumping Titling
+
+ -> Typography -> .tex -> .pdf file
+
+@end verbatim
+
+@enumerate
+
+@item @emph{Parsing} means reading a file, and translating letters and
+ numbers into data structures.
+
+@item The central data structure is the @emph{Music} expression. It is
+the structure that stores music events (notes, chords, lyric
+syllables, etc.) and their combinations.
+
+@item In order to print a piece music, separate events have to be
+synchronized. For example, notes that sound together must be combined
+horizontally, while syllables must be combined on a line. This happens
+in the @emph{interpretating} step.
+
+@item The result of @emph{interpreting} is @emph{notation}, a
+collection of layout objects.
+
+@item The exact appearance of the layout objects is determined during
+@emph{formatting}. For example, in this step spacing and beam slopes
+are determined.
+
+@item After formatting, LilyPond dumps a @TeX{} file containing the
+symbols and their offsets.
+
+@item In a final step, titles are added to the music, resulting in a
+PostScript, DVI or PDF file.
+
+@end enumerate
+
+This chapter discusses Steps@tie{}1. to@tie{}4. Step@tie{}5 is
+discussed in @ref{Tuning output}, while Step@tie{}6 is discussed in
+@ref{Invoking LilyPond}.
+
+The diagram above shows how music typesetting has been split-up in
+multiple subproblems. However, splitting up problems always produces
+the new problem of putting together the subsolutions to these
+subproblems. Therefore, we will start our advanced topics class with a
+discussion of the programming language Scheme, which lubricates the
+interactions between different modules of LilyPond.
+
+
+
+@section Scheme in LilyPond
+@node Scheme in LilyPond
+
+LilyPond includes an interpreter for the programming language Scheme,
+a member of the LISP family. This interpreter,
+@uref{GUILE,http://www.gnu.org/software/guile/},
+forms the basis of the
+
+****************************************************************
+
+@c -*-texinfo-*-
+@c Note:
+@c
+@c A menu is needed before every deeper *section nesting of @nodes
+@c Run M-x texinfo-all-menus-update
+@c to automatically fill in these menus
+@c before saving changes
+
+
+@node Technical manual
+@chapter Technical manual
+
+
+When LilyPond is run, it reads music from a file, translates that into
+notation, and outputs the result to a file. The most important steps
+are the first three. Consequently, there are three important basic
+concepts within LilyPond: music, translation and layout. The
+following diagram illustrates the concepts, and list the terminology
+associated with each step.
+
+
+@verbatim
+
+ +-------------+ Translation +----------+
+ | | | |
+ | Music | ------------------> | Layout |
+ | | | |
+ +-------------+ +----------+
+
+
+Syntax: c4 \context \set #'padding =
+ \override
+
+Objects: Music expressions Contexts Layout object
+ Engravers (aka. Grob)
+
+Example objects: NoteEvent Voice NoteHead
+ Note_heads_engraver
+
+Example properties: #'pitch keySignature #'line-count
+
+User applications: none various tuning layout
+
+@end verbatim
+
+The objects passed around in LilyPond have @emph{properties},
+variables that can contain many different types of information. Users
+can set these variables, to modify the default behavior. Since there
+are three different main concepts, there are also three types of
+properties:
+
+@cindex properties
+@cindex concepts, main
+@cindex context
+@cindex music expressions
+@cindex layout
+@cindex grob
+
+
+@table @b
+@item Music properties
+These are used internally, and most users will not see or use them.
+
+They use Scheme-style naming, i.e. lowercase words separated with
+dashes: @code{pitch}, @code{tremolo-type}.
+
+@item Translation properties
+These influence the translation process, and most users will encounter them
+regularly. For example, beaming behavior is tuned with
+@code{autoBeamSettings}.
+
+These use mixed-caps naming: @code{autoBeamSettings},
+@code{ignoreMelismata}. They are assigned as follows:
+@example
+ \set ignoreMelismata = ...
+@end example
+
+@item Layout properties
+These are internally used in the formatting process. Consequently, to
+tune formatting details, it is necessary to adjust these
+properties. For example, some objects may be moved around vertically
+by setting their @code{padding} property.
+
+These properties use Scheme-style naming: @code{c0-position},
+@code{break-align-symbol}. They most often assigned as follows:
+
+@example
+ \override Score.RehearsalMark #'break-align-symbol = ...
+@end example
+
+@noindent
+Here, @code{RehearsalMark} is the type of the layout object.
+
+@end table
+
diff --git a/Documentation/user/running.itely b/Documentation/user/changing-defaults.itely
similarity index 71%
rename from Documentation/user/running.itely
rename to Documentation/user/changing-defaults.itely
index e0395c30af..7d5fd57dcb 100644
--- a/Documentation/user/running.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -1,15 +1,66 @@
-@node Using LilyPond
-@chapter Using LilyPond
+@c -*-texinfo-*-
+@node Changing defaults
+@chapter Changing defaults
+
+TODO: reorganise.
+
+@menu
+* Scheme integration::
+* Setting variables::
+* Fine tuning layout::
+* Tuning output::
+* Text markup::
+* Global layout::
+* Interpretation context::
+* Output details::
+@end menu
+
+
+
+@node Scheme integration
+@section Scheme integration
+
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+@cindex accessing Scheme
+@cindex evaluating Scheme
+@cindex LISP
+
+LilyPond internally uses GUILE, a Scheme-interpreter, to represent
+data throughout the whole program, and glue together different program
+modules. For advanced usage, it is sometimes necessary to access and
+program the Scheme interpreter.
+
+Scheme is a full-blown programming language, from the LISP
+family. and a full discussion is outside the scope of this document.
+Interested readers are referred to the website
+@uref{http://www.schemers.org/} for more information on Scheme.
+
+The GUILE library for extension is documented at
+@uref{http://www.gnu.org/software/guile}.
+@ifinfo
+When it is installed, the following link should take you to its manual
+@ref{(guile.info)guile}
+@end ifinfo
@menu
-* Setting variables::
-* Fine tuning layout::
-* Tuning output::
-* Text markup::
-* Global layout::
-* Sound::
+* Inline Scheme::
@end menu
+@node Inline Scheme
+@subsection Inline Scheme
+
+Scheme expressions can be entered in the input file by entering a
+hash-sign (@code{#}). The expression following the hash-sign is
+evaluated as Scheme. For example, the boolean value @var{true} is
+@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
+and can be used in property assignments:
+@example
+ \set Staff.autoBeaming = ##f
+@end example
+
+
@node Setting variables
@section Setting variables
@@ -253,15 +304,10 @@ layout property name:
#'layout-property-name
@end example
-@seealso
-
-The introduction of the @ref{Technical manual} gives a more in-depth
-treatment of the difference between translation and layout.
@menu
* Tuning objects::
* Constructing a tweak::
-* Applyoutput::
* Font selection::
@end menu
@@ -526,44 +572,6 @@ Internals: the program reference also contains alphabetical lists of
to tweak by browsing the internals document.
-@node Applyoutput
-@subsection Applyoutput
-
-The most versatile way of tuning an object is @code{\applyoutput}. Its
-syntax is
-@example
-\applyoutput @var{proc}
-@end example
-
-@noindent
-where @var{proc} is a Scheme function, taking three arguments.
-
-When interpreted, the function @var{proc} is called for every layout
-object found in the context, with the following arguments:
-@itemize @bullet
-@item the layout object itself,
-@item the context where the layout object was created, and
-@item the context where @code{\applyoutput} is processed.
-@end itemize
-
-
-In addition, the cause of the layout object, i.e. the music
-expression or object that was responsible for creating it, is in the
-object property @code{cause}. For example, for a note head, this is a
-@internalsref{NoteHead} event, and for a @internalsref{Stem} object,
-this is a @internalsref{NoteHead} object.
-
-Here is a simple example of @code{\applyoutput}; it blanks note-heads on the
-center-line:
-@example
-(define (blanker grob grob-origin context)
- (if (and (memq (ly:grob-property grob 'interfaces)
- note-head-interface)
- (eq? (ly:grob-property grob 'staff-position) 0))
-
- (ly:grob-set-property! grob 'transparent #t)))
-@end example
-
@node Font selection
@@ -777,8 +785,6 @@ for formatting.
@menu
* Overview of text markup commands::
-* Markup construction in scheme::
-* Markup command definition::
@end menu
@node Overview of text markup commands
@@ -786,209 +792,6 @@ for formatting.
@include markup-commands.tely
-@node Markup construction in scheme
-@subsection Markup construction in scheme
-
-@cindex defining markup commands
-
-The @code{markup} macro builds markup expressions in Scheme while
-providing a LilyPond-like syntax. For example,
-@example
-(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
- #:bigger #:line ("foo" "bar" "baz")))
-@end example
-
-@noindent
-is equivalent to:
-@example
-\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
- \bigger @{ foo bar baz @} >
-@end example
-
-@noindent
-This example exposes the main translation rules between regular
-LilyPond markup syntax and scheme markup syntax, which are summed up
-is this table:
-@multitable @columnfractions .5 .5
-@item @b{LilyPond} @tab @b{Scheme}
-@item @code{\command} @tab @code{#:command}
-@item @code{\variable} @tab @code{variable}
-@item @code{@{ ... @}} @tab @code{#:line ( ... )}
-@item @code{\center-align < ... >} @tab @code{#:center ( ... )}
-@item @code{string} @tab @code{"string"}
-@item @code{#scheme-arg} @tab @code{scheme-arg}
-@end multitable
-
-Besides, the whole scheme language is accessible inside the
-@code{markup} macro: thus, one may use function calls inside
-@code{markup} in order to manipulate character strings for
-instance. This proves useful when defining new markup commands (see
-@ref{Markup command definition}).
-
-@refbugs
-
-One can not feed the @code{#:line} (resp @code{#:center},
-@code{#:column}) command with a variable or the result of a function
-call. Eg:
-@lisp
-(markup #:line (fun-that-returns-markups))
-@end lisp
-is illegal. One should use the @code{make-line-markup} (resp
-@code{make-center-markup}, @code{make-column-markup}) function
-instead:
-@lisp
-(markup (make-line-markup (fun-that-returns-markups)))
-@end lisp
-
-@node Markup command definition
-@subsection Markup command definition
-
-New markup commands can be defined thanks to the @code{def-markup-command} scheme macro.
-@lisp
-(def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...)
- (@var{arg1-type?} @var{arg2-type?} ...)
- ..command body..)
-
- @var{argi}: i@var{th} command argument
- @var{argi-type?}: a type predicate for the i@var{th} argument
- @var{paper}: the `paper' definition
- @var{props}: a list of alists, containing all active properties.
-@end lisp
-
-As a simple example, we show how to add a @code{\smallcaps} command,
-which selects @TeX{}'s small caps font. Normally, we could select the
-small caps font as follows:
-
-@verbatim
- \markup { \override #'(font-shape . caps) Text-in-caps }
-@end verbatim
-
-This selects the caps font by setting the @code{font-shape} property to
-@code{#'caps} for interpreting @code{Text-in-caps}.
-
-To make the above available as @code{\smallcaps} command, we have to
-define a function using @code{def-markup-command}. The command should
-take a single argument, of markup type. Therefore, the start of the
-definition should read
-@example
- (def-markup-command (smallcaps paper props argument) (markup?)
-@end example
-
-@noindent
-
-What follows is the content of the command: we should interpret
-the @code{argument} as a markup, i.e.
-
-@example
- (interpret-markup paper @dots{} argument)
-@end example
-
-@noindent
-This interpretation should add @code{'(font-shape . caps)} to the active
-properties, so we substitute the the following for the @dots{} in the
-above example:
-
-@example
- (cons (list '(font-shape . caps) ) props)
-@end example
-
-@noindent
-The variable @code{props} is a list of alists, and we prepend to it by
-consing a list with the extra setting.
-
-However, suppose that we are using a font that does not have a
-small-caps variant. In that case, we have to fake the small caps font,
-by setting a string in upcase, with the first letter a little larger:
-
-@example
-#(def-markup-command (smallcaps paper props str) (string?)
- "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
- (interpret-markup paper props
- (make-line-markup
- (map (lambda (s)
- (if (= (string-length s) 0)
- s
- (markup #:large (string-upcase (substring s 0 1))
- #:translate (cons -0.6 0)
- #:tiny (string-upcase (substring s 1)))))
- (string-split str #\Space)))))
-@end example
-
-The @code{smallcaps} command first splits its string argument into
-tokens separated by spaces (@code{(string-split str #\Space)}); for
-each token, a markup is built with the first letter made large and
-upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
-second markup built with the following letters made tiny and upcased
-(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
-introduces a space between markups on a line, the second markup is
-translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
-the markups built for each token are put in a line
-(@code{(make-line-markup ...)}). Finally, the resulting markup is
-passed to the @code{interpret-markup} function, with the @code{paper}
-and @code{props} arguments.
-
-Finally, suppose that we are typesetting a recitative in an opera, and
-we would like to define a command that will show character names in a
-custom manner. Names should be printed with small caps and translated a
-bit to the left and top. We will define a @code{\character} command
-that takes into account the needed translation, and uses the newly
-defined @code{\smallcaps} command:
-
-@verbatim
-#(def-markup-command (character paper props name) (string?)
- "Print the character name in small caps, translated to the left and
- top. Syntax: \\character #\"name\""
- (interpret-markup paper props
- (markup "" #:translate (cons -4 2) #:smallcaps name)))
-@end verbatim
-
-There is one complication that needs explanation: texts above and below
-the staff are moved vertically to be at a certain distance (the
-@code{padding} property) from the staff and the notes. To make sure
-that this mechanism does not annihilate the vertical effect of our
-@code{#:translate}, we add an empty string (@code{""}) before the
-translated text. Now the @code{""} will be put above the notes, and the
-@code{name} is moved in relation to that empty string. The net effect is
-that the text is moved to the upper left.
-
-The final result is as follows:
-@verbatim
-\score {
- \notes { \fatText
- c''^\markup \character #"Cleopatra"
- e'^\markup \character #"Giulio Cesare"
- }
-}
-@end verbatim
-
-@lilypond[raggedright]
-#(def-markup-command (smallcaps paper props str) (string?)
- "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
- (interpret-markup paper props
- (make-line-markup
- (map (lambda (s)
- (if (= (string-length s) 0)
- s
- (markup #:large (string-upcase (substring s 0 1))
- #:translate (cons -0.6 0)
- #:tiny (string-upcase (substring s 1)))))
- (string-split str #\Space)))))
-
-#(def-markup-command (character paper props name) (string?)
- "Print the character name in small caps, translated to the left and
- top. Syntax: \\character #\"name\""
- (interpret-markup paper props
- (markup "" #:translate (cons -4 0) #:smallcaps name)))
-
-\score {
- \notes { \fatText
- c''^\markup \character #"Cleopatra"
- e'^\markup \character #"Giulio Cesare"
- }
-}
-@end lilypond
-
-
@node Global layout
@section Global layout
@@ -1396,89 +1199,428 @@ LilyPond has no concept of page layout, which makes it difficult to
reliably choose page breaks in longer pieces.
+@node Interpretation context
+@section Interpretation context
+@menu
+* Creating contexts::
+* Default contexts::
+* Context properties::
+* Defining contexts::
+* Changing contexts locally::
+* Engravers and performers::
+* Defining new contexts::
+@end menu
-@node Sound
-@section Sound
-@cindex Sound
-Entered music can also be converted to MIDI output. The performance
-is good enough for proof-hearing the music for errors.
+Interpretation contexts are objects that only exist during program
+run. During the interpretation phase (when @code{interpreting music}
+is printed on the standard output), the music expression in a
+@code{\score} block is interpreted in time order, the same order in
+which we hear and play the music. During this phase, the interpretation
+context holds the state for the current point within the music, for
+example:
+@itemize @bullet
+@item What notes are playing at this point?
-Ties, dynamics and tempo changes are interpreted. Dynamic marks,
-crescendi and decrescendi translate into MIDI volume levels. Dynamic
-marks translate to a fixed fraction of the available MIDI volume
-range, crescendi and decrescendi make the volume vary linearly between
-their two extremities. The fractions can be adjusted by
-@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
-For each type of MIDI instrument, a volume range can be defined. This
-gives a basic equalizer control, which can enhance the quality of
-the MIDI output remarkably. The equalizer can be controlled by
-setting @code{instrumentEqualizer}.
+@item What symbols will be printed at this point?
-@refbugs
+@item What is the current key signature, time signature, point within
+the measure, etc.?
+@end itemize
-Many musically interesting effects, such as swing, articulation,
-slurring, etc., are not translated to MIDI.
+Contexts are grouped hierarchically: A @internalsref{Voice} context is
+contained in a @internalsref{Staff} context (because a staff can contain
+multiple voices at any point), a @internalsref{Staff} context is contained in
+@internalsref{Score}, @internalsref{StaffGroup}, or
+@internalsref{ChoirStaff} context.
-Since slurs are not interpreted, @code{\lyricsto} and
-@code{\addlyrics} sections will be interpreted wrongly.
+Contexts associated with sheet music output are called @emph{notation
+contexts}, those for sound output are called @emph{performance
+contexts}. The default definitions of the standard notation and
+performance contexts can be found in @file{ly/engraver-init.ly} and
+@file{ly/performer-init.ly}, respectively.
-The MIDI output allocates a channel for each Staff, and one for global
-settings. Hence, the MIDI file should not have more than 15 staves
-(or 14 if you do not use drums).
+@node Creating contexts
+@subsection Creating contexts
+@cindex @code{\context}
+@cindex context selection
-@menu
-* MIDI block::
-* MIDI instrument names::
-@end menu
+Contexts for a music expression can be selected manually, using one of
+the following music expressions:
+
+@example
+\new @var{contexttype} @var{musicexpr}
+\context @var{contexttype} [= @var{contextname}] @var{musicexpr}
+@end example
+
+@noindent
+This means that @var{musicexpr} should be interpreted within a context
+of type @var{contexttype} (with name @var{contextname} if specified).
+If no such context exists, it will be created:
+@lilypond[verbatim,raggedright]
+\score {
+ \notes \relative c'' {
+ c4 <<d4 \context Staff = "another" e4>> f
+ }
+}
+@end lilypond
-@node MIDI block
-@subsection MIDI block
-@cindex MIDI block
+@noindent
+In this example, the @code{c} and @code{d} are printed on the default
+staff. For the @code{e}, a context @code{Staff} called @code{another}
+is specified; since that does not exist, a new context is created.
+Within @code{another}, a (default) Voice context is created for the
+@code{e4}. A context is ended when when all music referring it has
+finished, so after the third quarter, @code{another} is removed.
+The @code{\new} construction creates a context with a
+generated, unique @var{contextname}. An expression with
+@code{\new} always leads to a new context. This is convenient
+for creating multiple staffs, multiple lyric lines, etc.
-The MIDI block is analogous to the paper block, but it is somewhat
-simpler. The @code{\midi} block can contain:
-@cindex MIDI block
+When using automatic staff changes, automatic phrasing, etc., the
+context names have special meanings, so @code{\new} cannot be
+used.
-@itemize @bullet
- @item a @code{\tempo} definition, and
- @item context definitions.
-@end itemize
-Assignments in the @code{\midi} block are not allowed.
+@node Default contexts
+@subsection Default contexts
-A number followed by a period is interpreted as a real number, so
-for setting the tempo for dotted notes, an extra space should be
-inserted, for example:
+Every top level music is interpreted by the @code{Score} context; in
+other words, you may think of @code{\score} working like
@example
- \midi @{ \tempo 4 . = 120 @}
+\score @{
+ \context Score @var{music}
+@}
@end example
+Music expressions inherit their context from the enclosing music
+expression. Hence, it is not necessary to explicitly specify
+@code{\context} for most expressions. In
+the following example, only the sequential expression has an explicit
+context. The notes contained therein inherit the @code{goUp} context
+from the enclosing music expression.
+
+@lilypond[verbatim,raggedright]
+ \notes \context Voice = goUp { c'4 d' e' }
+@end lilypond
+
+
+Second, contexts are created automatically to be able to interpret the
+music expressions. Consider the following example:
+
+@lilypond[verbatim,raggedright]
+ \score { \notes { c'4-( d' e'-) } }
+@end lilypond
+
+@noindent
+The sequential music is interpreted by the Score context initially,
+but when a note is encountered, contexts are setup to accept that
+note. In this case, a @code{Voice}, and @code{Staff}
+context are created. The rest of the sequential music is also
+interpreted with the same @code{Voice}, and
+@code{Staff} context, putting the notes on the same staff, in the same
+voice.
+
+@node Context properties
+@subsection Context properties
+
+Contexts have properties. These properties are set from the @file{.ly}
+file using the following expression:
+@cindex context properties
+@cindex properties, context
+
+@example
+\set @var{contextname}.@var{propname} = @var{value}
+@end example
+
+@noindent
+Sets the @var{propname} property of the context @var{contextname} to
+the specified Scheme expression @var{value}. Both @var{propname} and
+@var{contextname} are strings, which can often be written unquoted.
+
+@cindex inheriting
+Properties that are set in one context are inherited by all of the
+contained contexts. This means that a property valid for the
+@internalsref{Voice} context can be set in the @internalsref{Score} context
+(for example) and thus take effect in all @internalsref{Voice} contexts.
+
+Properties can be unset using the following statement.
+@example
+\unset @var{contextname}.@var{propname}
+@end example
+
+@cindex properties, unsetting
+@cindex @code{\unset}
+
+@noindent
+This removes the definition of @var{propname} in @var{contextname}. If
+@var{propname} was not defined in @var{contextname} (but was inherited
+from a higher context), then this has no effect.
+
+If @var{contextname} is left out, then it defaults to the current
+``bottom'' context: this is a context like @internalsref{Voice} that
+cannot contain any other contexts.
+
+
+@node Defining contexts
+@subsection Defining contexts
@cindex context definition
+@cindex translator definition
+
+The most common way to create a new context definition is by extending
+an existing one. An existing context from the paper block is copied
+by referencing a context identifier:
+
+@example
+\paper @{
+ \translator @{
+ @var{context-identifier}
+ @}
+@}
+@end example
+
+@noindent
+Every predefined context has a standard identifier. For example, the
+@code{Staff} context can be referred to as @code{\StaffContext}.
+
+The context can then be modified by setting or changing properties,
+e.g.
+@example
+\translator @{
+ \StaffContext
+ Stem \set #'thickness = #2.0
+ defaultBarType = #"||"
+@}
+@end example
+These assignments happen before interpretation starts, so a property
+command will override any predefined settings.
+
+@cindex engraver
+
+@refbugs
+
+It is not possible to collect multiple property assignments in a
+variable, and apply to one @code{\translator} definition by
+referencing that variable.
+
+@node Changing contexts locally
+@subsection Changing contexts locally
-Context definitions follow precisely the same syntax as within the
-\paper block. Translation modules for sound are called performers.
-The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
+Extending an existing context can also be done locally. A piece of
+music can be interpreted in a changed context by using the following syntax
-@node MIDI instrument names
-@subsection MIDI instrument names
+@example
+ \with @{
+ @var{context modifications}
+ @}
+@end example
-@cindex instrument names
-@cindex @code{Staff.midiInstrument}
+These statements comes between @code{\new} or @code{\context} and the
+music to be interpreted. The @var{context modifications} property
+settings and @code{\remove}, @code{\consists} and @code{\consistsend}
+commands. The syntax is similar to the @code{\translator} block.
-The MIDI instrument name is set by the @code{Staff.midiInstrument}
-property. The instrument name should be chosen from the list in
-@ref{MIDI instruments}.
+The following example shows how a staff is created with bigger spaces,
+and without a @code{Clef_engraver}.
+
+@lilypond[relative=1,fragment,verbatim]
+<<
+ \new Staff { c4 es4 g2 }
+ \new Staff \with {
+ \override StaffSymbol #'staff-space = #(magstep 1.5)
+ fontSize = #1.5
+ \remove "Clef_engraver"
+ } {
+ c4 es4 g2
+ } >>
+@end lilypond
@refbugs
-If the selected string does not exactly match, then the default is
-used, which is the Grand Piano.
+The command @code{\with} has no effect on contexts that already
+exist.
+
+
+@node Engravers and performers
+@subsection Engravers and performers
+
+
+Each context is composed of a number of building blocks, or plug-ins
+called engravers. An engraver is a specialized C++ class that is
+compiled into the executable. Typically, an engraver is responsible
+for one function: the @code{Slur_engraver} creates only @code{Slur}
+objects, and the @code{Skip_event_swallow_translator} only swallows
+(silently gobbles) @code{SkipEvent}s.
+
+
+
+@cindex engraver
+@cindex plug-in
+
+An existing context definition can be changed by adding or removing an
+engraver. The syntax for these operations is
+@example
+\consists @var{engravername}
+\remove @var{engravername}
+@end example
+
+@cindex @code{\consists}
+@cindex @code{\remove}
+
+@noindent
+Here @var{engravername} is a string, the name of an engraver in the
+system. In the following example, the @code{Clef_engraver} is removed
+from the Staff context. The result is a staff without a clef, where
+the middle C is at its default position, the center line:
+
+@lilypond[verbatim,raggedright]
+\score {
+ \notes {
+ c'4 f'4
+ }
+ \paper {
+ \translator {
+ \StaffContext
+ \remove Clef_engraver
+ }
+ }
+}
+@end lilypond
+
+A list of all engravers is in the internal documentation,
+see @internalsref{Engravers}.
+
+@node Defining new contexts
+@subsection Defining new contexts
+
+
+It is also possible to define new contexts from scratch. To do this,
+you must define give the new context a name. In the following
+example, a very simple Staff context is created: one that will put
+note heads on a staff symbol.
+
+@example
+\translator @{
+ \type "Engraver_group_engraver"
+ \name "SimpleStaff"
+ \alias "Staff"
+ \consists "Staff_symbol_engraver"
+ \consists "Note_head_engraver"
+ \consistsend "Axis_group_engraver"
+@}
+@end example
+
+@noindent
+The argument of @code{\type} is the name for a special engraver that
+handles cooperation between simple engravers such as
+@code{Note_head_engraver} and @code{Staff_symbol_engraver}. This
+should always be @code{Engraver_group_engraver} (unless you are
+defining a Score context from scratch, in which case
+@code{Score_engraver} must be used).
+
+The complete list of context modifiers is the following:
+@itemize @bullet
+@item @code{\alias} @var{alternate-name}:
+This specifies a different name. In the above example,
+@code{\set Staff.X = Y} will also work on @code{SimpleStaff}s.
+
+@item @code{\consistsend} @var{engravername}:
+Analogous to @code{\consists}, but makes sure that
+@var{engravername} is always added to the end of the list of
+engravers.
+
+Engravers that group context objects into axis groups or alignments
+need to be at the end of the list. @code{\consistsend} insures that
+engravers stay at the end even if a user adds or removes engravers.
+
+@item @code{\accepts} @var{contextname}:
+This context can contains @var{contextname} contexts. The first
+@code{\accepts} is created as a default context when events (e.g. notes
+or rests) are encountered.
+
+@item @code{\denies}:
+The opposite of @code{\accepts}.
+
+@item @code{\name} @var{contextname}:
+This sets the type name of the context, e.g. @code{Staff},
+@code{Voice}. If the name is not specified, the translator will not
+do anything.
+@end itemize
+
+@c EOF
+
+
+
+
+@node Output details
+@section Output details
+
+The default output format is La@TeX{}, which should be run
+through La@TeX{}. Using the option @option{-f}
+(or @option{--format}) other output formats can be selected also, but
+currently none of them work reliably.
+
+At the beginning of the output file, various global parameters are
+defined. Then the file @file{lilyponddefs.tex} is loaded to define
+the macros used in the code which follows. @file{lilyponddefs.tex}
+includes various other files, partially depending on the global
+parameters.
+
+Now the music is output system by system (a `system' consists of all
+staves belonging together). From @TeX{}'s point of view, a system is an
+@code{\hbox} which contains a lowered @code{\vbox} so that it is centered
+vertically on the baseline of the text. Between systems,
+@code{\interscoreline} is inserted vertically to have stretchable space.
+The horizontal dimension of the @code{\hbox} is given by the
+@code{linewidth} parameter from LilyPond's @code{\paper} block.
+
+After the last system LilyPond emits a stronger variant of
+@code{\interscoreline} only if the macro
+@code{\lilypondpaperlastpagefill} is not defined (flushing the systems
+to the top of the page). You can avoid that by setting the variable
+@code{lastpagefill} in LilyPond's @code{\paper} block.
+
+It is possible to fine-tune the vertical offset further by defining the
+macro @code{\lilypondscoreshift}:
+
+@example
+\def\lilypondscoreshift@{0.25\baselineskip@}
+@end example
+
+@noindent
+where @code{\baselineskip} is the distance from one text line to the next.
+
+Here an example how to embed a small LilyPond file @code{foo.ly} into
+running La@TeX{} text without using the @code{lilypond-book} script
+(@pxref{lilypond-book manual}):
+
+@example
+\documentclass@{article@}
+
+\def\lilypondpaperlastpagefill@{@}
+\lineskip 5pt
+\def\lilypondscoreshift@{0.25\baselineskip@}
+
+\begin@{document@}
+This is running text which includes an example music file
+\input@{foo.tex@}
+right here.
+\end@{document@}
+@end example
+
+The file @file{foo.tex} has been simply produced with
+
+@example
+ lilypond-bin foo.ly
+@end example
+
+The call to @code{\lineskip} assures that there is enough vertical space
+between the LilyPond box and the surrounding text lines.
diff --git a/Documentation/user/internals.itely b/Documentation/user/internals.itely
deleted file mode 100644
index b152463824..0000000000
--- a/Documentation/user/internals.itely
+++ /dev/null
@@ -1,966 +0,0 @@
-@c -*-texinfo-*-
-@c Note:
-@c
-@c A menu is needed before every deeper *section nesting of @nodes
-@c Run M-x texinfo-all-menus-update
-@c to automatically fill in these menus
-@c before saving changes
-
-
-@node Technical manual
-@chapter Technical manual
-
-
-When LilyPond is run, it reads music from a file, translates that into
-notation, and outputs the result to a file. The most important steps
-are the first three. Consequently, there are three important basic
-concepts within LilyPond: music, translation and layout. The
-following diagram illustrates the concepts, and list the terminology
-associated with each step.
-
-
-@verbatim
-
- +-------------+ Translation +----------+
- | | | |
- | Music | ------------------> | Layout |
- | | | |
- +-------------+ +----------+
-
-
-Syntax: c4 \context \set #'padding =
- \override
-
-Objects: Music expressions Contexts Layout object
- Engravers (aka. Grob)
-
-Example objects: NoteEvent Voice NoteHead
- Note_heads_engraver
-
-Example properties: #'pitch keySignature #'line-count
-
-User applications: none various tuning layout
-
-@end verbatim
-
-The objects passed around in LilyPond have @emph{properties},
-variables that can contain many different types of information. Users
-can set these variables, to modify the default behavior. Since there
-are three different main concepts, there are also three types of
-properties:
-
-@cindex properties
-@cindex concepts, main
-@cindex context
-@cindex music expressions
-@cindex layout
-@cindex grob
-
-
-@table @b
-@item Music properties
-These are used internally, and most users will not see or use them.
-
-They use Scheme-style naming, i.e. lowercase words separated with
-dashes: @code{pitch}, @code{tremolo-type}.
-
-@item Translation properties
-These influence the translation process, and most users will encounter them
-regularly. For example, beaming behavior is tuned with
-@code{autoBeamSettings}.
-
-These use mixed-caps naming: @code{autoBeamSettings},
-@code{ignoreMelismata}. They are assigned as follows:
-@example
- \set ignoreMelismata = ...
-@end example
-
-@item Layout properties
-These are internally used in the formatting process. Consequently, to
-tune formatting details, it is necessary to adjust these
-properties. For example, some objects may be moved around vertically
-by setting their @code{padding} property.
-
-These properties use Scheme-style naming: @code{c0-position},
-@code{break-align-symbol}. They most often assigned as follows:
-
-@example
- \override Score.RehearsalMark #'break-align-symbol = ...
-@end example
-
-@noindent
-Here, @code{RehearsalMark} is the type of the layout object.
-
-@end table
-
-This chapter discusses details of the three concepts in more detail,
-and explains how they are glued together in LilyPond with the embedded
-Scheme interpreter.
-
-@menu
-* Interpretation context::
-* Scheme integration::
-* Music storage format::
-* Lexical details::
-* Output details::
-@end menu
-
-
-@node Interpretation context
-@section Interpretation context
-
-@menu
-* Creating contexts::
-* Default contexts::
-* Context properties::
-* Context evaluation::
-* Defining contexts::
-* Changing contexts locally::
-* Engravers and performers::
-* Defining new contexts::
-@end menu
-
-
-Interpretation contexts are objects that only exist during program
-run. During the interpretation phase (when @code{interpreting music}
-is printed on the standard output), the music expression in a
-@code{\score} block is interpreted in time order, the same order in
-which we hear and play the music. During this phase, the interpretation
-context holds the state for the current point within the music, for
-example:
-@itemize @bullet
-@item What notes are playing at this point?
-
-@item What symbols will be printed at this point?
-
-@item What is the current key signature, time signature, point within
-the measure, etc.?
-@end itemize
-
-Contexts are grouped hierarchically: A @internalsref{Voice} context is
-contained in a @internalsref{Staff} context (because a staff can contain
-multiple voices at any point), a @internalsref{Staff} context is contained in
-@internalsref{Score}, @internalsref{StaffGroup}, or
-@internalsref{ChoirStaff} context.
-
-Contexts associated with sheet music output are called @emph{notation
-contexts}, those for sound output are called @emph{performance
-contexts}. The default definitions of the standard notation and
-performance contexts can be found in @file{ly/engraver-init.ly} and
-@file{ly/performer-init.ly}, respectively.
-
-
-@node Creating contexts
-@subsection Creating contexts
-@cindex @code{\context}
-@cindex context selection
-
-Contexts for a music expression can be selected manually, using one of
-the following music expressions:
-
-@example
-\new @var{contexttype} @var{musicexpr}
-\context @var{contexttype} [= @var{contextname}] @var{musicexpr}
-@end example
-
-@noindent
-This means that @var{musicexpr} should be interpreted within a context
-of type @var{contexttype} (with name @var{contextname} if specified).
-If no such context exists, it will be created:
-
-@lilypond[verbatim,raggedright]
-\score {
- \notes \relative c'' {
- c4 <<d4 \context Staff = "another" e4>> f
- }
-}
-@end lilypond
-
-@noindent
-In this example, the @code{c} and @code{d} are printed on the default
-staff. For the @code{e}, a context @code{Staff} called @code{another}
-is specified; since that does not exist, a new context is created.
-Within @code{another}, a (default) Voice context is created for the
-@code{e4}. A context is ended when when all music referring it has
-finished, so after the third quarter, @code{another} is removed.
-
-The @code{\new} construction creates a context with a
-generated, unique @var{contextname}. An expression with
-@code{\new} always leads to a new context. This is convenient
-for creating multiple staffs, multiple lyric lines, etc.
-
-When using automatic staff changes, automatic phrasing, etc., the
-context names have special meanings, so @code{\new} cannot be
-used.
-
-
-@node Default contexts
-@subsection Default contexts
-
-Every top level music is interpreted by the @code{Score} context; in
-other words, you may think of @code{\score} working like
-
-@example
-\score @{
- \context Score @var{music}
-@}
-@end example
-
-Music expressions inherit their context from the enclosing music
-expression. Hence, it is not necessary to explicitly specify
-@code{\context} for most expressions. In
-the following example, only the sequential expression has an explicit
-context. The notes contained therein inherit the @code{goUp} context
-from the enclosing music expression.
-
-@lilypond[verbatim,raggedright]
- \notes \context Voice = goUp { c'4 d' e' }
-@end lilypond
-
-
-Second, contexts are created automatically to be able to interpret the
-music expressions. Consider the following example:
-
-@lilypond[verbatim,raggedright]
- \score { \notes { c'4-( d' e'-) } }
-@end lilypond
-
-@noindent
-The sequential music is interpreted by the Score context initially,
-but when a note is encountered, contexts are setup to accept that
-note. In this case, a @code{Voice}, and @code{Staff}
-context are created. The rest of the sequential music is also
-interpreted with the same @code{Voice}, and
-@code{Staff} context, putting the notes on the same staff, in the same
-voice.
-
-@node Context properties
-@subsection Context properties
-
-Contexts have properties. These properties are set from the @file{.ly}
-file using the following expression:
-@cindex context properties
-@cindex properties, context
-
-@example
-\set @var{contextname}.@var{propname} = @var{value}
-@end example
-
-@noindent
-Sets the @var{propname} property of the context @var{contextname} to
-the specified Scheme expression @var{value}. Both @var{propname} and
-@var{contextname} are strings, which can often be written unquoted.
-
-@cindex inheriting
-Properties that are set in one context are inherited by all of the
-contained contexts. This means that a property valid for the
-@internalsref{Voice} context can be set in the @internalsref{Score} context
-(for example) and thus take effect in all @internalsref{Voice} contexts.
-
-Properties can be unset using the following statement.
-@example
-\unset @var{contextname}.@var{propname}
-@end example
-
-@cindex properties, unsetting
-@cindex @code{\unset}
-
-@noindent
-This removes the definition of @var{propname} in @var{contextname}. If
-@var{propname} was not defined in @var{contextname} (but was inherited
-from a higher context), then this has no effect.
-
-If @var{contextname} is left out, then it defaults to the current
-``bottom'' context: this is a context like @internalsref{Voice} that
-cannot contain any other contexts.
-
-
-
-@node Context evaluation
-@subsection Context evaluation
-
-Contexts can be modified during interpretation with Scheme code. The
-syntax for this is
-@example
- \applycontext @var{function}
-@end example
-
-@var{function} should be a Scheme function taking a single argument,
-being the context to apply it to. The following code will print the
-current bar number on the standard output during the compile:
-
-@example
- \applycontext
- #(lambda (x)
- (format #t "\nWe were called in barnumber ~a.\n"
- (ly:context-property x 'currentBarNumber)))
-@end example
-
-
-
-@node Defining contexts
-@subsection Defining contexts
-
-@cindex context definition
-@cindex translator definition
-
-The most common way to create a new context definition is by extending
-an existing one. An existing context from the paper block is copied
-by referencing a context identifier:
-
-@example
-\paper @{
- \translator @{
- @var{context-identifier}
- @}
-@}
-@end example
-
-@noindent
-Every predefined context has a standard identifier. For example, the
-@code{Staff} context can be referred to as @code{\StaffContext}.
-
-The context can then be modified by setting or changing properties,
-e.g.
-@example
-\translator @{
- \StaffContext
- Stem \set #'thickness = #2.0
- defaultBarType = #"||"
-@}
-@end example
-These assignments happen before interpretation starts, so a property
-command will override any predefined settings.
-
-@cindex engraver
-
-@refbugs
-
-It is not possible to collect multiple property assignments in a
-variable, and apply to one @code{\translator} definition by
-referencing that variable.
-
-@node Changing contexts locally
-@subsection Changing contexts locally
-
-
-Extending an existing context can also be done locally. A piece of
-music can be interpreted in a changed context by using the following syntax
-
-@example
- \with @{
- @var{context modifications}
- @}
-@end example
-
-These statements comes between @code{\new} or @code{\context} and the
-music to be interpreted. The @var{context modifications} property
-settings and @code{\remove}, @code{\consists} and @code{\consistsend}
-commands. The syntax is similar to the @code{\translator} block.
-
-The following example shows how a staff is created with bigger spaces,
-and without a @code{Clef_engraver}.
-
-@lilypond[relative=1,fragment,verbatim]
-<<
- \new Staff { c4 es4 g2 }
- \new Staff \with {
- \override StaffSymbol #'staff-space = #(magstep 1.5)
- fontSize = #1.5
- \remove "Clef_engraver"
- } {
- c4 es4 g2
- } >>
-@end lilypond
-
-@refbugs
-
-The command @code{\with} has no effect on contexts that already
-exist.
-
-
-@node Engravers and performers
-@subsection Engravers and performers
-
-
-Each context is composed of a number of building blocks, or plug-ins
-called engravers. An engraver is a specialized C++ class that is
-compiled into the executable. Typically, an engraver is responsible
-for one function: the @code{Slur_engraver} creates only @code{Slur}
-objects, and the @code{Skip_event_swallow_translator} only swallows
-(silently gobbles) @code{SkipEvent}s.
-
-
-
-@cindex engraver
-@cindex plug-in
-
-An existing context definition can be changed by adding or removing an
-engraver. The syntax for these operations is
-@example
-\consists @var{engravername}
-\remove @var{engravername}
-@end example
-
-@cindex @code{\consists}
-@cindex @code{\remove}
-
-@noindent
-Here @var{engravername} is a string, the name of an engraver in the
-system. In the following example, the @code{Clef_engraver} is removed
-from the Staff context. The result is a staff without a clef, where
-the middle C is at its default position, the center line:
-
-@lilypond[verbatim,raggedright]
-\score {
- \notes {
- c'4 f'4
- }
- \paper {
- \translator {
- \StaffContext
- \remove Clef_engraver
- }
- }
-}
-@end lilypond
-
-A list of all engravers is in the internal documentation,
-see @internalsref{Engravers}.
-
-@node Defining new contexts
-@subsection Defining new contexts
-
-
-It is also possible to define new contexts from scratch. To do this,
-you must define give the new context a name. In the following
-example, a very simple Staff context is created: one that will put
-note heads on a staff symbol.
-
-@example
-\translator @{
- \type "Engraver_group_engraver"
- \name "SimpleStaff"
- \alias "Staff"
- \consists "Staff_symbol_engraver"
- \consists "Note_head_engraver"
- \consistsend "Axis_group_engraver"
-@}
-@end example
-
-@noindent
-The argument of @code{\type} is the name for a special engraver that
-handles cooperation between simple engravers such as
-@code{Note_head_engraver} and @code{Staff_symbol_engraver}. This
-should always be @code{Engraver_group_engraver} (unless you are
-defining a Score context from scratch, in which case
-@code{Score_engraver} must be used).
-
-The complete list of context modifiers is the following:
-@itemize @bullet
-@item @code{\alias} @var{alternate-name}:
-This specifies a different name. In the above example,
-@code{\set Staff.X = Y} will also work on @code{SimpleStaff}s.
-
-@item @code{\consistsend} @var{engravername}:
-Analogous to @code{\consists}, but makes sure that
-@var{engravername} is always added to the end of the list of
-engravers.
-
-Engravers that group context objects into axis groups or alignments
-need to be at the end of the list. @code{\consistsend} insures that
-engravers stay at the end even if a user adds or removes engravers.
-
-@item @code{\accepts} @var{contextname}:
-This context can contains @var{contextname} contexts. The first
-@code{\accepts} is created as a default context when events (e.g. notes
-or rests) are encountered.
-
-@item @code{\denies}:
-The opposite of @code{\accepts}.
-
-@item @code{\name} @var{contextname}:
-This sets the type name of the context, e.g. @code{Staff},
-@code{Voice}. If the name is not specified, the translator will not
-do anything.
-@end itemize
-
-
-@node Scheme integration
-@section Scheme integration
-
-@cindex Scheme
-@cindex GUILE
-@cindex Scheme, in-line code
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
-
-LilyPond internally uses GUILE, a Scheme-interpreter, to represent
-data throughout the whole program, and glue together different program
-modules. For advanced usage, it is sometimes necessary to access and
-program the Scheme interpreter.
-
-Scheme is a full-blown programming language, from the LISP
-family. and a full discussion is outside the scope of this document.
-Interested readers are referred to the website
-@uref{http://www.schemers.org/} for more information on Scheme.
-
-The GUILE library for extension is documented at
-@uref{http://www.gnu.org/software/guile}.
-@ifinfo
-When it is installed, the following link should take you to its manual
-@ref{(guile.info)guile}
-@end ifinfo
-
-@menu
-* Inline Scheme::
-* Input variables and Scheme::
-* Assignments::
-@end menu
-
-@node Inline Scheme
-@subsection Inline Scheme
-
-Scheme expressions can be entered in the input file by entering a
-hash-sign (@code{#}). The expression following the hash-sign is
-evaluated as Scheme. For example, the boolean value @var{true} is
-@code{#t} in Scheme, so for LilyPond @var{true} looks like @code{##t},
-and can be used in property assignments:
-@example
- \set Staff.autoBeaming = ##f
-@end example
-
-
-@node Input variables and Scheme
-@subsection Input variables and Scheme
-
-
-The input format supports the notion of variable: in the following
-example, a music expression is assigned to a variable with the name
-@code{traLaLa}.
-@example
- traLaLa = \notes @{ c'4 d'4 @}
-@end example
-
-@noindent
-
-There is also a form of scoping: in the following example, the
-@code{\paper} block also contains a @code{traLaLa} variable, which is
-independent of the outer @code{\traLaLa}.
-@example
- traLaLa = \notes @{ c'4 d'4 @}
- \paper @{ traLaLa = 1.0 @}
-@end example
-@c
-In effect, each input file is a scope, and all @code{\header},
-@code{\midi} and @code{\paper} blocks are scopes nested inside that
-toplevel scope.
-
-Both variables and scoping are implemented in the GUILE module system.
-An anonymous Scheme module is attached to each scope. An assignment of
-the form
-@example
- traLaLa = \notes @{ c'4 d'4 @}
-@end example
-
-@noindent
-is internally converted to a Scheme definition
-@example
- (define traLaLa @var{Scheme value of ``@code{\notes ... }''})
-@end example
-
-This means that input variables and Scheme variables may be freely
-mixed. In the following example, a music fragment is stored in the
-variable @code{traLaLa}, and duplicated using Scheme. The result is
-imported in a @code{\score} by means of a second variable
-@code{twice}:
-@example
- traLaLa = \notes @{ c'4 d'4 @}
-
- #(define newLa (map ly:music-deep-copy
- (list traLaLa traLaLa)))
- #(define twice
- (make-sequential-music newLa))
-
- \score @{ \twice @}
-@end example
-
-In the above example, music expressions can be `exported' from the
-input to the Scheme interpreter. The opposite is also possible. By
-wrapping a Scheme value in the function @code{ly:export}, a Scheme
-value is interpreted as if it were entered in LilyPond syntax: instead
-of defining @code{\twice}, the example above could also have been
-written as
-@example
- @dots{}
- \score @{ #(ly:export (make-sequential-music newLa)) @}
-@end example
-
-
-
-
-
-@node Assignments
-@subsection Assignments
-@cindex Assignments
-
-Variables allow objects to be assigned to names during the parse
-stage. To assign a variable, use
-@example
-@var{name}@code{=}@var{value}
-@end example
-To refer to a variable, precede its name with a backslash:
-`@code{\}@var{name}'. @var{value} is any valid Scheme value or any of
-the input-types listed above. Variable assignments can appear at top
-level in the LilyPond file, but also in @code{\paper} blocks.
-
-A variable can be created with any string for its name, but for
-accessing it in the LilyPond syntax, its name must consist of
-alphabetic characters only, and may not be a keyword of the syntax.
-There are no restrictions for naming and accessing variables in the
-Scheme interpreter,
-
-The right hand side of a variable assignment is parsed completely
-before the assignment is done, so variables may be redefined in terms
-of its old value, e.g.
-@c
-@example
-foo = \foo * 2.0
-@end example
-
-When a variable is referenced in LilyPond syntax, the information it
-points to is copied. For this reason, a variable reference must
-always be the first item in a block.
-
-@example
-\paper @{
- foo = 1.0
- \paperIdent % wrong and invalid
-@}
-@end example
-
-@example
-\paper @{
- \paperIdent % correct
- foo = 1.0
-@}
-@end example
-
-
-
-@node Music storage format
-@section Music storage format
-
-Music in LilyPond is entered as music expressions. This section
-discusses different types of music expressions, and explains how
-information is stored internally. This internal storage is accessible
-through the Scheme interpreter, so music expressions may be
-manipulated using Scheme functions.
-
-@menu
-* Music expressions::
-* Internal music representation::
-* Manipulating music expressions::
-@end menu
-
-@node Music expressions
-@subsection Music expressions
-@cindex music expressions
-
-Notes, rests, lyric syllables are music expressions. Small music
-expressions may be combined to form larger ones, for example, by
-enclosing a list of expressions in @code{\sequential @{ @}} or @code{<<
->>}. In the following example, a compound expression is formed out of
-the quarter note @code{c} and a quarter note @code{d}:
-
-@example
-\sequential @{ c4 d4 @}
-@end example
-
-@cindex Sequential music
-@cindex @code{\sequential}
-@cindex sequential music
-@cindex @code{<<}
-@cindex @code{>>}
-@cindex Simultaneous music
-@cindex @code{\simultaneous}
-
-The two basic compound music expressions are simultaneous and
-sequential music:
-
-@example
-\sequential @code{@{} @var{musicexprlist} @code{@}}
-\simultaneous @code{@{} @var{musicexprlist} @code{@}}
-@end example
-
-For both, there is a shorthand:
-
-@example
-@code{@{} @var{musicexprlist} @code{@}}
-@end example
-
-@noindent
-for sequential and
-
-@example
-@code{<<} @var{musicexprlist} @code{>>}
-@end example
-
-@noindent
-for simultaneous music.
-In principle, the way in which you nest sequential and simultaneous to
-produce music is not relevant. In the following example, three chords
-are expressed in two different ways:
-
-@lilypond[fragment,verbatim,center]
-\notes \context Voice {
- <<a c'>> <<b d'>> <<c' e'>>
- << { a b c' } { c' d' e' } >>
-}
-@end lilypond
-However, using @code{<<} and @code{>>} for entering chords leads to
-various peculiarities. For this reason, a special syntax
-for chords was introduced in version 1.7: @code{< >}.
-
-
-
-
-
-Other compound music expressions include:
-@example
-\repeat @var{expr}
-\transpose @var{from} @var{to} @var{expr}
-\apply @var{func} @var{expr}
-\context @var{type} = @var{id} @var{expr}
-\times @var{fraction} @var{expr}
-@end example
-
-@node Internal music representation
-@subsection Internal music representation
-
-
-
-
-
-
-When a music expression is parsed, it is converted into a set of
-Scheme music objects. The defining property of a music object is that
-it takes up time. Time is a rational number that measures the length
-of a piece of music, in whole notes.
-
-A music object has three kinds of types:
-@itemize @bullet
-@item
- music name: Each music expression has a name, for example, a note
-leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
-a @internalsref{SimultaneousMusic}. A list of all expressions
-available is in the internals manual, under @internalsref{Music
-expressions}.
-
-@item
- `type' or interface: Each music name has several `types' or interface,
- for example, a note is an @code{event}, but it is also a @code{note-event},
- a @code{rhythmic-event} and a @code{melodic-event}.
-
- All classes of music are listed in the internals manual, under
- @internalsref{Music classes}.
-@item
-C++ object: Each music object is represented by a C++ object. For technical
-reasons, different music objects may be represented by different C++
-object types. For example, a note is @code{Event} object, while
-@code{\grace} creates a @code{Grace_music} object.
-
-We expect that distinctions between different C++ types will disappear
-in the future.
-@end itemize
-
-The actual information of a music expression is stored in properties.
-For example, a @internalsref{NoteEvent} has @code{pitch} and
-@code{duration} properties that store the pitch and duration of that
-note. A list of all properties available is in the internals manual,
-under @internalsref{Music properties}.
-
-A compound music expression is a music object that contains other
-music objects in its properties. A list of objects can be stored in
-the @code{elements} property of a music object, or a single `child'
-music object in the @code{element} object. For example,
-@internalsref{SequentialMusic} has its children in @code{elements},
-and @internalsref{GraceMusic} has its single argument in
-@code{element}. The body of a repeat is in @code{element} property of
-@internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
-
-@node Manipulating music expressions
-@subsection Manipulating music expressions
-
-Music objects and their properties can be accessed and manipulated
-directly, through the @code{\apply} mechanism.
-The syntax for @code{\apply} is
-@example
-\apply #@var{func} @var{music}
-@end example
-
-@noindent
-This means that the scheme function @var{func} is called with
-@var{music} as its argument. The return value of @var{func} is the
-result of the entire expression. @var{func} may read and write music
-properties using the functions @code{ly:music-property} and
-@code{ly:music-set-property!}.
-
-An example is a function that reverses the order of elements in
-its argument:
-@lilypond[verbatim,raggedright]
- #(define (rev-music-1 m)
- (ly:music-set-property! m 'elements (reverse
- (ly:music-property m 'elements)))
- m)
- \score { \notes \apply #rev-music-1 { c4 d4 } }
-@end lilypond
-
-The use of such a function is very limited. The effect of this
-function is void when applied to an argument which is does not have
-multiple children. The following function application has no effect:
-
-@example
- \apply #rev-music-1 \grace @{ c4 d4 @}
-@end example
-
-@noindent
-In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no
-@code{elements}, only a single @code{element}. Every generally
-applicable function for @code{\apply} must -- like music expressions
-themselves -- be recursive.
-
-The following example is such a recursive function: It first extracts
-the @code{elements} of an expression, reverses them and puts them
-back. Then it recurses, both on @code{elements} and @code{element}
-children.
-@example
-#(define (reverse-music music)
- (let* ((elements (ly:music-property music 'elements))
- (child (ly:music-property music 'element))
- (reversed (reverse elements)))
-
- ; set children
- (ly:music-set-property! music 'elements reversed)
-
- ; recurse
- (if (ly:music? child) (reverse-music child))
- (map reverse-music reversed)
-
- music))
-@end example
-
-A slightly more elaborate example is in
-@inputfileref{input/test,reverse-music.ly}.
-
-Some of the input syntax is also implemented as recursive music
-functions. For example, the syntax for polyphony
-@example
- <<a \\ b>>
-@end example
-
-@noindent
-is actually implemented as a recursive function that replaces the
-above by the internal equivalent of
-@example
- << \context Voice = "1" @{ \voiceOne a @}
- \context Voice = "2" @{ \voiceTwo b @} >>
-@end example
-
-Other applications of @code{\apply} are writing out repeats
-automatically (@inputfileref{input/test,unfold-all-repeats.ly}),
-saving keystrokes (@inputfileref{input/test,music-box.ly}) and
-exporting
-LilyPond input to other formats (@inputfileref{input/test,to-xml.ly})
-
-@seealso
-
-@file{scm/music-functions.scm}, @file{scm/music-types.scm},
-@inputfileref{input/test,add-staccato.ly},
-@inputfileref{input/test,unfold-all-repeats.ly}, and
-@inputfileref{input/test,music-box.ly}.
-
-@node Lexical details
-@section Lexical details
-
-
-@cindex string
-@cindex concatenate
-
-By enclosing text in quotes (@code{"}), strings are formed. To
-include a @code{"} character in a string write @code{\"}. Various
-other backslash sequences have special interpretations as in the C
-language. A string that does not contain spaces or special characters
-can be written without the quotes. The exact form of such unquoted
-strings depends on the input mode; there are different rules for
-lyrics, notes and markups. Strings can be concatenated with the
-@code{+} operator.
-
-
-@node Output details
-@section Output details
-
-The default output format is La@TeX{}, which should be run
-through La@TeX{}. Using the option @option{-f}
-(or @option{--format}) other output formats can be selected also, but
-currently none of them work reliably.
-
-At the beginning of the output file, various global parameters are
-defined. Then the file @file{lilyponddefs.tex} is loaded to define
-the macros used in the code which follows. @file{lilyponddefs.tex}
-includes various other files, partially depending on the global
-parameters.
-
-Now the music is output system by system (a `system' consists of all
-staves belonging together). From @TeX{}'s point of view, a system is an
-@code{\hbox} which contains a lowered @code{\vbox} so that it is centered
-vertically on the baseline of the text. Between systems,
-@code{\interscoreline} is inserted vertically to have stretchable space.
-The horizontal dimension of the @code{\hbox} is given by the
-@code{linewidth} parameter from LilyPond's @code{\paper} block.
-
-After the last system LilyPond emits a stronger variant of
-@code{\interscoreline} only if the macro
-@code{\lilypondpaperlastpagefill} is not defined (flushing the systems
-to the top of the page). You can avoid that by setting the variable
-@code{lastpagefill} in LilyPond's @code{\paper} block.
-
-It is possible to fine-tune the vertical offset further by defining the
-macro @code{\lilypondscoreshift}:
-
-@example
-\def\lilypondscoreshift@{0.25\baselineskip@}
-@end example
-
-@noindent
-where @code{\baselineskip} is the distance from one text line to the next.
-
-Here an example how to embed a small LilyPond file @code{foo.ly} into
-running La@TeX{} text without using the @code{lilypond-book} script
-(@pxref{lilypond-book manual}):
-
-@example
-\documentclass@{article@}
-
-\def\lilypondpaperlastpagefill@{@}
-\lineskip 5pt
-\def\lilypondscoreshift@{0.25\baselineskip@}
-
-\begin@{document@}
-This is running text which includes an example music file
-\input@{foo.tex@}
-right here.
-\end@{document@}
-@end example
-
-The file @file{foo.tex} has been simply produced with
-
-@example
- lilypond-bin foo.ly
-@end example
-
-The call to @code{\lineskip} assures that there is enough vertical space
-between the LilyPond box and the surrounding text lines.
-
-@c EOF
diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely
index 63d11155e3..ccf6611e67 100644
--- a/Documentation/user/introduction.itely
+++ b/Documentation/user/introduction.itely
@@ -644,10 +644,9 @@ The
@ifhtml
The
@end ifhtml
-@emph{@ref{Technical manual}}
+@emph{@ref{Changing defaults}}
@c
-discusses the general design of the program, and how to extend its
-functionality.
+Explains how to fine tune layout.
@item
@ifhtml
The chapter
diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi
index 0e0b88ba94..1b3b612bc6 100644
--- a/Documentation/user/invoking.itexi
+++ b/Documentation/user/invoking.itexi
@@ -410,6 +410,7 @@ be skipped.
Something is definitely wrong, and LilyPond cannot continue. This
happens rarely. The most usual cause is misinstalled fonts.
+@cindex trace, Scheme
@cindex call trace
@cindex Scheme error
@item Scheme error
diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely
index 8a187a9b08..7c6ecbe512 100644
--- a/Documentation/user/lilypond.tely
+++ b/Documentation/user/lilypond.tely
@@ -149,13 +149,14 @@ this and other documentation.
* Tutorial:: A tutorial introduction.
* Notation manual:: All notation supported, and how to
produce it.
-* Using LilyPond:: How it all works.
-* Technical manual:: How it all works.
+* Changing defaults:: Tuning output
* Invoking LilyPond:: Operation.
* Converting from other formats:: Converting to lilypond source format.
* lilypond-book manual:: Integrating text and music with lilypond-book.
* Unified index::
-* Reference manual details::
+* Notation manual details::
+* Literature list::
+* Interfaces for programmers::
* Cheat sheet::
* GNU Free Documentation License:: FDL.
@end menu
@@ -168,9 +169,8 @@ this and other documentation.
@include preface.itely
@include introduction.itely
@include tutorial.itely
-@include refman.itely
-@include running.itely
-@include internals.itely
+@include notation.itely
+@include changing-defaults.itely
@include invoking.itexi
@include lilypond-book.itely
@include converters.itely
@@ -182,8 +182,14 @@ this and other documentation.
@printindex cp
-@include appendices.itely
+@include notation-appendices.itely
+
+@include literature.itely
+
+@include programming-interface.itely
+
@include cheatsheet.itely
+
@include fdl.itexi
@bye
diff --git a/Documentation/user/literature.itely b/Documentation/user/literature.itely
index 9c9e938c7e..76eca96d05 100644
--- a/Documentation/user/literature.itely
+++ b/Documentation/user/literature.itely
@@ -1,5 +1,5 @@
@node Literature list
-@section Literature list
+@appendix Literature list
If you need to know more about music notation, here are some
interesting titles to read. The source archive includes a more
diff --git a/Documentation/user/music-glossary.tely b/Documentation/user/music-glossary.tely
index c52bf5b2e5..369a2b7b06 100644
--- a/Documentation/user/music-glossary.tely
+++ b/Documentation/user/music-glossary.tely
@@ -944,7 +944,7 @@ also the contrapunctal technique used in the @emph{fugue} which, since the
music of the baroque era, has been one of the most popular polyphonic
composition methods.
-@lilypond[staffsize=11,noquote]
+@lilypond[staffsize=11]
\override Score.TimeSignature #'style =\turnOff
\notes\context PianoStaff <<
\context Staff = SA \relative c' {
diff --git a/Documentation/user/appendices.itely b/Documentation/user/notation-appendices.itely
similarity index 83%
rename from Documentation/user/appendices.itely
rename to Documentation/user/notation-appendices.itely
index a70d26fb45..a52168b642 100644
--- a/Documentation/user/appendices.itely
+++ b/Documentation/user/notation-appendices.itely
@@ -1,25 +1,23 @@
-@node Reference manual details
-@appendix Reference manual details
+@node Notation manual details
+@appendix Notation manual details
@menu
-* Chord name chart::
-* MIDI instruments::
-* The Feta font::
-* Scheme functions::
-* Layout property overview::
-* Context property overview::
-* Literature list::
+* Chord name chart::
+* MIDI instruments::
+* The Feta font::
+* All context properties::
+* Layout properties::
@end menu
@node Chord name chart
-@section Chord name chart
+@appendixsec Chord name chart
@lilypondfile{chord-names-jazz.ly}
@node MIDI instruments
-@section MIDI instruments
+@appendixsec MIDI instruments
@example
"acoustic grand" "contrabass" "lead 7 (fifths)"
@@ -40,7 +38,7 @@
"dulcimer" "tuba" "fx 6 (goblins)"
"drawbar organ" "muted trumpet" "fx 7 (echoes)"
"percussive organ" "french horn" "fx 8 (sci-fi)"
-"rock organ" "brass section" "sitar"
+"rock organ" "brass appendixsection" "sitar"
"church organ" "synthbrass 1" "banjo"
"reed organ" "synthbrass 2" "shamisen"
"accordion" "soprano sax" "koto"
@@ -68,10 +66,11 @@
@end example
@node The Feta font
-@section The Feta font
+@appendixsec The Feta font
+
The following symbols are available in the Feta font and may be
-accessed directly using text markup such as
-@code{g^\markup @{ \musicglyph #"scripts-segno" @}}, see @ref{Text markup}.
+accessed directly using text markup such as @code{g^\markup @{
+\musicglyph #"scripts-segno" @}}, see @ref{Text markup}.
@lilypondfile[noindent]{feta16list.ly}
@@ -80,10 +79,15 @@ accessed directly using text markup such as
@lilypondfile[noindent]{parmesan16list.ly}
-@include scheme-functions.tely
+
+@node All context properties
+@appendixsec All context properties
@include context-properties.tely
+
+@node Layout properties
+@appendixsec Layout properties
+
@include layout-properties.tely
-@include literature.itely
diff --git a/Documentation/user/refman.itely b/Documentation/user/notation.itely
similarity index 98%
rename from Documentation/user/refman.itely
rename to Documentation/user/notation.itely
index 10a03b6afa..670e3047e3 100644
--- a/Documentation/user/refman.itely
+++ b/Documentation/user/notation.itely
@@ -4,9 +4,6 @@
@c A menu is needed before every deeper *section nesting of @node's; run
@c M-x texinfo-all-menus-update
@c to automatically fill in these menus before saving changes
-@c
-@c FIXME: singular vs. plural: Beams/Beam
-
@node Notation manual
@chapter Notation manual
@@ -33,6 +30,7 @@ somewhat familiar with using LilyPond.
* Ancient notation::
* Contemporary notation::
* Special notation::
+* Sound::
@end menu
@c FIXME: Note entry vs Music entry at top level menu is confusing.
@@ -1504,7 +1502,7 @@ In the example below, the autobeamer makes eight beams and sixteenth
end at 3 eights; the third beam can only be corrected by specifying
manual beaming.
-@lilypond[raggedright,fragment,relative,noverbatim]
+@lilypond[raggedright,fragment,relative]
#(override-auto-beam-setting '(end * * * *) 3 8)
% rather show case where it goes wrong
%\time 12/8 c'8 c c c16 c c c c c c[ c c c] c8[ c] c4
@@ -4654,7 +4652,7 @@ added clarinet voice.
Quotations take into account the transposition both source and target
instruments, if they are specified using the @code{\transposition} command.
-@lilypond[verbatim fragment]
+@lilypond[verbatim,fragment]
\addquote clarinet \notes\relative c' {
\transposition bes
f4 fis g gis
@@ -4682,10 +4680,6 @@ Examples: @inputfileref{input/regression,quote.ly}
Internals: @internalsref{QuoteMusic}.
-
-
-
-
@node Ancient notation
@section Ancient notation
@@ -7375,6 +7369,7 @@ entering the chant, as the following short excerpt demonstrates:
}
@end lilypond
+
@node Contemporary notation
@section Contemporary notation
@@ -7570,3 +7565,84 @@ If you view the result with Xdvi, then staff lines may show through
the letters. Printing the PostScript file obtained does produce the
correct result.
+
+@node Sound
+@section Sound
+@cindex Sound
+
+Entered music can also be converted to MIDI output. The performance
+is good enough for proof-hearing the music for errors.
+
+Ties, dynamics and tempo changes are interpreted. Dynamic marks,
+crescendi and decrescendi translate into MIDI volume levels. Dynamic
+marks translate to a fixed fraction of the available MIDI volume
+range, crescendi and decrescendi make the volume vary linearly between
+their two extremities. The fractions can be adjusted by
+@code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
+For each type of MIDI instrument, a volume range can be defined. This
+gives a basic equalizer control, which can enhance the quality of
+the MIDI output remarkably. The equalizer can be controlled by
+setting @code{instrumentEqualizer}.
+
+@refbugs
+
+Many musically interesting effects, such as swing, articulation,
+slurring, etc., are not translated to MIDI.
+
+The MIDI output allocates a channel for each Staff, and one for global
+settings. Hence, the MIDI file should not have more than 15 staves
+(or 14 if you do not use drums).
+
+
+@menu
+* MIDI block::
+* MIDI instrument names::
+@end menu
+
+
+@node MIDI block
+@subsection MIDI block
+@cindex MIDI block
+
+
+The MIDI block is analogous to the paper block, but it is somewhat
+simpler. The @code{\midi} block can contain:
+@cindex MIDI block
+
+@itemize @bullet
+ @item a @code{\tempo} definition, and
+ @item context definitions.
+@end itemize
+
+Assignments in the @code{\midi} block are not allowed.
+
+A number followed by a period is interpreted as a real number, so
+for setting the tempo for dotted notes, an extra space should be
+inserted, for example:
+
+@example
+ \midi @{ \tempo 4 . = 120 @}
+@end example
+
+
+@cindex context definition
+
+Context definitions follow precisely the same syntax as within the
+\paper block. Translation modules for sound are called performers.
+The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
+
+
+@node MIDI instrument names
+@subsection MIDI instrument names
+
+@cindex instrument names
+@cindex @code{Staff.midiInstrument}
+
+The MIDI instrument name is set by the @code{Staff.midiInstrument}
+property. The instrument name should be chosen from the list in
+@ref{MIDI instruments}.
+
+@refbugs
+
+If the selected string does not exactly match, then the default is
+used, which is the Grand Piano.
diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely
new file mode 100644
index 0000000000..ff923a66c6
--- /dev/null
+++ b/Documentation/user/programming-interface.itely
@@ -0,0 +1,510 @@
+@node Interfaces for programmers
+@appendix Interfaces for programmers
+
+
+
+@menu
+* Programmer interfaces for input ::
+* Markup programmer interface::
+* Contexts for programmers::
+@end menu
+
+@node Programmer interfaces for input
+@appendixsec Programmer interfaces for input
+
+@menu
+* Input variables and Scheme::
+* Internal music representation::
+* Manipulating music expressions::
+@end menu
+
+@node Input variables and Scheme
+@appendixsubsec Input variables and Scheme
+
+
+The input format supports the notion of variable: in the following
+example, a music expression is assigned to a variable with the name
+@code{traLaLa}.
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+@end example
+
+@noindent
+
+There is also a form of scoping: in the following example, the
+@code{\paper} block also contains a @code{traLaLa} variable, which is
+independent of the outer @code{\traLaLa}.
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+ \paper @{ traLaLa = 1.0 @}
+@end example
+@c
+In effect, each input file is a scope, and all @code{\header},
+@code{\midi} and @code{\paper} blocks are scopes nested inside that
+toplevel scope.
+
+Both variables and scoping are implemented in the GUILE module system.
+An anonymous Scheme module is attached to each scope. An assignment of
+the form
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+@end example
+
+@noindent
+is internally converted to a Scheme definition
+@example
+ (define traLaLa @var{Scheme value of ``@code{\notes ... }''})
+@end example
+
+This means that input variables and Scheme variables may be freely
+mixed. In the following example, a music fragment is stored in the
+variable @code{traLaLa}, and duplicated using Scheme. The result is
+imported in a @code{\score} by means of a second variable
+@code{twice}:
+@example
+ traLaLa = \notes @{ c'4 d'4 @}
+
+ #(define newLa (map ly:music-deep-copy
+ (list traLaLa traLaLa)))
+ #(define twice
+ (make-sequential-music newLa))
+
+ \score @{ \twice @}
+@end example
+
+In the above example, music expressions can be `exported' from the
+input to the Scheme interpreter. The opposite is also possible. By
+wrapping a Scheme value in the function @code{ly:export}, a Scheme
+value is interpreted as if it were entered in LilyPond syntax: instead
+of defining @code{\twice}, the example above could also have been
+written as
+@example
+ @dots{}
+ \score @{ #(ly:export (make-sequential-music newLa)) @}
+@end example
+
+
+@node Internal music representation
+@appendixsubsec Internal music representation
+
+When a music expression is parsed, it is converted into a set of
+Scheme music objects. The defining property of a music object is that
+it takes up time. Time is a rational number that measures the length
+of a piece of music, in whole notes.
+
+A music object has three kinds of types:
+@itemize @bullet
+@item
+ music name: Each music expression has a name, for example, a note
+leads to a @internalsref{NoteEvent}, and @code{\simultaneous} leads to
+a @internalsref{SimultaneousMusic}. A list of all expressions
+available is in the internals manual, under @internalsref{Music
+expressions}.
+
+@item
+ `type' or interface: Each music name has several `types' or interface,
+ for example, a note is an @code{event}, but it is also a @code{note-event},
+ a @code{rhythmic-event} and a @code{melodic-event}.
+
+ All classes of music are listed in the internals manual, under
+ @internalsref{Music classes}.
+@item
+C++ object: Each music object is represented by a C++ object. For technical
+reasons, different music objects may be represented by different C++
+object types. For example, a note is @code{Event} object, while
+@code{\grace} creates a @code{Grace_music} object.
+
+We expect that distinctions between different C++ types will disappear
+in the future.
+@end itemize
+
+The actual information of a music expression is stored in properties.
+For example, a @internalsref{NoteEvent} has @code{pitch} and
+@code{duration} properties that store the pitch and duration of that
+note. A list of all properties available is in the internals manual,
+under @internalsref{Music properties}.
+
+A compound music expression is a music object that contains other
+music objects in its properties. A list of objects can be stored in
+the @code{elements} property of a music object, or a single `child'
+music object in the @code{element} object. For example,
+@internalsref{SequentialMusic} has its children in @code{elements},
+and @internalsref{GraceMusic} has its single argument in
+@code{element}. The body of a repeat is in @code{element} property of
+@internalsref{RepeatedMusic}, and the alternatives in @code{elements}.
+
+@node Manipulating music expressions
+@appendixsubsec Manipulating music expressions
+
+Music objects and their properties can be accessed and manipulated
+directly, through the @code{\apply} mechanism.
+The syntax for @code{\apply} is
+@example
+\apply #@var{func} @var{music}
+@end example
+
+@noindent
+This means that the scheme function @var{func} is called with
+@var{music} as its argument. The return value of @var{func} is the
+result of the entire expression. @var{func} may read and write music
+properties using the functions @code{ly:music-property} and
+@code{ly:music-set-property!}.
+
+An example is a function that reverses the order of elements in
+its argument:
+@lilypond[verbatim,raggedright]
+ #(define (rev-music-1 m)
+ (ly:music-set-property! m 'elements (reverse
+ (ly:music-property m 'elements)))
+ m)
+ \score { \notes \apply #rev-music-1 { c4 d4 } }
+@end lilypond
+
+The use of such a function is very limited. The effect of this
+function is void when applied to an argument which is does not have
+multiple children. The following function application has no effect:
+
+@example
+ \apply #rev-music-1 \grace @{ c4 d4 @}
+@end example
+
+@noindent
+In this case, @code{\grace} is stored as @internalsref{GraceMusic}, which has no
+@code{elements}, only a single @code{element}. Every generally
+applicable function for @code{\apply} must -- like music expressions
+themselves -- be recursive.
+
+The following example is such a recursive function: It first extracts
+the @code{elements} of an expression, reverses them and puts them
+back. Then it recurses, both on @code{elements} and @code{element}
+children.
+@example
+#(define (reverse-music music)
+ (let* ((elements (ly:music-property music 'elements))
+ (child (ly:music-property music 'element))
+ (reversed (reverse elements)))
+
+ ; set children
+ (ly:music-set-property! music 'elements reversed)
+
+ ; recurse
+ (if (ly:music? child) (reverse-music child))
+ (map reverse-music reversed)
+
+ music))
+@end example
+
+A slightly more elaborate example is in
+@inputfileref{input/test,reverse-music.ly}.
+
+Some of the input syntax is also implemented as recursive music
+functions. For example, the syntax for polyphony
+@example
+ <<a \\ b>>
+@end example
+
+@noindent
+is actually implemented as a recursive function that replaces the
+above by the internal equivalent of
+@example
+ << \context Voice = "1" @{ \voiceOne a @}
+ \context Voice = "2" @{ \voiceTwo b @} >>
+@end example
+
+Other applications of @code{\apply} are writing out repeats
+automatically (@inputfileref{input/test,unfold-all-repeats.ly}),
+saving keystrokes (@inputfileref{input/test,music-box.ly}) and
+exporting
+LilyPond input to other formats (@inputfileref{input/test,to-xml.ly})
+
+@seealso
+
+@file{scm/music-functions.scm}, @file{scm/music-types.scm},
+@inputfileref{input/test,add-staccato.ly},
+@inputfileref{input/test,unfold-all-repeats.ly}, and
+@inputfileref{input/test,music-box.ly}.
+
+
+
+@node Markup programmer interface
+@appendixsec Markup programmer interface
+
+
+@menu
+* Markup construction in scheme::
+* Markup command definition::
+@end menu
+
+@node Markup construction in scheme
+@appendixsubsec Markup construction in scheme
+
+@cindex defining markup commands
+
+The @code{markup} macro builds markup expressions in Scheme while
+providing a LilyPond-like syntax. For example,
+@example
+(markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
+ #:bigger #:line ("foo" "bar" "baz")))
+@end example
+
+@noindent
+is equivalent to:
+@example
+\markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
+ \bigger @{ foo bar baz @} >
+@end example
+
+@noindent
+This example exposes the main translation rules between regular
+LilyPond markup syntax and scheme markup syntax, which are summed up
+is this table:
+@multitable @columnfractions .5 .5
+@item @b{LilyPond} @tab @b{Scheme}
+@item @code{\command} @tab @code{#:command}
+@item @code{\variable} @tab @code{variable}
+@item @code{@{ ... @}} @tab @code{#:line ( ... )}
+@item @code{\center-align < ... >} @tab @code{#:center ( ... )}
+@item @code{string} @tab @code{"string"}
+@item @code{#scheme-arg} @tab @code{scheme-arg}
+@end multitable
+
+Besides, the whole scheme language is accessible inside the
+@code{markup} macro: thus, one may use function calls inside
+@code{markup} in order to manipulate character strings for
+instance. This proves useful when defining new markup commands (see
+@ref{Markup command definition}).
+
+@refbugs
+
+One can not feed the @code{#:line} (resp @code{#:center},
+@code{#:column}) command with a variable or the result of a function
+call. Eg:
+@lisp
+(markup #:line (fun-that-returns-markups))
+@end lisp
+is illegal. One should use the @code{make-line-markup} (resp
+@code{make-center-markup}, @code{make-column-markup}) function
+instead:
+@lisp
+(markup (make-line-markup (fun-that-returns-markups)))
+@end lisp
+
+@node Markup command definition
+@appendixsubsec Markup command definition
+
+New markup commands can be defined thanks to the @code{def-markup-command} scheme macro.
+@lisp
+(def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...)
+ (@var{arg1-type?} @var{arg2-type?} ...)
+ ..command body..)
+
+ @var{argi}: i@var{th} command argument
+ @var{argi-type?}: a type predicate for the i@var{th} argument
+ @var{paper}: the `paper' definition
+ @var{props}: a list of alists, containing all active properties.
+@end lisp
+
+As a simple example, we show how to add a @code{\smallcaps} command,
+which selects @TeX{}'s small caps font. Normally, we could select the
+small caps font as follows:
+
+@verbatim
+ \markup { \override #'(font-shape . caps) Text-in-caps }
+@end verbatim
+
+This selects the caps font by setting the @code{font-shape} property to
+@code{#'caps} for interpreting @code{Text-in-caps}.
+
+To make the above available as @code{\smallcaps} command, we have to
+define a function using @code{def-markup-command}. The command should
+take a single argument, of markup type. Therefore, the start of the
+definition should read
+@example
+ (def-markup-command (smallcaps paper props argument) (markup?)
+@end example
+
+@noindent
+
+What follows is the content of the command: we should interpret
+the @code{argument} as a markup, i.e.
+
+@example
+ (interpret-markup paper @dots{} argument)
+@end example
+
+@noindent
+This interpretation should add @code{'(font-shape . caps)} to the active
+properties, so we substitute the the following for the @dots{} in the
+above example:
+
+@example
+ (cons (list '(font-shape . caps) ) props)
+@end example
+
+@noindent
+The variable @code{props} is a list of alists, and we prepend to it by
+consing a list with the extra setting.
+
+However, suppose that we are using a font that does not have a
+small-caps variant. In that case, we have to fake the small caps font,
+by setting a string in upcase, with the first letter a little larger:
+
+@example
+#(def-markup-command (smallcaps paper props str) (string?)
+ "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
+ (interpret-markup paper props
+ (make-line-markup
+ (map (lambda (s)
+ (if (= (string-length s) 0)
+ s
+ (markup #:large (string-upcase (substring s 0 1))
+ #:translate (cons -0.6 0)
+ #:tiny (string-upcase (substring s 1)))))
+ (string-split str #\Space)))))
+@end example
+
+The @code{smallcaps} command first splits its string argument into
+tokens separated by spaces (@code{(string-split str #\Space)}); for
+each token, a markup is built with the first letter made large and
+upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
+second markup built with the following letters made tiny and upcased
+(@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
+introduces a space between markups on a line, the second markup is
+translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
+the markups built for each token are put in a line
+(@code{(make-line-markup ...)}). Finally, the resulting markup is
+passed to the @code{interpret-markup} function, with the @code{paper}
+and @code{props} arguments.
+
+Finally, suppose that we are typesetting a recitative in an opera, and
+we would like to define a command that will show character names in a
+custom manner. Names should be printed with small caps and translated a
+bit to the left and top. We will define a @code{\character} command
+that takes into account the needed translation, and uses the newly
+defined @code{\smallcaps} command:
+
+@verbatim
+#(def-markup-command (character paper props name) (string?)
+ "Print the character name in small caps, translated to the left and
+ top. Syntax: \\character #\"name\""
+ (interpret-markup paper props
+ (markup "" #:translate (cons -4 2) #:smallcaps name)))
+@end verbatim
+
+There is one complication that needs explanation: texts above and below
+the staff are moved vertically to be at a certain distance (the
+@code{padding} property) from the staff and the notes. To make sure
+that this mechanism does not annihilate the vertical effect of our
+@code{#:translate}, we add an empty string (@code{""}) before the
+translated text. Now the @code{""} will be put above the notes, and the
+@code{name} is moved in relation to that empty string. The net effect is
+that the text is moved to the upper left.
+
+The final result is as follows:
+@verbatim
+\score {
+ \notes { \fatText
+ c''^\markup \character #"Cleopatra"
+ e'^\markup \character #"Giulio Cesare"
+ }
+}
+@end verbatim
+
+@lilypond[raggedright]
+#(def-markup-command (smallcaps paper props str) (string?)
+ "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
+ (interpret-markup paper props
+ (make-line-markup
+ (map (lambda (s)
+ (if (= (string-length s) 0)
+ s
+ (markup #:large (string-upcase (substring s 0 1))
+ #:translate (cons -0.6 0)
+ #:tiny (string-upcase (substring s 1)))))
+ (string-split str #\Space)))))
+
+#(def-markup-command (character paper props name) (string?)
+ "Print the character name in small caps, translated to the left and
+ top. Syntax: \\character #\"name\""
+ (interpret-markup paper props
+ (markup "" #:translate (cons -4 0) #:smallcaps name)))
+
+\score {
+ \notes { \fatText
+ c''^\markup \character #"Cleopatra"
+ e'^\markup \character #"Giulio Cesare"
+ }
+}
+@end lilypond
+
+
+
+@node Contexts for programmers
+@appendixsec Contexts for programmers
+
+
+@menu
+* Context evaluation::
+* Applyoutput::
+@end menu
+
+@node Context evaluation
+@appendixsubsec Context evaluation
+
+Contexts can be modified during interpretation with Scheme code. The
+syntax for this is
+@example
+ \applycontext @var{function}
+@end example
+
+@var{function} should be a Scheme function taking a single argument,
+being the context to apply it to. The following code will print the
+current bar number on the standard output during the compile:
+
+@example
+ \applycontext
+ #(lambda (x)
+ (format #t "\nWe were called in barnumber ~a.\n"
+ (ly:context-property x 'currentBarNumber)))
+@end example
+
+
+
+@node Applyoutput
+@appendixsubsec Applyoutput
+
+The most versatile way of tuning an object is @code{\applyoutput}. Its
+syntax is
+@example
+\applyoutput @var{proc}
+@end example
+
+@noindent
+where @var{proc} is a Scheme function, taking three arguments.
+
+When interpreted, the function @var{proc} is called for every layout
+object found in the context, with the following arguments:
+@itemize @bullet
+@item the layout object itself,
+@item the context where the layout object was created, and
+@item the context where @code{\applyoutput} is processed.
+@end itemize
+
+
+In addition, the cause of the layout object, i.e. the music
+expression or object that was responsible for creating it, is in the
+object property @code{cause}. For example, for a note head, this is a
+@internalsref{NoteHead} event, and for a @internalsref{Stem} object,
+this is a @internalsref{NoteHead} object.
+
+Here is a simple example of @code{\applyoutput}; it blanks note-heads on the
+center-line:
+@example
+(define (blanker grob grob-origin context)
+ (if (and (memq (ly:grob-property grob 'interfaces)
+ note-head-interface)
+ (eq? (ly:grob-property grob 'staff-position) 0))
+
+ (ly:grob-set-property! grob 'transparent #t)))
+@end example
+
diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 4a03f90ef9..0f47b487d0 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -808,8 +808,8 @@ braces at the end of an expression. For example,
@end example
-For more information on context see the Technical manual description
-in @ref{Interpretation context}.
+For more information on context see the description in
+@ref{Interpretation context}.
diff --git a/make/lilypond.redhat.spec.in b/make/lilypond.redhat.spec.in
index 39e9e88827..503b362073 100644
--- a/make/lilypond.redhat.spec.in
+++ b/make/lilypond.redhat.spec.in
@@ -107,7 +107,7 @@ fi
/sbin/install-info --delete %{_infodir}/music-glossary.info.gz %{_infodir}/dir
%endif
-# chkfontpath --remove=%{_datadir}/share/lilypond/@TOPLEVEL_VERSION@/fonts/type1/
+# chkfontpath --remove=%{_datadir}/share/lilypond/@TOPLEVEL_VERSION@/fonts/type1n/
%postun
@@ -144,7 +144,7 @@ scrollkeeper-update
%doc NEWS.txt
%if %{info}
-%{_infodir}/*
+%{_infodir}/lilypond/
%endif
%{_mandir}/man1/abc2ly.1.gz
diff --git a/scm/define-markup-commands.scm b/scm/define-markup-commands.scm
index d4b0a3f7f3..3b1e6d1183 100644
--- a/scm/define-markup-commands.scm
+++ b/scm/define-markup-commands.scm
@@ -263,7 +263,7 @@ letter 'A'."
This raises @var{arg}, by the distance @var{amount}.
A negative @var{amount} indicates lowering:
@c
-@lilypond[verbatim,fragment,relative=1,quote]
+@lilypond[verbatim,fragment,relative=1]
c1^\\markup { C \\small \\raise #1.0 \\bold { \"9/7+\" }}
@end lilypond
The argument to @code{\\raise} is the vertical displacement amount,
diff --git a/scm/documentation-generate.scm b/scm/documentation-generate.scm
index 6062aae507..8c47ee1021 100644
--- a/scm/documentation-generate.scm
+++ b/scm/documentation-generate.scm
@@ -28,55 +28,24 @@
))
(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)
-
-
-
-
-
-
-
-
-
-
-
-
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-(dump-node (all-scheme-functions-doc)
- (open-output-file "scheme-functions.tely")
- 2)
+(display
+ (slot-ref (all-scheme-functions-doc) 'text)
+ (open-output-file "scheme-functions.tely"))
(display
(markup-doc-string)
+ (open-output-file "markup-commands.tely"))
- (open-output-file "markup-commands.tely")
- )
-(dump-node
- (make <texi-node>
- #:name "Layout property overview"
- #:desc "All user serviceable layout properties"
- #:text (backend-properties-doc-string all-user-grob-properties))
-
- (open-output-file "layout-properties.tely")
- 2)
-
-(dump-node
- (make <texi-node>
- #:name "Context property overview"
- #:desc "All user serviceable context properties"
- #:text (translation-properties-doc-string all-user-translation-properties))
-
- (open-output-file "context-properties.tely")
- 2)
+(display
+ (backend-properties-doc-string all-user-grob-properties)
+ (open-output-file "layout-properties.tely") )
+(display
+ (translation-properties-doc-string all-user-translation-properties)
+ (open-output-file "context-properties.tely") )
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
diff --git a/scm/new-markup.scm b/scm/new-markup.scm
index a4174f94e0..b3f3d6d046 100644
--- a/scm/new-markup.scm
+++ b/scm/new-markup.scm
@@ -214,6 +214,43 @@ eg (make-COMMAND-markup arg1 arg2 ...), and the rest expression."
(values (cons 'list (compile-all-markup-args (car expr))) (cdr expr)))
(else (values (car expr) (cdr expr)))))
+;;;;;;;;;;;;;;;
+;;; Debugging utilities: print markup expressions in a friendly fashion
+
+(use-modules (ice-9 format))
+(define (markup->string markup-expr)
+ "Return a string describing, in LilyPond syntax, the given markup expression."
+ (define (proc->command proc)
+ (let ((cmd-markup (symbol->string (procedure-name proc))))
+ (substring cmd-markup 0 (- (string-length cmd-markup)
+ (string-length "-markup")))))
+ (define (arg->string arg)
+ (cond ((and (pair? arg) (pair? (car arg))) ;; markup list
+ (format #f "~{ ~a~}" (map markup->string arg)))
+ ((pair? arg) ;; markup
+ (markup->string arg))
+ ((string? arg) ;; scheme string argument
+ (format #f "#\"~a\"" arg))
+ (else ;; other scheme arg
+ (format #f "#~a" arg))))
+ (let ((cmd (car markup-expr))
+ (args (cdr markup-expr)))
+ (cond ((eqv? cmd simple-markup) ;; a simple string
+ (format #f "\"~a\"" (car args)))
+ ((eqv? cmd line-markup) ;; { ... }
+ (format #f "{~a}" (arg->string (car args))))
+ ((eqv? cmd center-align-markup) ;; \center < ... >
+ (format #f "\\center-align <~a>" (arg->string (car args))))
+ ((eqv? cmd column-markup) ;; \column < ... >
+ (format #f "\\column <~a>" (arg->string (car args))))
+ (else ;; \command ...
+ (format #f "\\~a~{ ~a~} " (proc->command cmd) (map arg->string args))))))
+
+(define-public (display-markup markup-expr)
+ "Print a LilyPond-syntax equivalent for the given markup expression."
+ (display "\\markup ")
+ (display (markup->string markup-expr)))
+
;;;;;;;;;;;;;;;
;;; Utilities for storing and accessing markup commands signature
;;; and keyword.
--
2.39.5