Re: Doc: NR rewrite of 3.2 Titles and Headers (issue4124056)

[percival . music . ca]

Read Usage and play with lilypond-book a bit on your own.
1. I want you to create a Tiny .tely file and compile it to a pdf.
2. play with a few [options] to the @lilypond[]s in your Tiny file.
3. in particular, play with linewidth and textheight or pageheight or
page sizes or \paper { height = 5\mm } or something.

Spending an hour or two playing with these options and/or paper
settings, and checking them out in a TINY .tely file compiled to pdf,
will be *extremely* well-spent time.  Such familiarity with the
[options] wasn't necessary (or even desirable) for 99% of our docs, but
it'll be very useful for the Spacing chapter.

I'm certain that we can have some settings which produce pages so small
that only 1-2 bars fit on them.  Once we have that, it'll be trivially
easy to display tagline, instrument/copyright headers, break-before,
etc.



http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely
File Documentation/notation/input.itely (right):

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode541
Documentation/notation/input.itely:541: outside of the first
@code{\score} of a book, and individual title
I'm not certain about the word "outside".  Do you have a strong
preference against "above" ?  I admit that this doesn't apply to things
like tagline, but the new docs seem to relegate that to a separate @node
anyway.

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode586
Documentation/notation/input.itely:586: @code{print-all-headers = ##t}
inside a @code{\paper} block.
Don't talk through the code.

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode589
Documentation/notation/input.itely:589: blocks by adding @code{##f} to
the Text field.
Don't talk through the code.

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode590
Documentation/notation/input.itely:590:
Replace the previous two paragraphs with this:

Text fields from the main title block of a book can be displayed in all
@code{\score} blocks, or manually suppressed:

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode599
Documentation/notation/input.itely:599: tagline = ##f
If you want to clarify this, add a comment above this line.
% do not this text field:

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode641
Documentation/notation/input.itely:641: @code{bookTitleMarkup} for the
main title block and
I'm confused -- below, you just write
\header {
  dedication = "dedication"
  ...
}

So what the mao is this "bookTitleMarkup" about?  Why should I know or
care about it?


This is a general note about the rewrite -- it's nicely laid out for
people who want to change these variables, but that's at most 5% of
readers.  Most people just want to know how to spell "dedicated" or..
whoops, it's "dedication"... or whether we call it "arranger" or
"editor" or what.

I don't think it'd be hard to write docs that let people seeking easy
answers get them quickly, without making it harder for people wanting to
do complicated stuff.

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode650
Documentation/notation/input.itely:650: These markup variables access
text fields from the @code{\header}
This is way less important than the general layout for stuff like title
and composer; move it to the bottom of this page (or even into another
@node).

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode656
Documentation/notation/input.itely:656: Settings for
@code{bookTitleMarkup}:
If we keep the bookTitleMarkup string at all, how about moving this
whole bit (including @lilypond) into the first itemize in this @node ?

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode689
Documentation/notation/input.itely:689: The default settings for
@code{scoreTitleMarkup} place the @code{piece}
If you're doing the @itemize thing for bookTitleMarkup, then do it here
too.

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode691
Documentation/notation/input.itely:691:
also, if you keep the first @itemize on this page, then consider moving
this into the second @item.  Yes, we can have nested @itemize lists, and
we can have @lilypond inside those nested lists.

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode707
Documentation/notation/input.itely:707: @end example
I'd rather have a @lilypond.

http://codereview.appspot.com/4124056/diff/9001/Documentation/notation/input.itely#newcode767
Documentation/notation/input.itely:767: @node Custom headers footers and
titles
I'm ignoring this subsection for now; let's focus on the first one.

http://codereview.appspot.com/4124056/