Doc: rename section in LM (3280)

Doc: rename section in LM (3280)

  In the LM, the word "tweaks" is used both generically, meaning
  "modifying LilyPond's action", and specifically to refer to the
  \tweak command.  The old section heading used the word in the former
  sense, but this was confusing as the section dealt exclusively
  with \override commands.

[Graham Percival, 2013-04-11 22:37:41]

I think it would be nicer if we could find a word that wasn't a command word
("modifications"?  "adjustments" ?  "customizations"?) but I agree that in this
case "override" is better than "tweak".

[Trevor Daniels, 2013-04-12 09:31:17]

On 2013/04/11 22:37:41, Graham Percival wrote:
> I think it would be nicer if we could find a word that wasn't a command word
> ("modifications"?  "adjustments" ?  "customizations"?) but I agree that in
this
> case "override" is better than "tweak".

Yes, we need a word or phrase that can be used to replace
tweaks and tweaking in all the places where they are used
generically, leaving tweaks and tweaking to refer to the
specific use of \tweak as a command.  Earlier, when \tweak 
as a comand was rarely used, no confusion arose, but now that
\tweak is more useful and is appearing more frequently in
replies and documentation I think the time has come to make
the change.  Although long, I think "fine-tuning the layout"
captures the generic meaning of tweaking quite well, and once
introduced it could be shortened to just "fine-tuning".  The
noun could be "fine-tuning adjustments."

So this section could entitled "Using variables for fine-tuning"
or "Using variables for fine-tuning the layout".

The main difficulty with this, and the reason why I'm looking
for further comment, is that many tweaks and overrides are rather
more than _fine_-tuning, but I think I could live with this.

Trevor

[dak, 2013-04-12 09:39:07]

On 2013/04/12 09:31:17, Trevor Daniels wrote:
> On 2013/04/11 22:37:41, Graham Percival wrote:
> > I think it would be nicer if we could find a word that wasn't a command word
> > ("modifications"?  "adjustments" ?  "customizations"?) but I agree that in
> this
> > case "override" is better than "tweak".
> 
> Yes, we need a word or phrase that can be used to replace
> tweaks and tweaking in all the places where they are used
> generically, leaving tweaks and tweaking to refer to the
> specific use of \tweak as a command.  Earlier, when \tweak 
> as a comand was rarely used, no confusion arose, but now that
> \tweak is more useful and is appearing more frequently in
> replies and documentation I think the time has come to make
> the change.  Although long, I think "fine-tuning the layout"
> captures the generic meaning of tweaking quite well, and once
> introduced it could be shortened to just "fine-tuning".  The
> noun could be "fine-tuning adjustments."
> 
> So this section could entitled "Using variables for fine-tuning"
> or "Using variables for fine-tuning the layout".
> 
> The main difficulty with this, and the reason why I'm looking
> for further comment, is that many tweaks and overrides are rather
> more than _fine_-tuning, but I think I could live with this.

It's not really "fine-tuning", and "tuning" alone has strange connotations.

I think "retouching" is pretty much on spot.  Asking the thesaurus does not
really deliver anything more convincing:

From Moby Thesaurus II by Grady Ward, 1.0 [moby-thes]:

  40 Moby Thesaurus words for "retouch":
     adjust, adulterate, brighten up, brush up, cook, correct, doctor,
     fake, finish, fix, freshen, furbish, furbish up, improve, juggle,
     load, manipulate, pack, plant, polish, polish up, recondition,
     refresh, renovate, repair, restore, revive, rig, rub up, salt,
     shine, sophisticate, spruce, spruce up, stack, tamper with,
     tone up, touch up, vamp, vamp up

[mail_philholmes.net, 2013-04-12 10:26:46]

----- Original Message ----- 
From: <dak@gnu.org>
To: <tdanielsmusic@googlemail.com>; <graham@percival-music.ca>
Cc: <reply@codereview-hr.appspotmail.com>; <lilypond-devel@gnu.org>
Sent: Friday, April 12, 2013 10:39 AM
Subject: Re: Doc: rename section in LM (3280) (issue 8575044)


> On 2013/04/12 09:31:17, Trevor Daniels wrote:
>> On 2013/04/11 22:37:41, Graham Percival wrote:
>> > I think it would be nicer if we could find a word that wasn't a
> command word
>> > ("modifications"?  "adjustments" ?  "customizations"?) but I agree
> that in
>> this
>> > case "override" is better than "tweak".
>
>> Yes, we need a word or phrase that can be used to replace
>> tweaks and tweaking in all the places where they are used
>> generically, leaving tweaks and tweaking to refer to the
>> specific use of \tweak as a command.  Earlier, when \tweak
>> as a comand was rarely used, no confusion arose, but now that
>> \tweak is more useful and is appearing more frequently in
>> replies and documentation I think the time has come to make
>> the change.  Although long, I think "fine-tuning the layout"
>> captures the generic meaning of tweaking quite well, and once
>> introduced it could be shortened to just "fine-tuning".  The
>> noun could be "fine-tuning adjustments."
>
>> So this section could entitled "Using variables for fine-tuning"
>> or "Using variables for fine-tuning the layout".
>
>> The main difficulty with this, and the reason why I'm looking
>> for further comment, is that many tweaks and overrides are rather
>> more than _fine_-tuning, but I think I could live with this.
>
> It's not really "fine-tuning", and "tuning" alone has strange
> connotations.
>
> I think "retouching" is pretty much on spot.  Asking the thesaurus does
> not really deliver anything more convincing:


Sorry - I don't agree.  In native English, retouching has a strong 
connotation of dabbing something like paint over another patch of paint to 
correct something that doesn't look right.  PhotoShop-type programs are 
known for their retouching ability.  In contract, fine-tuning is taking 
something that's fairly OK as it is and making it better - exactly what 
we've considered to be a tweak.  IMO fine-tuning is a perfectly acceptable 
description - retouching would not work.

The tuning/tweak stuff potentially arises from a motoring connotation - 
"Demon Tweeks" (commercial spelling) were well known for selling car tuning 
parts.

--
Phil Holmes 

[dak, 2013-04-12 10:41:40]

On 2013/04/12 10:26:46, mail_philholmes.net wrote:
> ----- Original Message ----- 
> From: <mailto:dak@gnu.org>

> > I think "retouching" is pretty much on spot.  Asking the thesaurus does
> > not really deliver anything more convincing:
> 
> 
> Sorry - I don't agree.  In native English, retouching has a strong
> connotation of dabbing something like paint over another patch of
> paint to correct something that doesn't look right.

And indeed, the very first actual code example in the "tweaks" section
changes notehead colours to green and red.

> PhotoShop-type programs are known for their retouching ability.  In
> contract, fine-tuning is taking something that's fairly OK as it is
> and making it better - exactly what we've considered to be a tweak.
> IMO fine-tuning is a perfectly acceptable description - retouching
> would not work.

How is coloring noteheads green and red "fine-tuning"?

I suspect you are objecting to the naming change without looking at
the actual contents of the section, just judging from its old name or
your memory.

The section isn't about fine-tuning (though it is helpful when
fine-tuning is your goal).  Indeed, since we don't want to rewrite the
section all the time just because LilyPond keeps getting better, the
examples in this section tend _not_ to be fine-tuning but rather
pretty thorough changes.  Changes that won't get redundant when
LilyPond gets better.

There _has_ been more documentation of fine-tuning changes in historic
times but many of them got thrown out eventually because they stopped
having an effect or made things worse as LilyPond got better out of
the box.

[janek, 2013-04-12 11:36:39]

For me "adjustments" would be probably best.  Adjustments can be big or small,
and - as far as i understand this word - can mean both adjusting something
that's wrong so that it'll be correct, and changing something according to one's
arbitrary tastes.

best,
Janek

[Trevor Daniels, 2013-04-12 12:02:23]

On 2013/04/12 11:36:39, janek wrote:
> For me "adjustments" would be probably best.  Adjustments can be big or small,
> and - as far as i understand this word - can mean both adjusting something
> that's wrong so that it'll be correct, and changing something according to
one's
> arbitrary tastes.

I'm inclined to agree, although maybe "manual adjustments" and
"manually adjusting" might be more suitable in certain contexts.

Unless there are more comments I'll go with this.

Trevor

[Trevor Daniels, 2013-04-14 11:50:38]

Use a generic name

[janek, 2013-04-14 20:01:14]

LGTM

[Graham Percival, 2013-04-15 00:26:30]

On Fri, Apr 12, 2013 at 11:36:40AM +0000, janek.lilypond@gmail.com wrote:
> For me "adjustments" would be probably best.  Adjustments can be big or
> small, and - as far as i understand this word - can mean both adjusting
> something that's wrong so that it'll be correct, and changing something
> according to one's arbitrary tastes.

Yes.  I like "adjustments" for this purpose.

- Graham

[Trevor Daniels, 2013-04-24 07:37:47]

Pushed to staging as
528e1aac95928f3fbe017af0b3d7a0f0a0ccafbf
Closing ...