From: Jan Nieuwenhuizen <janneke@gnu.org>
Date: Thu, 30 Nov 2000 21:44:25 +0000 (+0100)
Subject: patch::: 1.3.113.jcn2
X-Git-Tag: release/1.3.114~2
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=9d57f53d36a3d7ea280355086a0df9a16dc50992;p=lilypond.git

patch::: 1.3.113.jcn2

1.3.113.jcn2
============

* Moved all documentation from regtest to individual example files.

* Added feature to lilypond-book to write out \header texidoc string.
---

diff --git a/CHANGES b/CHANGES
index ea5f6b019f..d8e74e1021 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,10 @@
+1.3.113.jcn2
+============
+
+* Moved all documentation from regtest to individual example files.
+
+* Added feature to lilypond-book to write out \header texidoc string.
+
 1.3.113.jcn1
 ============
 
diff --git a/Documentation/regression-test.tely b/Documentation/regression-test.tely
index 8a5d214837..b2d8b87c0b 100644
--- a/Documentation/regression-test.tely
+++ b/Documentation/regression-test.tely
@@ -19,386 +19,163 @@ and documenting bugfixes.
 
 [TODO: revise and completize this. ]
 
-[TODO: should generate out of header fields using ly2dvi?]
-
 
 
 @section Notes and rests
 
-Rests.  Note that the dot of 8th, 16th and 32nd rests rest should be
-next to the top of the rest.  All rests except the whole rest are
-centered on the middle staff line.  
-
 @lilypondfile{rest.ly}
 
-Note head shapes are settable.  The stem endings should be adjusted
-per note head.  If you want different note head styles on one stem,
-you must create a special context called Thread.
-
-Harmonic notes have a different shape and different
-dimensions. Nevertheless, noteheads in both styles can be combined, on
-either up or down stems.
-
 @lilypondfile{noteheadstyle.ly}
 
-Noteheads can have dots, and rests can too.  Augmentation dots should
-never be printed on a staff line, but rather be shifted vertically. They
-should go up, but in case of multiple parts, the down stems have down
-shifted dots.  (Wanske p. 186) In case of chords, all dots should be in
-a column.  The dots go along as rests are shifted to avoid collisions.
-
 @lilypondfile{dots.ly}
 
-Accidentals work: the second note does not get a sharp. The third and
-fourth show forced and courtesy accidentals
-
 @lilypondfile{accidental.ly}
 
-Multiple measure rests do not collide with barlines and clefs.  They
-are not expanded when you set @code{Score.skipBars}.  Although the
-multi-measure-rest is a Spanner, minimum distances are set to keep it
-colliding from barlines. 
-
-
 @lilypondfile{multi-measure-rest.ly}
 
-If @code{Score.skipBars} is set,
-the signs for four, two, and one measure rest are combined to
-produce the graphical representation of rests for up to 10 bars.
-The number of bars will be written above the sign.
-
 @lilypondfile{mm-rests2.ly}
 
-A sharp sign after a double sharp sign, as well as a flat sign
-after a double flat sign is automatically prepended with a
-natural sign.
-
 @lilypondfile{accidental-single-double.ly}
 
-@section Stems
 
-Stem tremolos or rolls are tremolo signs that look like beam segments
-crossing stems.  If the stem is in a beam, the tremolo must be parallel
-to the beam.  If the stem is invisible (eg. on a whole note), the
-tremolo must be centered on the note.
+
+@section Stems
 
 @lilypondfile{stem-tremolo.ly}
 
-Chord tremolos look like beams, but are a kind of repeat symbol.
-To avoid confusion, chord tremolo beams do not reach the stems, but 
-leave a gap.  Chord tremolo beams on half notes are not ambiguous,
-as half notes cannot appear in a regular beam, and should reach the 
-stems.
-  
 @lilypondfile{chord-tremolo.ly}
 
-Beams, stems and noteheads often have communication troubles, since
-the two systems for y dimensions (1 unit = staffspace, 1 unit = 1
-point) are mixed.
-
-Stems, beams, ties and slurs should behave similarly, when placed
-on the middle staff line. Of course stem-direction is down for high
-notes, and up for low notes.
-
 @lilypondfile{stem-direction.ly}
 
-Similarly, if @code{stem_default_neutral_direction} is set to @code{-1}.
-
 @lilypondfile{stem-direction-down.ly}
 
-@section Scripts
 
-The staccato dot (and all scripts with follow-into-staff set), must
-not be on staff lines.
 
-@lilypondfile{staccato-pos.ly}
+@section Scripts
 
-Dynamics appear below or above the staff.  If multiple dynamics are
-linked with (de)crescendi, they should be on the same line.
+@lilypondfile{staccato-pos.ly}
 
 @lilypondfile{dyn-line.ly}
 
-
-Arpeggios are supported, both cross-staff and broken single staff. 
-
 @lilypondfile{arpeggio.ly}
 
-Simple glissando lines between notes are supported.
-
 @lilypondfile{glissando.ly}
 
 
 
 @section Chord names
 
-Chord names are generated from a list pitches, and are customisable
-from guile.  For some unlogical names, guile customisation is used
-by default.
-
 @lilypondfile{chord-names.ly}
 
-@section Grace notes
 
-Grace notes are typeset as an encapsulated piece of music. You can
-have beams, notes, chords, stems etc. within a @code{\grace} section.
-Slurs that start within a grace section, but aren't ended are attached
-to the next normal note.  Grace notes have zero duration.  If there
-are tuplets, the grace notes won't be under the brace.  Grace notes
-can have accidentals, but they are (currently) spaced at a fixed
-distance.  Grace notes (of course) come before the accidentals of the
-main note.  Grace notes can also be positioned after the main note.
 
-Grace notes without beams should have a slash, if @code{flagStyle} is
-not set.  Main note scripts don't end up on the grace note.
+@section Grace notes
 
 @lilypondfile{grace.ly}
 
-@section Beams, slurs and other spanners
 
-Beaming is generated automatically. Beams may cross bar lines. In that
-case, line breaks are forbidden.  Yet clef and key signatures are
-hidden just as with breakable bar lines.
 
-@lilypondfile{beaming.ly}
+@section Beams, slurs and other spanners
 
-Beams should behave reasonably well, even under extreme circumstances.
-Stems may be short, but noteheads should never touch the beam.
+@lilypondfile{beaming.ly}
 
 @lilypondfile{beam-extreme.ly}
 
-Beams should always reach the middle staff line.  The second beam
-counting from the note head side, should never be lower than the
-second staff line.  This does not hold for grace note beams.
-Override with @code{noStemExtend}.
-
 @lilypondfile{beam-position.ly}
 
-Slurs should look nice and symmetric.  The curvature may increase
-only to avoid noteheads, and as little as possible.  Slurs never
-run through noteheads or stems.
-
 @lilypondfile{slur-nice.ly}
 @lilypondfile{slur-symmetry.ly}
 @lilypondfile{slur-symmetry-1.ly}
 
-Across line breaks, slurs behave nicely.  On the left, they extend to
-just after the preferatory matter, and on the right to the end of the
-staff.  A slur should follow the same vertical direction it would have
-in unbroken state.
-
 @lilypondfile{slur-broken-trend.ly}
 
-Ties are strictly horizontal.  They are placed in between note heads.
-The horizontal middle should not overlap with a staffline.
-
 @lilypondfile{tie.ly}
 
-When tieing chords, the outer slurs point outwards, the inner slurs
-point away from the center of the staff.  Override with
-@code{tieVerticalDirection}.
-
 @lilypondfile{tie-chord.ly}
 
-When tieing notes with accidentals across a bar boundary, the accidental
-must not be drawn on the note in the new bar.  Instead, the next note of
-the same pitch in this bar should always show the accidental (even if
-it's natural).  Slurring a accidentaled note to a natural one across bar
-boundaries should be explicit.
-
-Pitches can be verified by printing them  with the @code{NoteNames} context.
-
 @lilypondfile{tie-accidental.ly}
 
-Beams can be typeset over fixed distance aligned staffs, beam
-beautification doesn't really work, but knees do. Beams should be
-behave well, wherever the switching point is.
-
 @lilypondfile{beam-cross-staff.ly}
 
-The same goes for slurs. They behave decently when broken across
-linebreak.
-
 @lilypondfile{slur-cross-staff.ly}
 
-Tuplets are indicated by a bracket with a number.  There should be no
-bracket if there is one beam that matches  the length of the tuplet.
-The bracket does not interfere with the stafflines, and the number is
-centered in the gap in the bracket.
-
 @lilypondfile{tup.ly}
 
-@section Property details
 
-More specific settings take precendence over less specific settings. The
-second slur has slurDirection set to down, overriding the stemup  setting.
+
+@section Property details
 
 @lilypondfile{generic-property-override.ly}
 
-@section Repeats
 
-LilyPond has three modes for repeats: folded, unfolded and
-semi-unfolded.  Unfolded repeats are fully written out. Semi unfolded
-repeats have the body written and all alternatives sequentially.
-Folded repeats have the body written and all alternatives
-simultaneo.ly.  If the number of alternatives is larger than the
-repeat count, the excess alternatives are ignored.  If the number of
-alternatives is smaller, the first alternative is multiplied to get to
-the number of repeats.
 
-Unfolded behavior:
+@section Repeats
 
 @lilypondfile{repeat-unfold.ly}
 
-Volta (Semi folded) behavior.  Voltas can start on non-barline moments.
-If they don't barlines should still be shown.
-
 @lilypondfile{repeat-volta.ly}
 
-Folded.  This doesn't make sense without alternatives, but it works.
-
 @lilypondfile{repeat-fold.ly}
 
-Across linebreaks, the left edge of a first and second alternative
-bracket should be equal
-
 @lilypondfile{repeat-line-break.ly}
 
-Auto change piano staff switches  voices  between up and down staffs
-automatically; rests are switched along with the coming note.
-
 @lilypondfile{auto-change.ly}
 
-@section Lyrics
 
-Lyrics can be set to a melody automatically.  Excess lyrics will be
-dumped.  Lyrics will not be set over rests.  You can have melismata
-either by setting a property melismaBusy, or by setting
-automaticMelismas (which will set melismas during slurs and ties).  If
-you want a different order than first Music, then Lyrics, you must
-precook a chord of staffs/lyrics and label those.  Of course
-@code{\rhythm} ignores any other rhythms in the piece.  Hyphens and
-extenders do not assume anything about lyric lengths, so they continue
-to work.
 
-@lilypondfile{lyric-combine.ly}
+@section Lyrics
 
-Multiple stanzas
+@lilypondfile{lyric-combine.ly}
 
 @lilypondfile{lyrics-multi-stanza.ly}
 
-@section Multiple notes
 
-Rests should not collide with beams, stems and noteheads.  Rests may
-be under beams.  Rests should be move by integral number of spaces
-inside the staff, and by half spaces outside.  Notice that the half
-and whole rests just outside the staff get ledger lines in different
-cases.
 
-@lilypondfile{rest-collision.ly}
+@section Multiple notes
 
-Normal collisions. We have support for polyphony, where the
-middle voices are horizontally shifted.
+@lilypondfile{rest-collision.ly}
 
 @lilypondfile{collisions.ly}
 
-The number of stafflines of a staff can be set with the property
-numberOfStaffLines.  Ledger lines both on note heads and rests are
-adjusted.  Barlines also are adjusted.
+@lilypondfile{number-staff-lines.ly}
 
 
-@lilypondfile{number-staff-lines.ly}
 
 @section Spacing
 
-In a limited number of cases, LilyPond corrects for optical spacing
-effects.  In this example, space for opposite pointed stems is adjusted
-
 @lilypondfile{stem-spacing.ly}
 
-If there are accidentals in the music, we add space, but the space
-between note and accidentals is less than between the notes with the
-same value.  Clef changes also get extra space, but not as much as
-barlines.
-
-Even if a line is very tightly spaced, there will still be room
-between prefatory matter and the following notes.  The space after the
-prefatory is very rigid.  In contrast, the space before the barline
-must stretch like the space within the measure.
-
-Tight:
-
 @lilypondfile{spacing-tight.ly}
 
-Natural:
-
 @lilypondfile{spacing-natural.ly}
 
-Loose:
-
 @lilypondfile{spacing-loose.ly}
 
-Adding a @code{Bar_engraver} to the LyricsVoice context makes sure that
-lyrics don't collide with barlines.
-
 @lilypondfile{lyrics-bar.ly}
 
-Text is set with empty horizontal dimensions.  The boolean property
-textNonEmpty is used to respect the horizontal size of text.
-
 @lilypondfile{non-empty-text.ly}
 
 
 
-
 @section PianoStaff
 
 
 
 @section Global stuff
 
-Breaks can be encouraged and discouraged using @code{\break} and
-@code{\nobreak}.  They are abbrevs for @code{\penalty} commands.
-
 @lilypondfile{break.ly}
 
-Markings that are attached to (invisible) barlines are 
-delicate: the are attached to the rest of the score without the score
-knowing it.  Consequently, they fall over  often.
-
 @lilypondfile{bar-scripts.ly}
 
-Staff margins are also markings attached to barlines.  They should be
-left of the staff, and be centered vertically wrt the staff.  They may
-be on normal staffs, but also on compound staffs, like the PianoStaff
-
 @lilypondfile{staff-margin.ly}
 
-Breathing signs, also used for phrasing, do normally not influence
-global spacing -- only if space gets tight, notes are shifted to make
-room for the breathing sign. Breathing signs break beams running
-through their voice. In the following example, the notes in the first
-two measures all have the same distance from each other:
-
 @lilypondfile{breathing-sign.ly}
 
-Hara kiri staffs kill themselves if they are empty.  This example really
-contains two staffs, but the second contains only spaces, and is
-therefore removed. 
-
 @lilypondfile{hara-kiri-short.ly}
 
-In orchestral scores and hymns, voices are traditionally combined onto
-one staff.  LilyPond has a part combiner, that combines or separates two
-voices according to actual rhythm and pitch.  User-defined texts such as
-``solo'' and ``@`a2'' are typeset automagically, as appropriate.
-
 @lilypondfile{part-combine.ly}
 
 
-Fonts are  available in a default set of sizes: 11, 13, 16, 20, 23 and
-26pt staffheight.  Sizes of the text fonts and symbol fonts are made
-to match the staff dimensions.    
-
 @lilypondfile[nonfragment]{size11.ly}
 
 @lilypondfile[nonfragment]{size13.ly}
@@ -412,27 +189,14 @@ to match the staff dimensions.
 @lilypondfile[nonfragment]{size26.ly}
 
 
-@section Clefs and Time Signatures
 
-The transparent clef should not occupy any space and with style
-@code{fullSizeChanges}, the changing clef should be typeset in full
-size. For octaviated clefs, the ``8'' should appear closely above or
-below the clef respectively.  The ``8'' is processed in a convoluted
-way, so this is fragile as well.
+@section Clefs and Time Signatures
 
 @lilypondfile{clefs.ly}
 
-
-Key signatures appear on key  changes. They may also
-appear without barlines.  The restoration accidentals are not printed at
-the start of the line. If @code{createKeyOnClefChange} is set, they're
-also created on a clef change.
-
 @lilypondfile{keys.ly}
 
 
-
-
 @ignore
 @c the input file is too long and does not test for specific bugs
 
@@ -448,14 +212,11 @@ signatures.
 
 
 
-@section Hacks and Features
 
-As a last resort, the placement of items can be adjusted manually, by
-setting the @code{extra-offset} of an output object.
 
-@lilypondfile{generic-output-property.ly}
+@section Hacks and Features
 
-The same mechanism can be  used  to force pagebreaks.
+@lilypondfile{generic-output-property.ly}
 
 @lilypondfile{between-systems.ly}
 
diff --git a/Documentation/user/latex-lilypond-example.latex b/Documentation/user/latex-lilypond-example.latex
index 6906eab7e9..d155917b56 100644
--- a/Documentation/user/latex-lilypond-example.latex
+++ b/Documentation/user/latex-lilypond-example.latex
@@ -158,6 +158,7 @@ text text text text text text text text text text text text
 text text text text text text text text text text text text 
 text text text text text text text text text text text text 
 
-
+%% need to use an -I ../../../input/test to find the file
+%% \lilypondfile{tie.ly}
 
 \end{document}
diff --git a/Documentation/user/lilypond-book.tely b/Documentation/user/lilypond-book.tely
index 49fc1f8256..125303f3ef 100644
--- a/Documentation/user/lilypond-book.tely
+++ b/Documentation/user/lilypond-book.tely
@@ -93,10 +93,11 @@ or @command{texi2dvi}.
 The result is a text document with formatted music integrated.
 
 @command{lilypond-book} will do its best to try to align the music to
-the left and right margins. Currently the most used papersizes and
-one- and twocolumn mode is supported. But if you use some more
-advances features, like the geometry-package or change the margins in
-La@TeX{} or use @code{@@pagesize} in texinfo, will break.
+the left and right margins. Currently all papersizes, one- and
+twocolumn mode and the @code{geometry} package is supported. 
+The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
+But changing the linewidth in other ways will not give you a straight
+right margin.
 
 This document assumes you have basic knowledge of GNU LilyPond and
 La@TeX{} or texinfo.
@@ -120,10 +121,11 @@ or
 These commands should be in the beginning of the document:
 @itemize @bullet
 @item @code{@@afourpaper}
+@item @code{@@afourlatex}
 @item @code{@@afourwide}
 @item @code{@@smallbook}
 @end itemize
-@code{@@pagesizes} are not supported.
+@code{@@pagesizes} are not yet supported.
 
 @subsection Examples
 
@@ -208,11 +210,9 @@ or
 \lilypond@{ YOUR LILYPOND CODE @}
 @end example
 
-The 'geometry' package is is not supported. The most popular
-papersizes should work.
-
 Lilypond-book know about the @code{\onecolumn} and 
-@code{\twocolumn} commands.
+@code{\twocolumn} commands, the @code{geometry} package and
+all the standard paper sizes.
 
 The music will be surrounded by @code{\preLilypondExample} and
 @code{\postLilypondExample}. The variables are 
@@ -221,26 +221,6 @@ to whatever he wants.
 @strong{[UGH: THIS DOES NOT HAPPEN WHEN
 YOU USE THE SHORT FORM, \LILYPOND@{ ... @}, CHECK OUT WHY]}
 
-@subsection @code{landscape} package 
-There is some simple support for landscape paper format, and this
-can be combined with the @code{\twocolumn} command. Only a4 and
-letter paper is supported, more to come...
-
-A more complete
-support, maybe also supporting the geometry package is planned, but
-there are more work that has to be done on @command{lilypond-book}
-first.
-
-This should work:
-@example
-\documentclass@{article@}
-\usepackage@{landscape@}
-\begin@{document@}
-\twocolumn
-BLA BLA BLA
-\end@{document@}
-@end example
-
 @subsection Examples 
 
 @example
@@ -321,7 +301,7 @@ overwritten.
 If you use @code{--outdir}, you should also @code{cd} to that directory
 before running LaTeX or makeinfo.
 
-@strong{[UGH: IS THIS THE BEST WAY TO DO IT. MAYBE ADD A COMMENT LINE TO THE
+@strong{[UGH: IS THIS THE BEST WAY TO DO IT? MAYBE ADD A COMMENT LINE TO THE
 GENERATED FILE, SO LILYPOND-BOOK CAN TEST IF THE FILE IT IS TO OVERWRITE
 IS GENERATED.]}
 
diff --git a/VERSION b/VERSION
index b512f995d8..1677e99412 100644
--- a/VERSION
+++ b/VERSION
@@ -2,7 +2,7 @@ PACKAGE_NAME=LilyPond
 MAJOR_VERSION=1
 MINOR_VERSION=3
 PATCH_LEVEL=113
-MY_PATCH_LEVEL=jcn1
+MY_PATCH_LEVEL=jcn2
 
 # use the above to send patches: MY_PATCH_LEVEL is always empty for a
 # released version.
diff --git a/input/test/accidental-single-double.ly b/input/test/accidental-single-double.ly
index 3da9842e72..9014bcfa35 100644
--- a/input/test/accidental-single-double.ly
+++ b/input/test/accidental-single-double.ly
@@ -1,4 +1,10 @@
-
+\header{
+texidoc="
+A sharp sign after a double sharp sign, as well as a flat sign
+after a double flat sign is automatically prepended with a
+natural sign.
+";
+}
 \version "1.3.110";
 
 
diff --git a/input/test/accidental.ly b/input/test/accidental.ly
index 23a0c7ca7f..c7ebadec80 100644
--- a/input/test/accidental.ly
+++ b/input/test/accidental.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+Accidentals work: the second note does not get a sharp. The third and
+fourth show forced and courtesy accidentals.
+";
+}
 
 foo = \notes\relative c''   {   \key as \major; dis4 dis dis! dis? }
 
diff --git a/input/test/arpeggio.ly b/input/test/arpeggio.ly
index f901b1a00f..6df0fc762a 100644
--- a/input/test/arpeggio.ly
+++ b/input/test/arpeggio.ly
@@ -1,3 +1,8 @@
+\header{
+texidoc="
+Arpeggios are supported, both cross-staff and broken single staff.
+";
+}
 
 \version "1.3.110";
 
diff --git a/input/test/auto-change.ly b/input/test/auto-change.ly
index 5d3d34f8e4..ee0b5d18ba 100644
--- a/input/test/auto-change.ly
+++ b/input/test/auto-change.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+Auto change piano staff switches  voices  between up and down staffs
+automatically; rests are switched along with the coming note.
+";
+}
 
 \score {
 	\notes \context PianoStaff <
diff --git a/input/test/bar-scripts.ly b/input/test/bar-scripts.ly
index 8a4788a684..a4898e094c 100644
--- a/input/test/bar-scripts.ly
+++ b/input/test/bar-scripts.ly
@@ -1,3 +1,10 @@
+\header{
+texidoc="
+Markings that are attached to (invisible) barlines are 
+delicate: the are attached to the rest of the score without the score
+knowing it.  Consequently, they fall over  often.
+";
+}
 
 \version "1.3.110";
 
diff --git a/input/test/beam-cross-staff.ly b/input/test/beam-cross-staff.ly
index 92e9c7eb2e..fc33719539 100644
--- a/input/test/beam-cross-staff.ly
+++ b/input/test/beam-cross-staff.ly
@@ -1,3 +1,10 @@
+\header{
+texidoc="
+Beams can be typeset over fixed distance aligned staffs, beam
+beautification doesn't really work, but knees do. Beams should be
+behave well, wherever the switching point is.
+";
+}
 \score{
 	\context PianoStaff <
 	\context Staff=one \notes\relative c'{
diff --git a/input/test/beam-extreme.ly b/input/test/beam-extreme.ly
index 83a9d5dfcb..af48d185f9 100644
--- a/input/test/beam-extreme.ly
+++ b/input/test/beam-extreme.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+Beams should behave reasonably well, even under extreme circumstances.
+Stems may be short, but noteheads should never touch the beam.
+";
+}
 \version "1.3.110";
 \score{
 	\notes\relative c''{
diff --git a/input/test/beam-position.ly b/input/test/beam-position.ly
index 1599857298..003639f380 100644
--- a/input/test/beam-position.ly
+++ b/input/test/beam-position.ly
@@ -1,4 +1,11 @@
-
+\header{
+texidoc="
+Beams should always reach the middle staff line.  The second beam
+counting from the note head side, should never be lower than the
+second staff line.  This does not hold for grace note beams.
+Override with @code{noStemExtend}.
+";
+}
 \version "1.3.110";
 
 \score { 
diff --git a/input/test/beaming.ly b/input/test/beaming.ly
index cba2132db8..b1673319bf 100644
--- a/input/test/beaming.ly
+++ b/input/test/beaming.ly
@@ -1,3 +1,10 @@
+\header{
+texidoc="
+Beaming is generated automatically. Beams may cross bar lines. In that
+case, line breaks are forbidden.  Yet clef and key signatures are
+hidden just as with breakable bar lines.
+";
+}
 
 \score { \context Staff \notes \relative c''  {
 	[c8. c16]
diff --git a/input/test/between-systems.ly b/input/test/between-systems.ly
index 1f72c7a90f..144cb166a2 100644
--- a/input/test/between-systems.ly
+++ b/input/test/between-systems.ly
@@ -1,3 +1,8 @@
+\header{
+texidoc="
+The same mechanism can be  used  to force pagebreaks.
+";
+}
 
 \score {
 \notes { c1
diff --git a/input/test/break.ly b/input/test/break.ly
index ce65bb178b..4f8e9f972e 100644
--- a/input/test/break.ly
+++ b/input/test/break.ly
@@ -1,4 +1,9 @@
-
+\header{
+texidoc="
+Breaks can be encouraged and discouraged using @code{\break} and
+@code{\nobreak}.  They are abbrevs for @code{\penalty} commands.
+";
+}
 
 
 \score{
diff --git a/input/test/breathing-sign.ly b/input/test/breathing-sign.ly
index 04e028c163..31d399f85c 100644
--- a/input/test/breathing-sign.ly
+++ b/input/test/breathing-sign.ly
@@ -1,3 +1,14 @@
+\header{
+texidoc="
+Breathing signs, also used for phrasing, do normally not influence
+global spacing -- only if space gets tight, notes are shifted to make
+room for the breathing sign. Breathing signs break beams running
+through their voice. In the following example, the notes in the first
+two measures all have the same distance from each other:
+";
+}
+
+
 \version "1.3.110";
 
 \score {
diff --git a/input/test/chord-names.ly b/input/test/chord-names.ly
index e370654616..d640871803 100644
--- a/input/test/chord-names.ly
+++ b/input/test/chord-names.ly
@@ -1,3 +1,10 @@
+\header{
+texidoc="
+Chord names are generated from a list pitches, and are customisable
+from guile.  For some unlogical names, guile customisation is used
+by default.
+";
+}
 \version "1.3.110"
 chord = \notes\transpose c''\chords{
    c1
diff --git a/input/test/chord-tremolo.ly b/input/test/chord-tremolo.ly
index 66d118991b..6d941ff971 100644
--- a/input/test/chord-tremolo.ly
+++ b/input/test/chord-tremolo.ly
@@ -1,3 +1,13 @@
+\header{
+texidoc="
+Chord tremolos look like beams, but are a kind of repeat symbol.
+To avoid confusion, chord tremolo beams do not reach the stems, but 
+leave a gap.  Chord tremolo beams on half notes are not ambiguous,
+as half notes cannot appear in a regular beam, and should reach the 
+stems.
+";
+}
+  
 \score { 
   \context Voice \notes\relative c {
 	\repeat "tremolo" 8 { c16 d16 }
diff --git a/input/test/clefs.ly b/input/test/clefs.ly
index a2a077adc3..47b094b73f 100644
--- a/input/test/clefs.ly
+++ b/input/test/clefs.ly
@@ -1,3 +1,14 @@
+
+\header{
+texidoc="
+The transparent clef should not occupy any space and with style
+@code{fullSizeChanges}, the changing clef should be typeset in full
+size. For octaviated clefs, the ``8'' should appear closely above or
+below the clef respectively.  The ``8'' is processed in a convoluted
+way, so this is fragile as well.
+";
+}
+
 \version "1.3.110";
 
 \score {
diff --git a/input/test/collisions.ly b/input/test/collisions.ly
index f0c959a588..e072c48182 100644
--- a/input/test/collisions.ly
+++ b/input/test/collisions.ly
@@ -1,4 +1,8 @@
 \header{
+texidoc="
+Normal collisions. We have support for polyphony, where the
+middle voices are horizontally shifted.
+";
 filename =	 "collisions.ly";
 description =	 "random counterpoint to test collisions";
 enteredby =	 "HWN,JCN";
diff --git a/input/test/dots.ly b/input/test/dots.ly
index 7b860cfdb6..624d601d7f 100644
--- a/input/test/dots.ly
+++ b/input/test/dots.ly
@@ -1,3 +1,14 @@
+\header{
+texidoc="
+Noteheads can have dots, and rests can too.  Augmentation dots should
+never be printed on a staff line, but rather be shifted vertically. They
+should go up, but in case of multiple parts, the down stems have down
+shifted dots.  (Wanske p. 186) In case of chords, all dots should be in
+a column.  The dots go along as rests are shifted to avoid collisions.
+";
+}
+
+
 \version "1.3.110";
 \score { 
   \context Voice \notes\relative c'' {
diff --git a/input/test/dyn-line.ly b/input/test/dyn-line.ly
index cdc5906302..31f5dc597b 100644
--- a/input/test/dyn-line.ly
+++ b/input/test/dyn-line.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+Dynamics appear below or above the staff.  If multiple dynamics are
+linked with (de)crescendi, they should be on the same line.
+";
+}
 \score{
 \notes\relative c''{
 a1\fff\> \!c,,\pp a'' a\p
diff --git a/input/test/generic-output-property.ly b/input/test/generic-output-property.ly
index 5adbba97c8..f0368e7daa 100644
--- a/input/test/generic-output-property.ly
+++ b/input/test/generic-output-property.ly
@@ -1,3 +1,10 @@
+\header{
+texidoc="
+As a last resort, the placement of items can be adjusted manually, by
+setting the @code{extra-offset} of an output object.
+";
+}
+
 \score{
 	\notes\relative c''{
   	\outputproperty #(make-type-checker 'note-head-interface) 
diff --git a/input/test/generic-property-override.ly b/input/test/generic-property-override.ly
index 779cd99fce..c906ed3fb2 100644
--- a/input/test/generic-property-override.ly
+++ b/input/test/generic-property-override.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+More specific settings take precendence over less specific settings. The
+second slur has slurDirection set to down, overriding the stemup  setting.
+";
+}
 \version "1.3.110";
 
 \score {
diff --git a/input/test/glissando.ly b/input/test/glissando.ly
index e07626c372..951557e530 100644
--- a/input/test/glissando.ly
+++ b/input/test/glissando.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+Simple glissando lines between notes are supported.
+";
+}
+
 \score{
     <
         \context Staff=one \notes\relative c''{
diff --git a/input/test/grace.ly b/input/test/grace.ly
index ee5fe5da8e..dbc42a872c 100644
--- a/input/test/grace.ly
+++ b/input/test/grace.ly
@@ -1,3 +1,19 @@
+\header{
+texidoc="
+Grace notes are typeset as an encapsulated piece of music. You can
+have beams, notes, chords, stems etc. within a @code{\grace} section.
+Slurs that start within a grace section, but aren't ended are attached
+to the next normal note.  Grace notes have zero duration.  If there
+are tuplets, the grace notes won't be under the brace.  Grace notes
+can have accidentals, but they are (currently) spaced at a fixed
+distance.  Grace notes (of course) come before the accidentals of the
+main note.  Grace notes can also be positioned after the main note.
+
+Grace notes without beams should have a slash, if @code{flagStyle} is
+not set.  Main note scripts don't end up on the grace note.
+
+";
+}
 
 \score {\notes \context Voice = VA \relative c'' {
 	\grace b8 c4-\fermata
diff --git a/input/test/hara-kiri-short.ly b/input/test/hara-kiri-short.ly
index 5b977d5546..b58e3c9eda 100644
--- a/input/test/hara-kiri-short.ly
+++ b/input/test/hara-kiri-short.ly
@@ -1,3 +1,10 @@
+\header{
+texidoc="
+Hara kiri staffs kill themselves if they are empty.  This example really
+contains two staffs, but the second contains only spaces, and is
+therefore removed. 
+";
+}
 
 \version "1.3.110";
 zager = \context Staff = zager \notes \relative c'' {
diff --git a/input/test/keys.ly b/input/test/keys.ly
index 20dc2b6922..427cda9010 100644
--- a/input/test/keys.ly
+++ b/input/test/keys.ly
@@ -1,3 +1,12 @@
+\header{
+texidoc="
+Key signatures appear on key  changes. They may also
+appear without barlines.  The restoration accidentals are not printed at
+the start of the line. If @code{createKeyOnClefChange} is set, they're
+also created on a clef change.
+";
+}
+
 \version "1.3.110";
 
 \score {
diff --git a/input/test/lyric-combine.ly b/input/test/lyric-combine.ly
index 85f594a020..52497a554b 100644
--- a/input/test/lyric-combine.ly
+++ b/input/test/lyric-combine.ly
@@ -1,4 +1,17 @@
 \header{
+texidoc="
+Lyrics can be set to a melody automatically.  Excess lyrics will be
+dumped.  Lyrics will not be set over rests.  You can have melismata
+either by setting a property melismaBusy, or by setting
+automaticMelismas (which will set melismas during slurs and ties).  If
+you want a different order than first Music, then Lyrics, you must
+precook a chord of staffs/lyrics and label those.  Of course
+@code{\rhythm} ignores any other rhythms in the piece.  Hyphens and
+extenders do not assume anything about lyric lengths, so they continue
+to work.
+";
+
+
 filename =	 "twinkle-pop.ly";
 %title =	 "Ah, vous dirais-je, maman ";
 description =	 "twinkle twinkle in pop-song-settings";
diff --git a/input/test/lyric-phrasing.ly b/input/test/lyric-phrasing.ly
index eece431c4e..2927eb62ae 100644
--- a/input/test/lyric-phrasing.ly
+++ b/input/test/lyric-phrasing.ly
@@ -25,14 +25,14 @@ textIII =  \lyrics  { la -- da __ doo dah; dargh la dargh loo.  }
 \score {
 
     \notes < \context Staff = SA \context Voice = VA { s1 }
-      \context LyricVoice = "VA-1" { s1 }
-      \context LyricVoice = "VA-2" { s1 }
+      \context LyricsVoice = "VA-1" { s1 }
+      \context LyricsVoice = "VA-2" { s1 }
       
       \addlyrics
 	  \context Staff = SA \m
-	  < \context LyricVoice = "VA-1" \textI
-	    \context LyricVoice = "VA-2" \textII
-	    \context LyricVoice = "VA-3" \textIII
+	  < \context LyricsVoice = "VA-1" \textI
+	    \context LyricsVoice = "VA-2" \textII
+	    \context LyricsVoice = "VA-3" \textIII
 	  >
 	  
     >
diff --git a/input/test/lyrics-bar.ly b/input/test/lyrics-bar.ly
index ad47fbc19b..998ce458ee 100644
--- a/input/test/lyrics-bar.ly
+++ b/input/test/lyrics-bar.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+Adding a @code{Bar_engraver} to the LyricsVoice context makes sure that
+lyrics don't collide with barlines.
+";
+}
 
 \score {
 	\context StaffGroup <
diff --git a/input/test/lyrics-multi-stanza.ly b/input/test/lyrics-multi-stanza.ly
index 56a7be277a..2006b0879a 100644
--- a/input/test/lyrics-multi-stanza.ly
+++ b/input/test/lyrics-multi-stanza.ly
@@ -1,12 +1,18 @@
-% Tests a number of features:
-% * Lyric_phrasing_engraver
-% * Stanza_number_engraver
-% * Automatic melismata on beamed notes
 
 \version "1.3.110";
 \include "english.ly"
 
 \header{
+texidoc="
+Multiple stanzas
+
+ Tests a number of features:
+ * Lyric_phrasing_engraver
+ * Stanza_number_engraver
+ * Automatic melismata on beamed notes
+
+";
+
     title = "Crowned with Honour";
     composer = "Oliver Holden (1765-1844)";
     poet = "Thomas Kelly (1769-1855)";
@@ -70,9 +76,9 @@ Bass = \notes \relative c{
 
 TheLyrics =  \lyrics <
         {
-	    \context LyricVoice = "Soprano-1"
-	    \property LyricVoice .stanza = "1:"
-	    \property LyricVoice .stz = "(1)"
+	    \context LyricsVoice = "Soprano-1"
+	    \property LyricsVoice .stanza = "1:"
+	    \property LyricsVoice .stz = "(1)"
 	         The4 head    that once was crowned with thorns
 	         Is   crowned with glo -- ry  now;
 		 A roy -- al di -- a -- dem a -- dorns
@@ -81,9 +87,9 @@ TheLyrics =  \lyrics <
 		 The might -- y Vic -- tor's  brow.
         }
         {
-	    \context LyricVoice = "Soprano-2"
-	    \property LyricVoice .stanza = "2:"
-	    \property LyricVoice .stz = "(2)"
+	    \context LyricsVoice = "Soprano-2"
+	    \property LyricsVoice .stanza = "2:"
+	    \property LyricsVoice .stz = "(2)"
 	         The4 high -- est place that heav'n af -- fords
 	         Is His by sov -- 'reign  right;
 		 The King of kings, the Lord of lords,
@@ -92,9 +98,9 @@ TheLyrics =  \lyrics <
  		 He reigns in glo -- ry  bright.
         }
         {
-	    \context LyricVoice = "Soprano-3"
-	    \property LyricVoice .stanza = "3:"
-	    \property LyricVoice .stz = "(3)"
+	    \context LyricsVoice = "Soprano-3"
+	    \property LyricsVoice .stanza = "3:"
+	    \property LyricsVoice .stz = "(3)"
 	         The joy of all who dwell a -- bove,
 	         The joy of saints be --  low,
 		 To4 whom He man -- i -- fests His love,
diff --git a/input/test/mm-rests2.ly b/input/test/mm-rests2.ly
index eb90cbd8b1..c801ec4c67 100644
--- a/input/test/mm-rests2.ly
+++ b/input/test/mm-rests2.ly
@@ -1,3 +1,12 @@
+\header{
+texidoc="
+If @code{Score.skipBars} is set,
+the signs for four, two, and one measure rest are combined to
+produce the graphical representation of rests for up to 10 bars.
+The number of bars will be written above the sign.
+";
+}
+
 thenotes = \notes \relative cis' {
 \property Score. skipBars = ##t
 \time 4/4;
diff --git a/input/test/multi-measure-rest.ly b/input/test/multi-measure-rest.ly
index 3fa5193fe1..23f3e335b8 100644
--- a/input/test/multi-measure-rest.ly
+++ b/input/test/multi-measure-rest.ly
@@ -1,3 +1,11 @@
+\header{
+texidoc="
+Multiple measure rests do not collide with barlines and clefs.  They
+are not expanded when you set @code{Score.skipBars}.  Although the
+multi-measure-rest is a Spanner, minimum distances are set to keep it
+colliding from barlines. 
+";
+}
 \version "1.3.110";
 
 \score { \notes { \time 3/4; \key cis \major;
diff --git a/input/test/non-empty-text.ly b/input/test/non-empty-text.ly
index a9227e3a67..1d445c81fb 100644
--- a/input/test/non-empty-text.ly
+++ b/input/test/non-empty-text.ly
@@ -1,4 +1,9 @@
-
+\header{
+texidoc="
+Text is set with empty horizontal dimensions.  The boolean property
+textNonEmpty is used to respect the horizontal size of text.
+";
+}
 \score { \notes {
 \property Voice.TextScript \override #'no-spacing-rods = ##f
 c4_"very wide and long text" c4
diff --git a/input/test/noteheadstyle.ly b/input/test/noteheadstyle.ly
index bd313628ce..808c16020c 100644
--- a/input/test/noteheadstyle.ly
+++ b/input/test/noteheadstyle.ly
@@ -1,3 +1,14 @@
+\header{
+texidoc="
+Note head shapes are settable.  The stem endings should be adjusted
+per note head.  If you want different note head styles on one stem,
+you must create a special context called Thread.
+
+Harmonic notes have a different shape and different
+dimensions. Nevertheless, noteheads in both styles can be combined, on
+either up or down stems.
+";
+}
 
 \version "1.3.110";
 
diff --git a/input/test/number-staff-lines.ly b/input/test/number-staff-lines.ly
index f275c84ccf..d8f758a1e9 100644
--- a/input/test/number-staff-lines.ly
+++ b/input/test/number-staff-lines.ly
@@ -1,3 +1,11 @@
+\header{
+texidoc="
+The number of stafflines of a staff can be set with the property
+numberOfStaffLines.  Ledger lines both on note heads and rests are
+adjusted.  Barlines also are adjusted.
+";
+}
+
 \score { 
   \context Voice \notes\relative c {
     
diff --git a/input/test/part-combine.ly b/input/test/part-combine.ly
index 85efe4eee7..d710038cde 100644
--- a/input/test/part-combine.ly
+++ b/input/test/part-combine.ly
@@ -1,3 +1,12 @@
+\header{
+texidoc="
+In orchestral scores and hymns, voices are traditionally combined onto
+one staff.  LilyPond has a part combiner, that combines or separates two
+voices according to actual rhythm and pitch.  User-defined texts such as
+``solo'' and ``@`a2'' are typeset automagically, as appropriate.
+";
+}
+
 \score{
 	\context Staff = flauti <
 		\time 4/4;
diff --git a/input/test/repeat-fold.ly b/input/test/repeat-fold.ly
index 2ee0bc8424..28313665a5 100644
--- a/input/test/repeat-fold.ly
+++ b/input/test/repeat-fold.ly
@@ -1,3 +1,8 @@
+\header{
+texidoc="
+Folded.  This doesn't make sense without alternatives, but it works.
+";
+}
 
 \score { \notes\context Staff\relative c'' {
 \repeat fold 3 { c^"3$\\times$ 0alt" d }
diff --git a/input/test/repeat-line-break.ly b/input/test/repeat-line-break.ly
index 06ff02cd31..ae6a06de0d 100644
--- a/input/test/repeat-line-break.ly
+++ b/input/test/repeat-line-break.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+Across linebreaks, the left edge of a first and second alternative
+bracket should be equal
+";
+}
 
 \score  {
 \notes
diff --git a/input/test/repeat-unfold.ly b/input/test/repeat-unfold.ly
index 8d62f8991c..cb965c1610 100644
--- a/input/test/repeat-unfold.ly
+++ b/input/test/repeat-unfold.ly
@@ -1,3 +1,17 @@
+\header{
+texidoc="
+LilyPond has three modes for repeats: folded, unfolded and
+semi-unfolded.  Unfolded repeats are fully written out. Semi unfolded
+repeats have the body written and all alternatives sequentially.
+Folded repeats have the body written and all alternatives
+simultaneo.ly.  If the number of alternatives is larger than the
+repeat count, the excess alternatives are ignored.  If the number of
+alternatives is smaller, the first alternative is multiplied to get to
+the number of repeats.
+
+Unfolded behavior:
+";
+}
 
 \score {
 
diff --git a/input/test/repeat-volta.ly b/input/test/repeat-volta.ly
index b64a981a03..634ba4dadd 100644
--- a/input/test/repeat-volta.ly
+++ b/input/test/repeat-volta.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+Volta (Semi folded) behavior.  Voltas can start on non-barline moments.
+If they don't barlines should still be shown.
+";
+}
 
 %  no alts.
 \score { \notes
diff --git a/input/test/rest-collision.ly b/input/test/rest-collision.ly
index b55e6cfb09..a00046c6ea 100644
--- a/input/test/rest-collision.ly
+++ b/input/test/rest-collision.ly
@@ -1,3 +1,12 @@
+\header{
+texidoc="
+Rests should not collide with beams, stems and noteheads.  Rests may
+be under beams.  Rests should be move by integral number of spaces
+inside the staff, and by half spaces outside.  Notice that the half
+and whole rests just outside the staff get ledger lines in different
+cases.
+";
+}
 
 scale = \notes \relative c' {
   c8 d e f g a b c c d e f g a b c
diff --git a/input/test/rest.ly b/input/test/rest.ly
index 1396e8fb24..0e7eea1703 100644
--- a/input/test/rest.ly
+++ b/input/test/rest.ly
@@ -1,4 +1,13 @@
-\score { \notes {
+\header{
+texidoc="
+Rests.  Note that the dot of 8th, 16th and 32nd rests rest should be
+next to the top of the rest.  All rests except the whole rest are
+centered on the middle staff line.
+";
+}
+
+
+	\score { \notes {
 	\time 4/4;
 r \longa * 1/4  r\breve * 1/2 
 r1 r2 r4 r8 r16 r32 r64 r128 r128
diff --git a/input/test/size11.ly b/input/test/size11.ly
index bdd2767227..6bc299ba38 100644
--- a/input/test/size11.ly
+++ b/input/test/size11.ly
@@ -1,3 +1,10 @@
+\header{
+texidoc="
+Fonts are  available in a default set of sizes: 11, 13, 16, 20, 23 and
+26pt staffheight.  Sizes of the text fonts and symbol fonts are made
+to match the staff dimensions.    
+";
+}
 
 \include "paper11.ly"
 \include "allfontstyle.ly";
diff --git a/input/test/slur-broken-trend.ly b/input/test/slur-broken-trend.ly
index fb5cf7fed5..868d156491 100644
--- a/input/test/slur-broken-trend.ly
+++ b/input/test/slur-broken-trend.ly
@@ -1,3 +1,11 @@
+\header{
+texidoc="
+Across line breaks, slurs behave nicely.  On the left, they extend to
+just after the preferatory matter, and on the right to the end of the
+staff.  A slur should follow the same vertical direction it would have
+in unbroken state.
+";
+}
 \score{
 	\notes \relative c''{
 		e1( \break) a,
diff --git a/input/test/slur-cross-staff.ly b/input/test/slur-cross-staff.ly
index 2f1f8ed6af..b4805b1bea 100644
--- a/input/test/slur-cross-staff.ly
+++ b/input/test/slur-cross-staff.ly
@@ -1,4 +1,9 @@
-
+\header{
+texidoc="
+The same goes for slurs. They behave decently when broken across
+linebreak.
+";
+}
 
 	
 \score{
diff --git a/input/test/slur-nice.ly b/input/test/slur-nice.ly
index a0f90f807e..fdc690766e 100644
--- a/input/test/slur-nice.ly
+++ b/input/test/slur-nice.ly
@@ -1,4 +1,10 @@
-
+\header{
+texidoc="
+Slurs should look nice and symmetric.  The curvature may increase
+only to avoid noteheads, and as little as possible.  Slurs never
+run through noteheads or stems.
+";
+}
 \version "1.3.110";
 \score{
 	\notes\relative c''{
diff --git a/input/test/spacing-loose.ly b/input/test/spacing-loose.ly
index e0893afab8..eaac633a28 100644
--- a/input/test/spacing-loose.ly
+++ b/input/test/spacing-loose.ly
@@ -1,3 +1,8 @@
+\header{
+texidoc="
+Loose:
+";
+}
 \score {
 	\notes { \time 2/2; c'2 c'2 \time 2/2; }
 	\paper { linewidth = 5.0\cm;
diff --git a/input/test/spacing-natural.ly b/input/test/spacing-natural.ly
index 3a31c995c3..74e9f6f0f7 100644
--- a/input/test/spacing-natural.ly
+++ b/input/test/spacing-natural.ly
@@ -1,3 +1,8 @@
+\header{
+texidoc="
+Natural:
+";
+}
 
 \score {
 	\notes { \time 2/2; c'2 c'2 \time 2/2; }
diff --git a/input/test/spacing-tight.ly b/input/test/spacing-tight.ly
index f9cbe7c071..75c7d16f97 100644
--- a/input/test/spacing-tight.ly
+++ b/input/test/spacing-tight.ly
@@ -1,4 +1,18 @@
+\header{
+texidoc="
+If there are accidentals in the music, we add space, but the space
+between note and accidentals is less than between the notes with the
+same value.  Clef changes also get extra space, but not as much as
+barlines.
 
+Even if a line is very tightly spaced, there will still be room
+between prefatory matter and the following notes.  The space after the
+prefatory is very rigid.  In contrast, the space before the barline
+must stretch like the space within the measure.
+
+Tight:
+";
+}
 \score {
 	\notes { \time 2/2; f''2 c'2 \time 2/2; }
 	\paper { linewidth = 2.5 \cm;
diff --git a/input/test/staccato-pos.ly b/input/test/staccato-pos.ly
index dc0150a477..aa3ac8a27f 100644
--- a/input/test/staccato-pos.ly
+++ b/input/test/staccato-pos.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+The staccato dot (and all scripts with follow-into-staff set), must
+not be on staff lines.
+";
+}
 \score { 
   \context Voice \notes\relative c {
     
diff --git a/input/test/staff-margin.ly b/input/test/staff-margin.ly
index ef9312ceb9..de631bce01 100644
--- a/input/test/staff-margin.ly
+++ b/input/test/staff-margin.ly
@@ -1,3 +1,10 @@
+\header{
+texidoc="
+Staff margins are also markings attached to barlines.  They should be
+left of the staff, and be centered vertically wrt the staff.  They may
+be on normal staffs, but also on compound staffs, like the PianoStaff
+";
+}
 
 	
 \version "1.3.110";
diff --git a/input/test/stem-direction-down.ly b/input/test/stem-direction-down.ly
index fb331e9674..1733d3995f 100644
--- a/input/test/stem-direction-down.ly
+++ b/input/test/stem-direction-down.ly
@@ -1,3 +1,10 @@
+\header{
+texidoc="
+@c FIXME
+Similarly, if @code{stem_default_neutral_direction} is set to @code{-1}.
+";
+}
+
 \score{
 	\notes\relative c{
 	    b''4 ~ b8()b8 e4 e,
diff --git a/input/test/stem-direction.ly b/input/test/stem-direction.ly
index 800185c33e..78f20f5182 100644
--- a/input/test/stem-direction.ly
+++ b/input/test/stem-direction.ly
@@ -1,3 +1,16 @@
+\header{
+texidoc="
+Beams, stems and noteheads often have communication troubles, since
+the two systems for y dimensions (1 unit = staffspace, 1 unit = 1
+point) are mixed.
+
+Stems, beams, ties and slurs should behave similarly, when placed
+on the middle staff line. Of course stem-direction is down for high
+notes, and up for low notes.
+";
+}
+
+
 \score { 
   \context Voice \notes\relative c {
     b''4 ~ b8()b8 e4 e,
diff --git a/input/test/stem-spacing.ly b/input/test/stem-spacing.ly
index 772cca797b..765416f54c 100644
--- a/input/test/stem-spacing.ly
+++ b/input/test/stem-spacing.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+In a limited number of cases, LilyPond corrects for optical spacing
+effects.  In this example, space for opposite pointed stems is adjuste
+";
+}
 \score { 
   \context Voice \notes\relative c {
     
diff --git a/input/test/stem-tremolo.ly b/input/test/stem-tremolo.ly
index 13f1a9ddd0..4856eb5a00 100644
--- a/input/test/stem-tremolo.ly
+++ b/input/test/stem-tremolo.ly
@@ -1,3 +1,11 @@
+\header{
+texidoc="
+Stem tremolos or rolls are tremolo signs that look like beam segments
+crossing stems.  If the stem is in a beam, the tremolo must be parallel
+to the beam.  If the stem is invisible (eg. on a whole note), the
+tremolo must be centered on the note.
+";
+}
 
 \version "1.3.110";
 \score{
diff --git a/input/test/tie-accidental.ly b/input/test/tie-accidental.ly
index 7b2e9c1c16..d6a20c92c6 100644
--- a/input/test/tie-accidental.ly
+++ b/input/test/tie-accidental.ly
@@ -1,3 +1,14 @@
+\header{
+texidoc="
+When tieing notes with accidentals across a bar boundary, the accidental
+must not be drawn on the note in the new bar.  Instead, the next note of
+the same pitch in this bar should always show the accidental (even if
+it's natural).  Slurring a accidentaled note to a natural one across bar
+boundaries should be explicit.
+
+Pitches can be verified by printing them  with the @code{NoteNames} context.
+";
+}
 
 thenotes = \notes \relative cis' { \time 4/4;
 gis'2 gis ~ |
diff --git a/input/test/tie-chord.ly b/input/test/tie-chord.ly
index afed40ee00..25fffecf9c 100644
--- a/input/test/tie-chord.ly
+++ b/input/test/tie-chord.ly
@@ -1,4 +1,10 @@
-
+\header{
+texidoc="
+When tieing chords, the outer slurs point outwards, the inner slurs
+point away from the center of the staff.  Override with
+@code{tieVerticalDirection}.
+";
+}
 \version "1.3.110";
 
 t = \notes \relative c' {   <c e g> ~ <c e g> }
diff --git a/input/test/tie.ly b/input/test/tie.ly
index 4a6d255da6..6cc474c3b6 100644
--- a/input/test/tie.ly
+++ b/input/test/tie.ly
@@ -1,3 +1,9 @@
+\header{
+texidoc="
+Ties are strictly horizontal.  They are placed in between note heads.
+The horizontal middle should not overlap with a staffline.
+";
+}
 \score{
 	\notes\relative c''{
 		%b2~b4~b8~b16~b32~b64 r64\break
diff --git a/input/test/tup.ly b/input/test/tup.ly
index 3619e50709..83c6bce13f 100644
--- a/input/test/tup.ly
+++ b/input/test/tup.ly
@@ -1,3 +1,11 @@
+\header{
+texidoc="
+Tuplets are indicated by a bracket with a number.  There should be no
+bracket if there is one beam that matches  the length of the tuplet.
+The bracket does not interfere with the stafflines, and the number is
+centered in the gap in the bracket.
+";
+}
 \score{
 	\notes \context Voice \relative c'' {
 		 \times 2/3 { \times 2/3 { a8 b c}  c }
diff --git a/scripts/lilypond-book.py b/scripts/lilypond-book.py
index a871fb4298..79f63be70c 100644
--- a/scripts/lilypond-book.py
+++ b/scripts/lilypond-book.py
@@ -4,8 +4,12 @@
 # * Figure out clean set of options. Hmm, isn't it pretty ok now?
 # * add support for .lilyrc
 # * EndLilyPondOutput is def'd as vfil. Causes large white gaps.
+# * texinfo: add support for @pagesize
 
-# todo: dimension handling (all the x2y) is clumsy. 
+# todo: dimension handling (all the x2y) is clumsy. (tca: Thats
+#       because the values are taken directly from texinfo.tex,
+#       geometry.sty and article.cls. Give me a hint, and I'll
+#       fix it.)
 
 # This is was the idea for handling of comments:
 #	Multiline comments, @ignore .. @end ignore is scanned for
@@ -38,7 +42,7 @@ import operator
 
 program_version = '@TOPLEVEL_VERSION@'
 if program_version == '@' + 'TOPLEVEL_VERSION' + '@':
-	program_version = '1.3.106'	
+	program_version = '1.3.113'
 
 include_path = [os.getcwd()]
 
@@ -250,7 +254,7 @@ class LatexPaper:
 
 class TexiPaper:
 	def __init__(self):
-		self.m_papersize = 'a4'
+		self.m_papersize = 'letterpaper'
 		self.m_fontsize = 12
 	def get_linewidth(self):
 		return texi_linewidths[self.m_papersize][self.m_fontsize]
@@ -278,10 +282,11 @@ latex_linewidths = {
 	'executivepaper':{10: 345, 11: 360, 12: 379}}
 
 texi_linewidths = {
-	'a4': {12: 455},
-	'a4wide': {12: 470},
-	'smallbook': {12: 361},
-	'texidefault': {12: 433}}
+	'afourpaper': {12: mm2pt(160)},
+	'afourwide': {12: in2pt(6.5)},
+	'afourlatex': {12: mm2pt(150)},
+	'smallbook': {12: in2pt(5)},
+	'letterpaper': {12: in2pt(6)}}
 
 option_definitions = [
   ('EXT', 'f', 'format', 'set format.  EXT is one of texi and latex.'),
@@ -342,7 +347,9 @@ output_dict= {
 
 # should also support fragment in
 		  
-		  'output-all': r"""@tex
+		  'output-all': r"""
+@include %(fn)s-doc.texi
+@tex
 \catcode`\@=12
 \input lilyponddefs
 \def\EndLilyPondOutput{}
@@ -429,6 +436,8 @@ def get_re (name):
 	return  re_dict[format][name]
 
 def bounding_box_dimensions(fname):
+	if g_outdir:
+		fname = os.path.join(g_outdir, fname)
 	try:
 		fd = open(fname)
 	except IOError:
@@ -562,12 +571,10 @@ def scan_texi_preamble (chunks):
 	idx = 0
 	while 1:
 		if chunks[idx][0] == 'input':
-			if string.find(chunks[idx][1], "@afourpaper") != -1:
-				paperguru.m_papersize = 'a4'
-			elif string.find(chunks[idx][1], "@afourwide") != -1:
-				paperguru.m_papersize = 'a4wide'
-			elif string.find(chunks[idx][1], "@smallbook") != -1:
-				paperguru.m_papersize = 'smallbook'
+			for s in ('afourpaper', 'afourwide', 'letterpaper',
+				  'afourlatex', 'smallbook'):
+				if string.find(chunks[idx][1], "@%s" % s) != -1:
+					paperguru.m_papersize = s
 		idx = idx + 1
 		if idx == 10 or idx == len(chunks):
 			break
@@ -833,6 +840,28 @@ def system (cmd):
 		error ('Error command exited with value %d\n' % st)
 	return st
 
+
+texidoc_re = re.compile (r'.*?\n\s*texidoc\s*=\s*"((([^"])|([^\\]\\"))*)".*', re.DOTALL)
+def extract_texidoc (lyfile):
+	"""
+	Extract the ``texidoc'' entry from the lyfile.ly, and write it to
+	lyfile-doc.texi.
+
+	Maybe this should be output by `lilypond --header=texidoc' or so?
+	"""
+ 	outfile = os.path.basename (os.path.splitext (lyfile)[0]) + "-doc.texi"
+	sys.stderr.write ("Writing `%s'\n" % outfile)
+	f = open (lyfile)
+	s = f.read (-1)
+#	doc = re.sub (r'(.|\n)*?\n\s*texidoc\s*=\s*"((([^"])|([^\\]\\"))*)"(.|\n)*', '\\2', s) + '\n'
+	m = texidoc_re.match (s)
+	doc = ''
+	if m:
+		doc = m.group (1) + '\n'
+	f = open (outfile, 'w')
+	f.write (doc)
+	f.close ()
+
 def compile_all_files (chunks):
 	eps = []
 	tex = []
@@ -866,6 +895,8 @@ def compile_all_files (chunks):
 		lilyopts = string.join (incs, ' ' )
 		texfiles = string.join (tex, ' ')
 		system ('lilypond %s %s' % (lilyopts, texfiles))
+		for i in tex:
+			extract_texidoc (i)
 	for e in eps:
 		system(r"tex '\nonstopmode \input %s'" % e)
 		system(r"dvips -E -o %s %s" % (e + '.eps', e))
diff --git a/stepmake/stepmake/texinfo-rules.make b/stepmake/stepmake/texinfo-rules.make
index 42889ebec3..e24d66435a 100644
--- a/stepmake/stepmake/texinfo-rules.make
+++ b/stepmake/stepmake/texinfo-rules.make
@@ -3,10 +3,10 @@
 .SUFFIXES: .html .info .texi .texinfo
 
 $(outdir)/%.info: $(outdir)/%.texi
-	-$(MAKEINFO) --force --output=$@ $<
+	-$(MAKEINFO) --force -I $(outdir) --output=$@ $<
 
 $(outdir)/%.html: $(outdir)/%.texi
-	-$(MAKEINFO) --force --output=$@ --html --no-split --no-headers $<
+	-$(MAKEINFO) --force -I $(outdir) --output=$@ --html --no-split --no-headers $<
 # we want footers even if website builds (or is built) partly
 	$(footify) $@
 
@@ -22,7 +22,7 @@ $(outdir)/%.dvi:	$(outdir)/%.texi
 	cd $(outdir); texi2dvi ../$< 
 
 $(outdir)/%.txt: $(outdir)/%.texi
-	$(MAKEINFO) -I../  --no-split --no-headers --output $@ $<
+	$(MAKEINFO) -I../ -I $(outdir) --no-split --no-headers --output $@ $<
 
 $(outdir)/%.texi: %.texi
 	rm -f $@