Doc: clarify \header variables (2640) (issue 6456047)

[tdanielsmusic]

Reviewers: eluzew_gmail.com,

Message:
I believe this doc change should be ok, but as I
am unable to easily do a full doc build it would
be helpful if a reviewer could offer to test this
for me and check the new example looks correct.

Trevor


Description:
Doc: clarify \header variables (2640)

  Revised example and text submitted by Eluse - thanks!

  a7landscape paper size added to suit this example

Please review this at http://codereview.appspot.com/6456047/

Affected files:
  M Documentation/notation/input.itely
  M scm/paper.scm


Index: Documentation/notation/input.itely
diff --git a/Documentation/notation/input.itely  
b/Documentation/notation/input.itely
index  
fe0af3b5daf4aaddcf320def4da0602a2dfaaea9..608195ab15b44f9acdd5991f7508378005de9e5b  
100644
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -640,47 +640,78 @@ Notation Reference:
 @node Default layout of book and score title blocks
 @unnumberedsubsubsec Default layout of book and score title blocks

-The layout and formatting of title blocks are controlled by two
address@hidden variables; @code{bookTitleMarkup} for the main
address@hidden title block and @code{scoreTitleMarkup} for individual
address@hidden blocks within a @code{\score}.
+This example demonstrates all @code{\header} variables:

address@hidden,quote,verbatim,noragged-right]
-\header {
-  % The following fields are centered
-  dedication = "Dedication"
-  title = "Title"
-  subtitle = "Subtitle"
-  subsubtitle = "Subsubtitle"
-  instrument = "Instrument"
-
-  % The following fields are left-aligned on the left side
-  poet = "Poet"
-  meter = "Meter"
-
-  % The following fields are right-aligned on the right side
-  composer = "Composer"
-  arranger = "Arranger"
-}
-
-\score {
-  { s1 }
address@hidden,quote,verbatim,noragged-right]
+\book {
   \header {
-    % The following fields are placed at opposite ends of the same line
-    piece = "Piece"
-    opus = "Opus"
+      % The following fields are centered
+    dedication = "Dedication"
+    title = "Title"
+    subtitle = "Subtitle"
+    subsubtitle = "Subsubtitle"
+      % The following fields are evenly spread on one line
+      % the field "instrument" also appears on following pages
+    instrument = \markup \with-color #green "Instrument"
+    poet = "Poet"
+    composer = "Composer"
+      % The following fields are placed at opposite ends of the same line
+    meter = "Meter"
+    arranger = "Arranger"
+      % The following fields are centered at the bottom
+    tagline = "tagline goes at the bottom of the last page"
+    copyright = "copyright goes at the bottom of the first page"
+  }
+  \score {
+    { s1 }
+    \header {
+        % The following fields are placed at opposite ends of the same line
+      piece = "Piece 1"
+      opus = "Opus 1"
+    }
+  }
+  \score {
+    { s1 }
+    \header {
+        % The following fields are placed at opposite ends of the same line
+      piece = "Piece 2 on the same page"
+      opus = "Opus 2"
+    }
+  }
+  \pageBreak
+  \score {
+    { s1 }
+    \header {
+        % The following fields are placed at opposite ends of the same line
+      piece = "Piece 3 on a new page"
+      opus = "Opus 3"
+    }
   }
 }
 @end lilypond

address@hidden Is the bit about \null markups true? -mp
+Note that
+
address@hidden
address@hidden
+The instrument name will be repeated on every page.
+
address@hidden
+Only @code{piece} and @code{opus} are printed in a @code{\score}
+when the paper variable @code{print-all-headers} is set to
address@hidden (the default).

address@hidden
address@hidden Is the bit about \null markups true? -mp
 Text fields left unset in a @code{\header} block are replaced with
 @code{\null} markups so that the space is not wasted.

address@hidden
 The default settings for @code{scoreTitleMarkup} place the @code{piece}
 and @code{opus} text fields at opposite ends of the same line.

address@hidden itemize
+
 @cindex breakbefore

 Use the @code{breakbefore} variable inside a @code{\header} block
Index: scm/paper.scm
diff --git a/scm/paper.scm b/scm/paper.scm
index  
e076d692a301dc0098d44fa5f8d9df556b8118d5..f482d9b9b79f8419af2fa48327a9314d4e7197d7  
100644
--- a/scm/paper.scm
+++ b/scm/paper.scm
@@ -238,8 +238,9 @@
     ;; F4 used in southeast Asia and Australia
     ("f4" . (cons (* 210 mm) (* 330 mm)))
     ;; Used for very small @lilypond examples in the Documentation
-    ;; based on a8 size but landscape not portrait
+    ;; based on a8 and a7 sizes but landscape not portrait
     ("a8landscape" . (cons (* 74 mm) (* 52 mm)))
+    ("a7landscape" . (cons (* 105 mm) (* 74 mm)))
     ))

 ;; todo: take dimension arguments.