Re: Doc: Adjusted CG Policy on @lilypond[] variables (issue4445070)

[pkx166h]

Reviewers: Graham Percival, Trevor Daniels,


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

http://codereview.appspot.com/4445070/diff/1/Documentation/contributor/doc-work.itexi#newcode314
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-work.itexi#newcode323
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-work.itexi#newcode338
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-work.itexi#newcode341
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-work.itexi#newcode345
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.

Description:
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.

Please review this at http://codereview.appspot.com/4445070/

Affected files:
  M Documentation/contributor/doc-work.itexi