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

[percival . music . ca]

I've done a first pass at this.  General comment: there's more "talking
through the code" than I'd like.  I'm willing to relax this a bit for
Notation 3 instead of Notation 1+2, but I think it can be tightened up a
bit with some work.

Other than that, not bad at all!  I think we're looking at 4-5 drafts,
but definitely manageable in a week.  Good job, Mark and James!


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

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode526
Documentation/notation/input.itely:526: @subsection Creating titles,
headers, and footers
I get nervous when the @subsection doesn't match the @node, but I can't
think of a definitely alternative after a few seconds.  The only serious
alternative at the moment is "Creating titles and headers and footers".
:(

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode548
Documentation/notation/input.itely:548:
@lilypond[quote,verbatim,noragged-right,staffsize=17,indent=13\mm]
First - it's ok to be more "creative" with [options] when we're talking
about spacing stuff.  However, are you certain you need staffsize=17 and
indent=13\mm ?  If you experimented with a few values and decided this
looked best, that's a perfectly acceptable answer!

That said, could you standardize on indent=15\mm, instead of switching
between 13 and 15 ?

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode555
Documentation/notation/input.itely:555: \new Staff \relative g, {
I think the doc policy officially calls for { between the Staff and
\relative, but IMO this is ok syntax.
(you might want to look at the CG, and prepare a patch saying "sometimes
it's ok not to strictly add { everywhere, such as in NR 3, but always do
it in the LM and NR 1+2)

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode584
Documentation/notation/input.itely:584: @example
Do you really need an @example ?  I think this material could be worked
into the following @lilypond.

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode592
Documentation/notation/input.itely:592: #(set-default-paper-size "a5")
I remember discussing this page-size thing before, but I confess that I
can't remember the result of that discussion.  Why does this example
have a #(set-default-paper-size ?

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode597
Documentation/notation/input.itely:597: indent = 0\mm
are you putting indent in the [options], or in \paper ?  If you have a
particular rationale for switching between the two, that's ok, but it
seems weird to me.

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode661
Documentation/notation/input.itely:661: The default settings for
@code{bookTitleMarkup}:
I think the phrase "default settings" is a bit confusing.  99.9% of
readers will never redefine bookTitleMarkup.  I think we should discuss
the redefinition later in this chapter/section, and drop the "default".

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode681
Documentation/notation/input.itely:681: \header {
Does this work?  (a \header by itself, inside a @lilypond)?
Cool!

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode752
Documentation/notation/input.itely:752: The default tagline is a
clickable link (to
Hmm.  Could this be a @lilypond instead?  That way, if we alter the
default tagline at all, it'll be updated automatically here.

http://codereview.appspot.com/4124056/diff/1/Documentation/notation/input.itely#newcode759
Documentation/notation/input.itely:759: The default tagline can be
changed by adding a @code{tagline =} in the
Holy "talking through the code", batman!  Can we revise this?

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