Doc: specify which \header blocks generate PDF metadata

[lilypond.git] / Documentation / notation / input.itely

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index ce33708eac5f57d1fceff81dee2a776e67349bd6..c4224727ed968b3e7bb1843ab875388a3ba7c703 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -1119,9 +1119,9 @@ markup conditionally to header and footer text defined within the
 @code{\paper} block, using the following syntax:
 
 @example
-@code{variable} = @code{\markup} @{
+variable = \markup @{
   @dots{}
-  @code{\on-the-fly}  \@var{procedure}  @var{markup}
+  \on-the-fly  \@var{procedure}  @var{markup}
   @dots{}
 @}
 @end example
@@ -1185,8 +1185,8 @@ Several @code{\on-the-fly} conditions can be combined with an
 @q{and} operation, for example,
 
 @example
-  @code{\on-the-fly \first-page}
-  @code{\on-the-fly \last-page}
+  \on-the-fly \first-page
+  \on-the-fly \last-page
   @code{@{ \markup @dots{} \fromproperty #'header: @dots{} @}}
 @end example
 
@@ -1207,14 +1207,20 @@ Installed Files:
 
 In addition to being shown in the printed output, @code{\header} variables
 are also used to set PDF metadata (the information displayed by PDF readers
-as the @code{properties} of the PDF file).  For example, setting the
-@code{title} property of the @code{header} block @q{Symphony I} will also give
-this title to the PDF document.
+as the @code{properties} of the PDF file).  As metadata are applied per
+output file, only @code{\header} blocks located at top level or within an
+explicit @code{\book} block will be used to generate PDF metadata; while
+@code{\header} variables in a @code{\bookpart} or @code{\score} block
+will be reflected in the printed output of the respective blocks, the
+document-wide PDF metadata will not be affected by headers at that level.
+
+For example, setting the @code{title} property of the @code{header} block
+@q{Symphony I} will also give this title to the PDF document.
 
 @example
-  @code{\header@{}
-    @code{title = "Symphony I"}
-  @code{@}}
+\header@{
+  title = "Symphony I"
+@}
 @end example
 
 If you want to set the title of the printed output to one value, but have the
@@ -1222,10 +1228,10 @@ title property of the PDF to have a different value, you can use
 @code{pdftitle}, as below.
 
 @example
-  @code{\header@{}
-    @code{title = "Symphony I"}
-    @code{pdftitle = "Symphony I by Beethoven"}
-  @code{@}}
+\header@{
+  title = "Symphony I"
+  pdftitle = "Symphony I by Beethoven"
+@}
 @end example
 
 The variables @code{title}, @code{subject}, @code{keywords},