X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Finput.itely;h=c109df7b28ec497d7826252853cd8fde669786dd;hb=8211950f0931c4d8a0e18ee9e436e489bd583dbd;hp=a5b04b4b2414171179a2ab7b155a8c894a6ab906;hpb=7f8b09731f6eb683dcde1114cdfc1ae2607e47c1;p=lilypond.git

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index a5b04b4b24..c109df7b28 100644
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -277,7 +277,7 @@ Lilypond provides facilities to allow you to control what file names
 are used by the various back-ends when producing output files.
 
 In the previous section, we saw how Lilypond prevents name-clashes when
-producing several ouputs from a single source file.  You also have the
+producing several outputs from a single source file.  You also have the
 ability to specify your own suffixes for each @code{\book} block, so
 for example you can produce files called
 @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
@@ -521,12 +521,17 @@ Notation Reference:
 @node Titles and headers
 @section Titles and headers
 
+@cindex titles
+@cindex headers
+@cindex footers
+
 Almost all printed music includes a title and the composer's name;
 some pieces include a lot more information.
 
 @menu
 * Creating titles headers and footers::
 * Custom titles headers and footers::
+* Creating PDF metadata::
 * Creating footnotes::
 * Reference to page numbers::
 * Table of contents::
@@ -681,7 +686,7 @@ suppressed:
   \header {
     title = "DAS WOHLTEMPERIRTE CLAVIER"
     subtitle = "TEIL I"
-    % Do not display the tagline for this book
+    % Do not display the default LilyPond footer for this book
     tagline = ##f
   }
   \markup { \vspace #1 }
@@ -723,7 +728,7 @@ Notation Reference:
 @node Default layout of bookpart and score titles
 @unnumberedsubsubsec Default layout of bookpart and score titles
 
-This example demonstrates all @code{\header} variables:
+This example demonstrates all printed @code{\header} variables:
 
 @lilypond[papersize=a6landscape,quote,verbatim,noragged-right]
 \book {
@@ -742,8 +747,8 @@ This example demonstrates all @code{\header} variables:
     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"
+    tagline = "The tagline goes at the bottom of the last page"
+    copyright = "The copyright goes at the bottom of the first page"
   }
   \score {
     { s1 }
@@ -875,8 +880,8 @@ the @code{copyright} text if there is only a single page.
 
 @end itemize
 
-The default tagline can be changed by adding a @code{tagline} in the
-top-level @code{\header} block.
+The default LilyPond footer text can be changed by adding a
+@code{tagline} in the top-level @code{\header} block.
 
 @lilypond[papersize=a8landscape,verbatim]
 \book {
@@ -891,7 +896,8 @@ top-level @code{\header} block.
 }
 @end lilypond
 
-To remove the @code{tagline} set the value to @code{##f}.
+To remove the default LilyPond footer text, the @code{tagline} can be
+set to @code{##f}.
 
 
 @node Custom titles headers and footers
@@ -1194,6 +1200,44 @@ Notation Reference:
 Installed Files:
 @file{../ly/titling-init.ly}.
 
+@node Creating PDF metadata
+@subsection Creating PDF metadata
+
+@cindex PDF 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).  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{@}}
+@end example
+
+If you want to set the title of the printed output to one value, but have the
+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{@}}
+@end example
+
+The variables @code{title}, @code{subject}, @code{keywords},
+@code{subtitle}, @code{composer}, @code{arranger}, @code{poet}, @code{author}
+and @code{copyright} all set PDF properties and can all be prefixed with
+@q{pdf} to set a PDF property to a value different from the printed output.
+
+The PDF property @code{Creator} is automatically set to @q{LilyPond} plus
+the current LilyPond version, and @code{CreationDate} and @code{ModDate} are
+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.
 
 @node Creating footnotes
 @subsection Creating footnotes
@@ -1693,10 +1737,11 @@ ie. a two digit number.
 
 @node Table of contents
 @subsection Table of contents
-A table of contents is included using the @code{\markuplist \table-of-contents}
-command.  The elements which should appear in the table of contents are
-entered with the @code{\tocItem} command, which may be used either at
-top-level, or inside a music expression.
+A table of contents is included using the
+@code{\markuplist \table-of-contents} command.  The elements which
+should appear in the table of contents are entered with the
+@code{\tocItem} command, which may be used either at top-level, or
+inside a music expression.
 
 @verbatim
 \markuplist \table-of-contents
@@ -1719,39 +1764,89 @@ top-level, or inside a music expression.
 }
 @end verbatim
 
-The markups which are used to format the table of contents are defined
-in the @code{\paper} block.  The default ones are @code{tocTitleMarkup},
-for formatting the title of the table, and @code{tocItemMarkup}, for
-formatting the toc elements, composed of the element title and page
-number.  These variables may be changed by the user:
+Markups used for formatting the table of contents are defined in the
+@code{\paper} block.  There are two @q{pre-defined} markups already
+available;
+
+@itemize
+
+@item
+@code{tocTitleMarkup}
+
+@noindent
+Used for formatting the title of the table of contents.
+
+@verbatim
+tocTitleMarkup = \markup \huge \column {
+  \fill-line { \null "Table of Contents" \null }
+  \null
+}
+@end verbatim
+
+@item
+@code{tocItemMarkup}
+
+@noindent
+Used for formatting the elements within the table of contents.
+
+@verbatim
+tocItemMarkup = \markup \fill-line {
+  \fromproperty #'toc:text \fromproperty #'toc:page
+}
+@end verbatim
+
+@end itemize
+
+@noindent
+Both of these variables can be changed.
+
+Here is an example changing the table of contents' title into French;
 
 @verbatim
 \paper {
-  %% Translate the toc title into French:
   tocTitleMarkup = \markup \huge \column {
     \fill-line { \null "Table des matières" \null }
     \hspace #1
   }
-  %% use larger font size
-  tocItemMarkup = \markup \large \fill-line {
-    \fromproperty #'toc:text \fromproperty #'toc:page
-  }
+@end verbatim
+
+Here is an example changing the font-size of the elements in the table
+of contents;
+
+@verbatim
+tocItemMarkup = \markup \large \fill-line {
+  \fromproperty #'toc:text \fromproperty #'toc:page
 }
 @end verbatim
 
-Note how the toc element text and page number are referred to in
-the @code{tocItemMarkup} definition.
+Note how the element text and page numbers are referred to in the
+@code{tocItemMarkup} definition.
 
-New commands and markups may also be defined to build more elaborated
-table of contents:
-@itemize
-@item first, define a new markup variable in the @code{\paper} block
-@item then, define a music function which aims at adding a toc element
-using this markup paper variable.
-@end itemize
+The @code{\tocItemWithDotsMarkup} command can be included within the
+@code{tocItemMarkup} to fill the line, between a table of contents item
+and its corresponding page number, with dots;
 
-In the following example, a new style is defined for entering act names
-in the table of contents of an opera:
+@lilypond[verbatim,line-width=10.0\cm]
+\header { tagline = ##f }
+\paper {
+  tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+  \markuplist \table-of-contents
+  \tocItem \markup { Allegro }
+  \tocItem \markup { Largo }
+  \markup \null
+}
+@end lilypond
+
+Custom commands with their own markups can also be defined to build a
+more complex table of contents.  In the following example, a new style
+is defined for entering act names in a table of contents of an opera;
+
+@noindent
+A new markup variable (called @code{tocActMarkup}) is defined in the
+@code{\paper} block;
 
 @verbatim
 \paper {
@@ -1761,12 +1856,22 @@ in the table of contents of an opera:
     \hspace #1
   }
 }
+@end verbatim
 
+@noindent
+A custom music function (@code{tocAct}) is then created -- which uses
+the new @code{tocActMarkup} markup definition.
+
+@verbatim
 tocAct =
-#(define-music-function (text) (markup?)
-   (add-toc-item! 'tocActMarkup text))
+  #(define-music-function (text) (markup?)
+     (add-toc-item! 'tocActMarkup text))
 @end verbatim
 
+@noindent
+A LilyPond input file, using these customer definitions, could look
+something like this;
+
 @lilypond[line-width=10.0\cm]
 \header { tagline = ##f }
 \paper {
@@ -1793,21 +1898,19 @@ tocAct =
 }
 @end lilypond
 
-Dots can be added to fill the line between an item and its page number:
 
-@lilypond[verbatim,line-width=10.0\cm]
-\header { tagline = ##f }
-\paper {
-  tocItemMarkup = \tocItemWithDotsMarkup
-}
+Here is an example of the @code{\fill-with-pattern} command used within
+the context of a table of contents;
 
-\book {
-  \markuplist \table-of-contents
-  \tocItem \markup { Allegro }
-  \tocItem \markup { Largo }
-  \markup \null
+@verbatim
+\paper {
+  tocItemMarkup = \markup { \fill-line {
+    \override #'(line-width . 70)
+    \fill-with-pattern #1.5 #CENTER . \fromproperty #'toc:text \fromproperty #'toc:page
+    }
+  }
 }
-@end lilypond
+@end verbatim
 
 @seealso
 Installed Files:
@@ -2023,7 +2126,7 @@ sopranoMusic = \relative { a'4 b c b8( a) }
 altoMusic = \relative { e'4 e e f }
 tenorMusic = \relative { c'4 b e d8( c) }
 bassMusic = \relative { a4 gis a d, }
-allLyrics = \lyricmode {King of glo -- ry }
+allLyrics = \lyricmode { King of glo -- ry }
 <<
   \new Staff = "Soprano" \sopranoMusic
   \new Lyrics \allLyrics
@@ -2041,17 +2144,11 @@ allLyrics = \lyricmode {King of glo -- ry }
   \new Lyrics \allLyrics
   \new PianoStaff <<
     \new Staff = "RH" {
-      \set Staff.printPartCombineTexts = ##f
-      \partcombine
-      \sopranoMusic
-      \altoMusic
+      \partcombine \sopranoMusic \altoMusic
     }
     \new Staff = "LH" {
-      \set Staff.printPartCombineTexts = ##f
       \clef "bass"
-      \partcombine
-      \tenorMusic
-      \bassMusic
+      \partcombine \tenorMusic \bassMusic
     }
   >>
 >>
@@ -2562,7 +2659,7 @@ By default, each music fragment will be output as a separate @code{EPS}
 file, but other formats such as @code{PDF} or @code{PNG} can also be
 created if required.  The extracted music is output as if had been
 literally @q{cut} from the original printed score so if a fragment runs
-over one or more lines, a separate ouput file for each line will be
+over one or more lines, a separate output file for each line will be
 generated.
 
 @seealso
@@ -3439,7 +3536,7 @@ Notes that do not have any articulations attached to them may also be
 shortened; so to compensate for this, restrict the use of the
 @code{\articulate} function to shorter segments of music or modify the
 values of the variables defined in the @file{articulate} script to
-compenstate for the note-shortening behavior.}
+compentate for the note-shortening behavior.}