Re: Fixes all black bars in NR (issue 6345088)

[Phil Holmes]

----- Original Message ----- 
From: <address@hidden>
To: <address@hidden>; <address@hidden>; 
<address@hidden>; <address@hidden>; <address@hidden>
Cc: <address@hidden>; <address@hidden>
Sent: Wednesday, July 11, 2012 8:45 PM
Subject: Re: Fixes all black bars in NR (issue 6345088)


> I've only looked at the first few files, but I have grave concerns with
> this patch.
>
> I feel terrible about it, though.  Please, PLEASE, anybody who wants to
> make lots of changes to the docs -- spend *at most* one hour working on
> your changes, then submit them to get feedback.  It must have taken a
> long time to do all this, and if it doesn't get accepted this will be a
> real shame.
> (some parts of this patch are obviously good and could be pushed
> directly, but they're all mixed in with parts that I have concerns
> about, so it's problematic)

Probably about 4 or 5 hours, so it's not desperate.  The problem with stuff 
like this is that there's no real point in doing a little bit - you either 
fix the lot or none.  Don't worry about adverse comments - I'm happy to 
receive them providing we remember the aim is to make things better - 
occasionally we stray into keeping the _very_ poor status quo instead of 
implementing a _slightly_ poor change.

> http://codereview.appspot.com/6345088/diff/1/Documentation/notation/fretted-strings.itely
> File Documentation/notation/fretted-strings.itely (right):
>
> http://codereview.appspot.com/6345088/diff/1/Documentation/notation/fretted-strings.itely#newcode1134
> Documentation/notation/fretted-strings.itely:1134: The file
> @file{predefined-ukulele-fretboards.ly} contains the fret
> I'm not a fan of this change.  I'd rather have a manual line-break on
> its own line:
>
> ... are contained in the file
> @*
> @file{blah}

David doesn't like @* so I avoided it.  I'll use @*

> http://codereview.appspot.com/6345088/diff/1/Documentation/notation/fretted-strings.itely#newcode1404
> Documentation/notation/fretted-strings.itely:1404:
> @file{ly/predefined-guitar-fretboards.ly}, @*
> oh god.  Seriously?!  there _has_ to be a better way to make tex behave.
>
> hmm, maybe these could be wrapped in an @example?  it's icky, though.
> Not a serious suggestion.

To be honest, it didn't seem worth worrying about too much.  It's basically 
a list of filenames.  Separating them with line break isn't a big deal, and 
at least allows the user to read them?

> http://codereview.appspot.com/6345088/diff/1/Documentation/notation/input.itely
> File Documentation/notation/input.itely (right):
>
> http://codereview.appspot.com/6345088/diff/1/Documentation/notation/input.itely#newcode1359
> Documentation/notation/input.itely:1359:
> @lilypond[verbatim,papersize=a8landscape]
> why is this necessary?  Does lilypond-book not select the appropriate
> paper size when there's a \book{} inside the example?  If that's the
> case, it should be solved with lilypond-book, not by manually changing
> every @lilypond that involves \book.
>
> (this sounds slightly familiar.  Didn't we have a round of bugfixes in
> lilypond-book on this problem?)

Kind of, but not this one specifically.  Look at the old version - it's 
crap.  This makes it work for an odd example that depends on multiple page 
examples, which are rare.  Also check the CG - 
http://lilypond.org/doc/v2.15/Documentation/contributor/lilypond-formatting  
- a8landscape is specifically recommended.

> http://codereview.appspot.com/6345088/diff/1/Documentation/notation/notation-appendices.itely
> File Documentation/notation/notation-appendices.itely (right):
>
> http://codereview.appspot.com/6345088/diff/1/Documentation/notation/notation-appendices.itely#newcode48
> Documentation/notation/notation-appendices.itely:48: @c The line width
> is a hack to allow space for instrument names
> I really don't like seeing hacks like this in the docs; it's just
> wall-papering over flaws in lilypond itself.  There should be a way to
> tell lilypond "you have this much width on the page", and then lilypond
> should select an appropriate line-width for the first line of the score
> in order to have enough space for the instrument names.
>
> http://codereview.appspot.com/6345088/

Kind-of agreed.  But if there's a flaw in lilypond, we shouldn't make that 
flaw a defining feature by emphasising it in the docs.  My suggestion is 
that you should either fix the flaw or accept the change....

--
Phil Holmes