[Lilypond-auto] Issue 4542 in lilypond: Doc: document the extra fields which can be used to customize the metadata specifically for PDF in \headrer blocks

[lilypond]

Status: Accepted
Owner: ----
Labels: Type-Documentation

New issue 4542 by address@hidden: Doc: document the extra fields which  
can be used to customize the metadata specifically for PDF in \headrer  
blocks
https://code.google.com/p/lilypond/issues/detail?id=4542

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 (
> 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.

> Regards,
> Heikki Tauriainen

--
You received this message because this project is configured to send all  
issue notifications to this address.
You may adjust your notification preferences at:
https://code.google.com/hosting/settings