[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Documentation missing for extra \header fields available for customizing

From: Heikki Tauriainen
Subject: Documentation missing for extra \header fields available for customizing PDF metadata
Date: Sat, 08 Aug 2015 11:53:54 +0300


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

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 (
https://code.google.com/p/lilypond/issues/detail?id=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.

Heikki Tauriainen

reply via email to

[Prev in Thread] Current Thread [Next in Thread]