Doc: Adjusted CG Policy on @lilypond[] variables

Doc: Adjusted CG Policy on @lilypond[] variables

As a reuslt of work on NR 3.2 Titles and Headers, it was necessary to
define some more explicit requirements for using the variables in the
@lilypond[ ... ] construct. Ssuch as removing staffsize
and page sizes within the actual @lilypond example which only add more noise
to the examples.

Also when the need to show taglines and/or page breaks and footers is required then
\book is needed in the example and this will result in unnecessary white space between top and bottom
of the page. So showing page breaking features or numbering examples becomes
problematic within the documentation.

The new @lilypond[papersize=X] variable allows for explicit page sizing without
the need to include it in the example itself. Allowing for better clarity.

The papersize=X takes variables from the scm/paper.scm else 'a4' is presumed.

Moved existing material to the front of this section so that it makes more sense
and added the new requirements for the various preferred variables.

[Graham Percival (old account), 2011-04-27 16:39:04]

Looks pretty good.

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
File Documentation/contributor/doc-work.itexi (right):

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:314: inlcude the @code{papersize=X}
variable, where @code{X} is an defined
typo.

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:338: documentation.  Do not use the
@code{quote} option with this paper size.
Could I see a Tiny example of why it's bad to use [quote] with that paper size?

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:345: @code{quote} option may need to be
omitted.
What are the considerations about whether to use quote or not?

[Trevor Daniels, 2011-04-27 22:46:32]

A couple of nitpicks; otherwise looks fine.

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
File Documentation/contributor/doc-work.itexi (right):

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:323: and/or single @code{tagline}.
lose the fullstop

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:341: more than two measures of music or
require multiple staffs (i.e. to
staves

[Graham Percival (old account), 2011-04-28 11:43:05]

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
File Documentation/contributor/doc-work.itexi (right):

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:323: and/or single @code{tagline}.
On 2011/04/27 22:46:32, Trevor Daniels wrote:
> lose the fullstop

If the period is removed, it needs to be replaced with something.  We don't
allow text to go directly into an example.  The choices are IIRC : , .
(they're listed in the CG.  I prefer a colon : or period . but if you want to
propose a different punctuation symbol from the list in the CG, that's fine)

[pkx166h, 2011-04-28 13:06:22]

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
File Documentation/contributor/doc-work.itexi (right):

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:314: inlcude the @code{papersize=X}
variable, where @code{X} is an defined
On 2011/04/27 16:39:05, Graham Percival wrote:
> typo.

Done.

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:323: and/or single @code{tagline}.
On 2011/04/28 11:43:05, Graham Percival wrote:
> On 2011/04/27 22:46:32, Trevor Daniels wrote:
> > lose the fullstop
> 
> I prefer a colon :

Colon it is.

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:338: documentation.  Do not use the
@code{quote} option with this paper size.
On 2011/04/27 16:39:05, Graham Percival wrote:
> Could I see a Tiny example of why it's bad to use [quote] with that paper
size?

I'll send you some examples in a separate email.

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:341: more than two measures of music or
require multiple staffs (i.e. to
On 2011/04/27 22:46:32, Trevor Daniels wrote:
> staves

Done.

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:345: @code{quote} option may need to be
omitted.
On 2011/04/27 16:39:05, Graham Percival wrote:
> What are the considerations about whether to use quote or not?

Well it was hard to articulate but if you used quote then depending on the
specific example - you would get a warning during compilation - I'll let you
know when I give you the examples - but also it seemed to squeeze the examples
width-wize, so that again depending on what you were trying to show it wouldn't
look as neat as not using it.

When I omitted it, I saw no negatives, no errors. So in some cases it might make
no difference at all, in others you will get a warning and no notable difference
in the example and in the worst case you get a squashed set of measures and
notes and you get warnings.

[Graham Percival (old account), 2011-04-28 13:15:25]

LGTM.

I still want to see the examples of quote, but if those change anything, then
you can always modify the CG later.  Maybe wait a few hours for Trevor to
comment again, then go ahead and push.

[Trevor Daniels, 2011-04-28 22:40:39]

A few more nitpicks; otherwise looks fine.

[I'm not convinced adding colons before @examples is a good 
thing, especially when the sentence runs on after the
example, but for now that is the policy.]

http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
File Documentation/contributor/doc-work.itexi (right):

http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
Documentation/contributor/doc-work.itexi:314: inlcude the @code{papersize=X}
variable, where @code{X} is a defined
typo, and a superfluous space

http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
Documentation/contributor/doc-work.itexi:327: \header{
\header {

http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
Documentation/contributor/doc-work.itexi:359: Inspirational headwords are
produced with
colon

http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
Documentation/contributor/doc-work.itexi:367: LSR snippets are linked with
colon

[pkx166h, 2011-05-02 16:22:39]

Third draft includes new change from c9landscape to a8landscape - this requires
an approval of

http://codereview.appspot.com/4432088 first as the new paper size is changed in
the file in that patch (didn't think it good form to combine the two).

http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
File Documentation/contributor/doc-work.itexi (right):

http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
Documentation/contributor/doc-work.itexi:314: inlcude the @code{papersize=X}
variable, where @code{X} is a defined
Done the typo..where's the superfluous space? Can't see it for looking!?

http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
Documentation/contributor/doc-work.itexi:327: \header{
On 2011/04/28 22:40:39, Trevor Daniels wrote:

Done.

http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
Documentation/contributor/doc-work.itexi:367: LSR snippets are linked with
On 2011/04/28 22:40:39, Trevor Daniels wrote:

Done.

[t.daniels_treda.co.uk, 2011-05-02 17:32:53]

<pkx166h@gmail.com> wrote  Monday, May 02, 2011 5:22 PM

>
http://codereview.appspot.com/4445070/diff/4001/Documentation/contributor/doc...
> Documentation/contributor/doc-work.itexi:314: inlcude the
> @code{papersize=X} variable, where @code{X} is a defined
> Done the typo..where's the superfluous space? Can't see it for 
> looking!?

Dunno.  Can't see it now.  Must have been an aberration.  Sorry.

Trevor

[Graham Percival (old account), 2011-05-02 18:15:41]

LGTM

[Graham Percival (old account), 2011-05-03 12:36:24]

http://codereview.appspot.com/4445070/diff/5/Documentation/contributor/doc-wo...
File Documentation/contributor/doc-work.itexi (right):

http://codereview.appspot.com/4445070/diff/5/Documentation/contributor/doc-wo...
Documentation/contributor/doc-work.itexi:325:
@lilypond[papersize=a8landscape,verbatim]
this is a .itexi, not a .itely, so you can't use @lilypond.

Change that whole example to a
@example
(and escape all { symbols).

Remember that you can do a quick test of the basic "will it compile" by doing
  touch Documentation/*.te??
  make