Menu ▾ ▴

#4542 Doc: document the extra fields which can be used to customize the metadata specifically for PDF in \headrer blocks

Verified
Phil Holmes
Fixed_2_19_29 (16)
Documentation
2015-10-23
2015-08-08
Anonymous
No

Originally created by: *anonymous

Originally created by: pkx1...@gmail.com
Originally owned by: PhilEHol...@googlemail.com

On 08/08/15 09:53, Heikki Tauriainen wrote:> Hi,
>
> While examining the source code on how \header blocks are used to
> extract information for PDF metadata (to implement the enhancement
> #4539), I discovered that LilyPond actually supports quite an extensive
> (optional) mechanism for customizing PDF metadata independently of the
> information usually specified in the fields (title, subtitle, composer
> etc.) of a \header block, through the use of extra \header fields.
> However, I can't find any mention of this customization mechanism, nor
> examples of using any of the extra fields, in any of the current
> (v2.19.24) manuals.  (The most relevant piece of documentation about
> the supported \header fields that I could find is the "Default layout
> of bookpart and score titles" example in Section 3.2.1 of the Notation
> Reference (v2.19.24) – this example claims to list "all" of the
> available fields.)
>
> I'd consider documenting the extra fields which can be used to
> customize the metadata specifically for PDF files a useful addition to
> the manuals.  Knowledge about the possibility of customizing the
> metadata could be useful in the case where the fields of a \header
> block contain complex LilyPond markup code, which doesn't translate
> into plain text form in a "satisfactory" way automatically.
>
> In short, the implementation appears to support a number of extra
> \header fields which can be used (if defined in a \header block) to
> override the values of the fields listed in the documentation
> specifically for PDF output.  For example, the "pdftitle" \header field
> appears to be available for specifying a title for the PDF metadata
> independently of the value of the "title" field (which is normally used
> to generate a title for the PDF metadata if there's no "pdftitle"
> override present), for example, as
>
>   \header {
>     title = "Title"
>     pdftitle = "PDF Title"
>   }
>
> (The title from the PDF metadata may be shown in a special way to the
> user by the PDF viewer application: for example, evince 3.16.1 will use
> the PDF title as the primary window title.)
>
> Quick experimenting suggests that the value for "pdftitle" appears to
> be first sought from a \book header, and then from a top-level \header,
> although I didn't try to cover all the possible cases of nesting
> various \header blocks. (Overriding the "pdftitle" field in \bookpart
> or \score headers doesn't seem to have any effect, which seems
> reasonable since book parts and scores don't map into separate PDF
> files.)
>
> The full list of fields which appear to be supported for customizing
> PDF metadata is defined in the "handle-metadata" function in
> scm/framework-ps.scm as lines of the form
>
>   (metadata-lookup-output 'pdftitle 'title "Title")
>
> where the first argument to "metadata-lookup-output" looks like the
> \header field name that can be used to customize the value of the
> \header field given in the second argument specifically for PDF output.
>
> ----
>
> As I've modeled the \header field queries for enhancement [#4539]
> albeit in a
> reduced form, after the functionality which was already available for
> PDF output, [#4539] (if it gets accepted) will add a new extra \header
> field "midititle" which can be used to override the name of a MIDI
> sequence (which will, similar to PDF output, get its name from the
> "title" field after [#4539] if no override is present) for MIDI output.
> The "midititle" override will have significance in \header blocks down
> to the "score" level because each score with a \midi block will produce
> a separate MIDI file.
>
> Regards,
> Heikki Tauriainen

Related

Issues: #4539

Discussion

  • Google Importer

    Google Importer - 2015-08-12

    Originally posted by: PhilEHol...@googlemail.com

    I've had a look at the source, and I think the list below is a full list of the header fields that have any effect on the output.  Keywords and subject are a little odd, since they do not feature in the visible output (e.g. PDF or PNG) but only in the metadata, and are effectively simple synonyms for pdfsubject and pdfkeywords.  I propose adding a new section "PDF metadata" before the "3.2.3 Creating footnotes" section of the NR.

    \version "2.19.23"
    \header {
      dedication = "Dedication"
      title = "Title"
      subtitle = "Subtitle"
      subsubtitle = "Subsubtitle"
      instrument = "Instrument"
      poet = "Poet"
      composer = "Composer"
      meter = "Meter"
      arranger = "Arranger"
      tagline = "tagline goes at the bottom of the last page"
      copyright = "copyright goes at the bottom of the first page"
      keywords = "Keywords"
      subject = "Subject"
      pdfcomposer = "pdfComposer"
      pdftitle = "pdfTitle"
      pdfsubject = "pdfSubject"
      pdfkeywords = "pdfKeywords"
      pdfmodDate = "D:20150811160000+01'00'"
      pdfsubtitle = "pdfSubtitle"
      pdfarranger = "pdfArranger"
      pdfpoet = "pdfPoet"
      pdfcopyright = "pdfCopyright"
    }
    \score {
      \header {
        piece = "Piece 1"
        opus = "Opus 1"}
      { c1 \pageBreak c1 }
    }

     

  • Google Importer

    Google Importer - 2015-08-13

    Originally posted by: pkx1...@gmail.com

    (No comment was entered for this change.)

    Owner: PhilEHol...@googlemail.com

     

  • Google Importer

    Google Importer - 2015-08-13

    Originally posted by: pkx1...@gmail.com

    Passes make, make check and a full make doc.

    Labels: -Patch-new Patch-review

     

  • Google Importer

    Google Importer - 2015-08-16

    Originally posted by: pkx1...@gmail.com

    There are some comments from Heikki T. on Rietveld, I am leaving this on review.

     

  • Google Importer

    Google Importer - 2015-08-20

    Originally posted by: pkx1...@gmail.com

    Setting to Needs_work

    Labels: -Patch-review Patch-needs_work

     

  • Trevor Daniels

    Trevor Daniels - 2015-08-29
    • Description has changed:

    Diff:

    --- old
+++ new
@@ -65,6 +65,7 @@
 > ----
 > 
 > As I've modeled the \header field queries for enhancement \#4539 \(
+> [#4539]
 > [https://code.google.com/p/lilypond/issues/detail?id=4539](#4539)\), albeit in a
 > reduced form, after the functionality which was already available for
 > PDF output, \#4539 \(if it gets accepted\) will add a new extra \header
    • Needs: --> design
     

  • Trevor Daniels

    Trevor Daniels - 2015-08-29
    • Description has changed:

    Diff:

    --- old
+++ new
@@ -64,14 +64,13 @@
 > 
 > ----
 > 
-> As I've modeled the \header field queries for enhancement \#4539 \(
-> [#4539]
-> [https://code.google.com/p/lilypond/issues/detail?id=4539](#4539)\), albeit in a
+> As I've modeled the \header field queries for enhancement [#4539] \(
+> was [https://code.google.com/p/lilypond/issues/detail?id=4539](#4539)\), albeit in a
 > reduced form, after the functionality which was already available for
-> PDF output, \#4539 \(if it gets accepted\) will add a new extra \header
+> PDF output, [#4539] \(if it gets accepted\) will add a new extra \header
 > field "midititle" which can be used to override the name of a MIDI
 > sequence \(which will, similar to PDF output, get its name from the
-> "title" field after \#4539 if no override is present\) for MIDI output.
+> "title" field after [#4539] if no override is present\) for MIDI output.
 > The "midititle" override will have significance in \header blocks down
 > to the "score" level because each score with a \midi block will produce
 > a separate MIDI file.
     

  • Trevor Daniels

    Trevor Daniels - 2015-08-29
    • Description has changed:

    Diff:

    --- old
+++ new
@@ -64,8 +64,8 @@
 > 
 > ----
 > 
-> As I've modeled the \header field queries for enhancement [#4539] \(
-> was [https://code.google.com/p/lilypond/issues/detail?id=4539](#4539)\), albeit in a
+> As I've modeled the \header field queries for enhancement [#4539]
+> albeit in a
 > reduced form, after the functionality which was already available for
 > PDF output, [#4539] \(if it gets accepted\) will add a new extra \header
 > field "midititle" which can be used to override the name of a MIDI
     

  • Phil Holmes

    Phil Holmes - 2015-09-24
    • Patch: needs_work --> new
     

  • Phil Holmes

    Phil Holmes - 2015-09-24
     

  • Phil Holmes

    Phil Holmes - 2015-09-24
    • status: Accepted --> Started
     

  • Anonymous

    Anonymous - 2015-09-26
    • Patch: new --> review
     

  • Anonymous

    Anonymous - 2015-09-26

    Passes make, make check and a full make doc.

     

  • Trevor Daniels

    Trevor Daniels - 2015-09-26
    • assigned_to: Phil Holmes
     

  • Anonymous

    Anonymous - 2015-09-29
    • Patch: review --> countdown
     

  • Anonymous

    Anonymous - 2015-09-29

    Patch on countdown for October 2nd.

     

  • Anonymous

    Anonymous - 2015-10-02
    • Patch: countdown --> push
     

  • Anonymous

    Anonymous - 2015-10-02

    Patch counted down - please push

     

  • Phil Holmes

    Phil Holmes - 2015-10-02

    Pushed to staging as:

    a22f2ad68fccb81e52f805ba69cb8c0e6bf8cd82

     

  • Phil Holmes

    Phil Holmes - 2015-10-02
    • labels: --> Fixed_2_19_29
    • status: Started --> Fixed
    • Needs: design -->
    • Patch: push -->
     

  • Federico Bruni

    Federico Bruni - 2015-10-23
    • status: Fixed --> Verified