Doc: Describe the "midititle" \header variable (issue 303080043 by address@hidden)

[ht . lilypond . development]

Reviewers: ,

Message:
Hi,

I'm sorry to edit the NR section on output file metadata so soon after
Issue 4921 was fixed, but that issue actually reminded me about the
missing documentation for the "midititle" header variable (which can be
used to set the sequence name for MIDI files independently of the
contents of "title"), so here's a patch to generalize the section on
output file metadata (to not speak only of PDF files; I hope the point
of Issue 4921 is still clear enough), and add the missing piece of
documentation.

Thanks,
--
Heikki Tauriainen


Description:
Doc: Describe the "midititle" \header variable

Please review this at https://codereview.appspot.com/303080043/

Affected files (+20, -12 lines):
  M Documentation/notation/input.itely


Index: Documentation/notation/input.itely
diff --git a/Documentation/notation/input.itely  
b/Documentation/notation/input.itely
index  
c4224727ed968b3e7bb1843ab875388a3ba7c703..654daafe28670691baf9b5a329e132165768c0b4  
100644
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -531,7 +531,7 @@ some pieces include a lot more information.
 @menu
 * Creating titles headers and footers::
 * Custom titles headers and footers::
-* Creating PDF metadata::
+* Creating output file metadata::
 * Creating footnotes::
 * Reference to page numbers::
 * Table of contents::
@@ -1200,22 +1200,25 @@ Notation Reference:
 Installed Files:
 @file{../ly/titling-init.ly}.

address@hidden Creating PDF metadata
address@hidden Creating PDF metadata
address@hidden Creating output file metadata
address@hidden Creating output file metadata

 @cindex PDF metadata
address@hidden MIDI metadata

 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).  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
address@hidden 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.
+are also used to set metadata for output files.  For example, with PDF
+files, this metadata could be displayed by PDF readers as the
address@hidden of the PDF file.  For each type of output file, only the
address@hidden definitions of blocks that define separate files of that
+type, and blocks higher in the block hierarchy, will be consulted.
+Therefore, for PDF files, only the @code{\book} level and the top level
address@hidden definitions affect the document-wide PDF metadata, whereas
+for MIDI files, all headers above or at the @code{\score} level are used.

 For example, setting the @code{title} property of the @code{header} block
address@hidden I} will also give this title to the PDF document.
+to @q{Symphony I} will also give this title to the PDF document, and use
+it as the sequence name of the MIDI file.

 @example
 address@hidden
@@ -1245,6 +1248,10 @@ both set to the current date and time.   
@code{ModDate} can be overridden by
 setting the header variable @code{moddate} (or @code{pdfmoddate}) to a
 valid PDF date string.

+The @code{title} variable sets also the sequence name for MIDI.  The
address@hidden variable can be used to set the sequence name
+independently of the value used for typeset output.
+
 @node Creating footnotes
 @subsection Creating footnotes

@@ -2958,7 +2965,8 @@ either the @code{\book}, @code{\bookpart} or  
@code{\score} blocks.  See

 @seealso
 Notation Reference:
address@hidden structure}.
address@hidden structure},
address@hidden output file metadata}.

 Installed Files:
 @file{scm/midi.scm}.