[Lilypond-auto] Issue 2640 in lilypond: doc enhancement for \headers

[lilypond]

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

New issue 2640 by address@hidden: doc enhancement for \headers
http://code.google.com/p/lilypond/issues/detail?id=2640

is it asking too much to add a full list or table of all the \header
variables supported by default!? this would save users a lot of time
searching for an example/snippet where all of them are shown (actually this
is the 3rd example in
http://www.lilypond.org/doc/v2.15/Documentation/notation/creating-titles-headers-and-footers#title-blocks-explained
3.2.1 Creating titles headers and footers . it is not mentioned that all
variables are listed.

\header is found 75 times in the NR.

imo this would make the NR more a reference than a collection of loosely
connected examples (the examples are still welcome!)

thanks
Eluze


and here is how this could look like:

+++ (right after Title blocks explained or after the Note)

there are 13 variables that can be defined in the \header block and which
will be used by the default header and footnote engraver:

dedication
title
subtitle
subsubtitle
instrument*
poet
composer
meter
arranger
piece**
opus**

tagline
copyright

*  the instrument will be repeated on every page.
** these are printed in a \score when the paper variable print-all-headers
is set to ##f (default)

+++

this list could be enhanced with the position of each item.


Graham Percival address@hidden via gnu.org
Jul 5 (2 days ago)

to -Eluze, bug-lilypond
On Thu, Jul 05, 2012 at 08:05:16AM -0700, -Eluze wrote:
> is it asking too much to add a full list or table of all the \header
> variables supported by default!?

Isn't that done in "Default layout of book and score title blocks"
?  A working example is much more informative than a list or
table.

> this would save users a lot of time
> searching for an example/snippet where all of them are shown (actually  
> this
> is the 3rd example in
> http://www.lilypond.org/doc/v2.15/Documentation/notation/creating-titles-headers-and-footers#title-blocks-explained
> 3.2.1 Creating titles headers and footers . it is not mentioned that all
> variables are listed.

ok, that's fair.  So a sentence should be added to the top of that
subsection, saying "This example demonstrates all \header
variables" ?  That sounds like a good idea.

> and here is how this could look like:

> +++ (right after Title blocks explained or after the Note)

> there are 13 variables that can be defined in the \header block and which
> will be used by the default header and footnote engraver:

The problem with such a list is that it's easy to forget to update
it, and wordy explanations about where items are positioned are
hard to read and write.  The example shows immediately how they're
laid out, what fonts they use, etc.

> instrument*
> piece**
> opus**

> *  the instrument will be repeated on every page.
> ** these are printed in a \score when the paper variable print-all-headers
> is set to ##f (default)

Good points!  It would be nice if that example were extended to
use multiple peices (to show off piece and opus), and had multiple
pages (to show instrument).


-Eluze address@hidden via gnu.org
Jul 5 (2 days ago)

to bug-lilypond
Graham Percival-3 wrote:

> On Thu, Jul 05, 2012 at 08:05:16AM -0700, -Eluze wrote:
> > is it asking too much to add a full list or table of all the \header
> > variables supported by default!?

> Isn't that done in "Default layout of book and score title blocks"
> ?  A working example is much more informative than a list or
> table.

yes and no - the list/table gives you an overview and singular items can be
illustrated with examples (first a little bit of theory and then get
practical…)



> > this would save users a lot of time
> > searching for an example/snippet where all of them are shown (actually
> > this
> > is the 3rd example in
> > http://www.lilypond.org/doc/v2.15/Documentation/notation/creating-titles-headers-and-footers#title-blocks-explained
> > 3.2.1 Creating titles headers and footers . it is not mentioned that all
> > variables are listed.

> ok, that's fair.  So a sentence should be added to the top of that
> subsection, saying "This example demonstrates all \header
> variables" ?  That sounds like a good idea.


exactly



> > and here is how this could look like:

> > +++ (right after Title blocks explained or after the Note)

> > there are 13 variables that can be defined in the \header block and which
> > will be used by the default header and footnote engraver:

> The problem with such a list is that it's easy to forget to update it…


certainly, but a documentation is only worthwhile if it shows the actual
state - I think LilyPond does a great effort to keep documentations
up-to-date and if there's a problem with it this should be attacked from
another starting point.


> > instrument*
> > piece**
> > opus**

> > *  the instrument will be repeated on every page.
> > ** these are printed in a \score when the paper variable
> > print-all-headers
> > is set to ##f (default)

> Good points!  It would be nice if that example were extended to
> use multiple peices (to show off piece and opus), and had multiple
> pages (to show instrument).



I'll try to enlarge the third example

thanks for your feedback!


-Eluze via gnu.org
Jul 5 (2 days ago)

to bug-lilypond
-Eluze wrote:


> I'll try to enlarge the third example


here my suggestion - I changed the comments a little bit (the instrument is
on the same line as the poet and composer):

Default layout of book and score title blocks

[omit the following lines, because the two \paper variables are not
explained here]

 - The layout and formatting of title blocks are controlled by two \paper
variables;
 - bookTitleMarkup for the main \header title block and scoreTitleMarkup for
individual
 - \header blocks within a \score.

+ This example demonstrates all \header variables.

+  http://old.nabble.com/file/p34119867/headerVariables.ly
headerVariables.ly

+ *  the instrument will be repeated on every page.
+ ** only piece and opus are printed in a \score when the paper variable
print-all-headers is set to ##f(default)


maybe the coloring is not needed.

nb: I feel like the default example should come first so users know about
what we are speaking…