Removes ugly side bars from learning

Please see http://code.google.com/p/lilypond/issues/detail?id=2152 for more detail on what and why.

[PhilEHolmes, 2011-12-29 13:20:21]

Please review

[pkx166h, 2011-12-29 13:42:10]

Just some very minor queries.

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/common-no...
File Documentation/learning/common-notation.itely (right):

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/common-no...
Documentation/learning/common-notation.itely:853: <c e g>\>[ <c f a> <c f a> <c
e g>]\! |
If we're breaking a line then should we re-state the duration.

I.e. <c e g>8\>[ <c ...

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/templates...
File Documentation/learning/templates.itely (right):

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/templates...
Documentation/learning/templates.itely:162:
@lilypondfile[verbatim,quote,ragged-right,texidoc,line-width=140]
Is any merit in preference to editing the snippet than forcing the issue in the
Tex code within the itely file?

[mail_philholmes.net, 2011-12-29 14:06:41]

----- Original Message ----- 
From: <pkx166h@gmail.com>
To: <PhilEHolmes@googlemail.com>; <percivall@gmail.com>; 
<tdanielsmusic@googlemail.com>
Cc: <reply@codereview-hr.appspotmail.com>; <lilypond-devel@gnu.org>
Sent: Thursday, December 29, 2011 1:42 PM
Subject: Re: Removes ugly side bars from learning (issue 5498089)


> Just some very minor queries.
>
>
>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/common-no...
> File Documentation/learning/common-notation.itely (right):
>
>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/common-no...
> Documentation/learning/common-notation.itely:853: <c e g>\>[ <c f a> <c
> f a> <c e g>]\! |
> If we're breaking a line then should we re-state the duration.
>
> I.e. <c e g>8\>[ <c ...

I assume this is not strictly required, but is the style used in the 
manuals?  Fixed in my local copy but won't upload another patch just for 
this.

>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/templates...
> File Documentation/learning/templates.itely (right):
>
>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/templates...
> Documentation/learning/templates.itely:162:
> @lilypondfile[verbatim,quote,ragged-right,texidoc,line-width=140]
> Is any merit in preference to editing the snippet than forcing the issue
> in the Tex code within the itely file?
>
> http://codereview.appspot.com/5498089/

The problem is that the offending part of the score is right-justified, so 
the snippet would need to have either a different page size or not have that 
text entry to work. This was the only way I can think of doing it - it's 
related to issue http://code.google.com/p/lilypond/issues/detail?id=1691 
which has a long and convoluted history.  Given the simplicity of this 
approach I'd rather do this to complete the correction of the manual that a 
lot of other complicated stuff.

In passing I need to mention that I had not implemented the same fix to the 
mensural template, but again I have done locally.  This involves a change to 
the use of \remove "Forbid_line_break_engraver" in snippet 363.

--
Phil Holmes

[Graham Percival, 2011-12-29 18:01:03]

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/common-no...
File Documentation/learning/common-notation.itely (right):

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/common-no...
Documentation/learning/common-notation.itely:853: <c e g>\>[ <c f a> <c f a> <c
e g>]\! |
On 2011/12/29 13:42:10, J_lowe wrote:
> If we're breaking a line then should we re-state the duration.
> 
> I.e. <c e g>8\>[ <c ...

I'm not too fussed about that, but the second line should be indented by two
spaces to indicate that it's a continuation of the previous line (i.e. not
starting its own bar).  I certainly wouldn't object to having an explicit
duration, though!

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/templates...
File Documentation/learning/templates.itely (right):

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/templates...
Documentation/learning/templates.itely:162:
@lilypondfile[verbatim,quote,ragged-right,texidoc,line-width=140]
On 2011/12/29 13:42:10, J_lowe wrote:
> Is any merit in preference to editing the snippet than forcing the issue in
the
> Tex code within the itely file?

I'm not fond of having an explicit line-width.  Could this be done by either
editing the snippet, or giving a papersize  option instead?

I still think that it's a general bug if non-insane .ly code exceeds the bounds
of the box, but I can't remember where we ended up in those bugfixes Reinhold
was doing IIRC half a year ago.

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/tweaks.itely
File Documentation/learning/tweaks.itely (right):

http://codereview.appspot.com/5498089/diff/1/Documentation/learning/tweaks.it...
Documentation/learning/tweaks.itely:4022:
@file{@var{INSTALLDIR}/LilyPond.app/Contents/Resources/share/lilypond/current/}
Please make this an
@example

instead.  The @* syntax is really icky; I think we should only use it if there's
no other way of getting what we want (i.e. forcing a line-break inside a
@warning{} macro, which unfortunately does not allow normal line breaks).

[mail_philholmes.net, 2011-12-30 13:12:38]

----- Original Message ----- 
From: <graham@percival-music.ca>
To: <PhilEHolmes@googlemail.com>; <percivall@gmail.com>; 
<pkx166h@gmail.com>; <tdanielsmusic@googlemail.com>; <mail@philholmes.net>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Thursday, December 29, 2011 6:01 PM
Subject: Re: Removes ugly side bars from learning (issue 5498089)


>
>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/common-no...
> File Documentation/learning/common-notation.itely (right):
>
>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/common-no...
> Documentation/learning/common-notation.itely:853: <c e g>\>[ <c f a> <c
> f a> <c e g>]\! |
> On 2011/12/29 13:42:10, J_lowe wrote:
>> If we're breaking a line then should we re-state the duration.
>
>> I.e. <c e g>8\>[ <c ...
>
> I'm not too fussed about that, but the second line should be indented by
> two spaces to indicate that it's a continuation of the previous line
> (i.e. not starting its own bar).  I certainly wouldn't object to having
> an explicit duration, though!

No problem.  This isn't covered in the CG, AFAICS.

>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/templates...
> File Documentation/learning/templates.itely (right):
>
>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/templates...
> Documentation/learning/templates.itely:162:
> @lilypondfile[verbatim,quote,ragged-right,texidoc,line-width=140]
> On 2011/12/29 13:42:10, J_lowe wrote:
>> Is any merit in preference to editing the snippet than forcing the
> issue in the
>> Tex code within the itely file?
>
> I'm not fond of having an explicit line-width.  Could this be done by
> either editing the snippet, or giving a papersize  option instead?
>
> I still think that it's a general bug if non-insane .ly code exceeds the
> bounds of the box, but I can't remember where we ended up in those
> bugfixes Reinhold was doing IIRC half a year ago.

It's taken me far too long to work out what's going on here.  It's our old 
friend instrument names.  Both the templates cited have material stretching 
to the right of the "page" as well as non-zero-length instrument names.  See 
http://code.google.com/p/lilypond/issues/detail?id=1691 and 
http://code.google.com/p/lilypond/issues/detail?id=766.  So it is a bug, but 
I don't think we should allow a bug to mess up what the LM looks like.  My 
suggestion is to use an explicit line-width with a comment above saying 
something like "@c Line-width is used below because of Issue 766.  If that's 
fixed, it can be removed.".  If we wait for issues like that to be fixed to 
improve the docs, we could have grotty looking docs forever...

FWIW it can be "fixed" by using papersize A6, but this leaves the example 
rather too narrow - line-width produces better looking results, since it's 
more easily adjusted.

>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/tweaks.itely
> File Documentation/learning/tweaks.itely (right):
>
>
http://codereview.appspot.com/5498089/diff/1/Documentation/learning/tweaks.it...
> Documentation/learning/tweaks.itely:4022:
>
@file{@var{INSTALLDIR}/LilyPond.app/Contents/Resources/share/lilypond/current/}
> Please make this an
> @example
>
> instead.  The @* syntax is really icky; I think we should only use it if
> there's no other way of getting what we want (i.e. forcing a line-break
> inside a @warning{} macro, which unfortunately does not allow normal
> line breaks).
>
> http://codereview.appspot.com/5498089/
>

OK - willdo.  Just think all the boxes are a bit unnecessary.

--
Phil Holmes

[Graham Percival, 2011-12-31 01:40:50]

On Fri, Dec 30, 2011 at 01:12:30PM -0000, Phil Holmes wrote:
> >I'm not too fussed about that, but the second line should be indented by
> >two spaces to indicate that it's a continuation of the previous line
> >(i.e. not starting its own bar).  I certainly wouldn't object to having
> >an explicit duration, though!
> 
> No problem.  This isn't covered in the CG, AFAICS.

Yeah, it's part of the unofficial "policy" that I never got around
to writing down.  Sorry.

> >I'm not fond of having an explicit line-width.  Could this be done by
> >either editing the snippet, or giving a papersize  option instead?
> 
> It's taken me far too long to work out what's going on here.
---snip issues 776 and 1691---

> My suggestion is to use an explicit line-width with a
> comment above saying something like "@c Line-width is used below
> because of Issue 766.  If that's fixed, it can be removed.".

ok, let's do that.

> If we wait for issues like that to be fixed to improve the docs,
> we could have grotty looking docs forever...

True.  It's a shame that there isn't more interest in working on
"maintainability" problems, but that's just how things are.

> >Please make this an
> >@example
> 
> OK - willdo.  Just think all the boxes are a bit unnecessary.

I'd be fine with distinguishing between "quick url box" and
"lilypond material box".  I'd like it if the url was indentend on
its own line, but didn't have the yellow box.

ETA: 1 hour if you know what you're doing with texinfo and css;
otherwise 10 hours of frustration.
(could you add this as a tracker issue so we don't forget?)

Cheers,
- Graham

[email_philholmes.net, 2011-12-31 14:51:23]

----- Original Message ----- 
From: "Graham Percival" <graham@percival-music.ca>
To: "Phil Holmes" <mail@philholmes.net>
Cc: <PhilEHolmes@googlemail.com>; <percivall@gmail.com>; 
<pkx166h@gmail.com>; <tdanielsmusic@googlemail.com>; 
<lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Saturday, December 31, 2011 1:40 AM
Subject: Re: Removes ugly side bars from learning (issue 5498089)


> I'd be fine with distinguishing between "quick url box" and
> "lilypond material box".  I'd like it if the url was indentend on
> its own line, but didn't have the yellow box.
>
> ETA: 1 hour if you know what you're doing with texinfo and css;
> otherwise 10 hours of frustration.
> (could you add this as a tracker issue so we don't forget?)

http://code.google.com/p/lilypond/issues/detail?id=2157


--
Phil Holmes

[Graham Percival, 2012-01-02 21:23:30]

could we get those @* turned into @example ?  Just grit your teeth and ignore
the yellow boxes for now?

If you want to add a comment to remind us to change the @example when we have a
better way of doing this, go ahead.

[mail_philholmes.net, 2012-01-03 10:32:28]

----- Original Message ----- 
From: <graham@percival-music.ca>
To: <PhilEHolmes@googlemail.com>; <percivall@gmail.com>; 
<pkx166h@gmail.com>; <tdanielsmusic@googlemail.com>; <mail@philholmes.net>; 
<email@philholmes.net>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Monday, January 02, 2012 9:23 PM
Subject: Re: Removes ugly side bars from learning (issue 5498089)


> could we get those @* turned into @example ?  Just grit your teeth and
> ignore the yellow boxes for now?
>
> If you want to add a comment to remind us to change the @example when we
> have a better way of doing this, go ahead.
>
> http://codereview.appspot.com/5498089/
>

That's what I've done on my local-not-uploaded-for-review copy.

--
Phil Holmes

[percivall, 2012-01-03 10:35:20]

On 3 jan 2012, at 11:32, Phil Holmes wrote:
> ----- Original Message ----- From: <graham@percival-music.ca>
> To: <PhilEHolmes@googlemail.com>; <percivall@gmail.com>; <pkx166h@gmail.com>;
<tdanielsmusic@googlemail.com>; <mail@philholmes.net>; <email@philholmes.net>
> Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
> Sent: Monday, January 02, 2012 9:23 PM
> Subject: Re: Removes ugly side bars from learning (issue 5498089)
> 
> 
>> could we get those @* turned into @example ?  Just grit your teeth and
>> ignore the yellow boxes for now?
>> 
>> If you want to add a comment to remind us to change the @example when we
>> have a better way of doing this, go ahead.
>> 
>> http://codereview.appspot.com/5498089/
>> 
> 
> That's what I've done on my local-not-uploaded-for-review copy.


Please stop including me in these mails.

/Simon