Re: Directed \tweak commands in 2.15.39

[David Kastrup]

Thomas Morley <address@hidden> writes:

> 2012/5/23 Janek Warchoł <address@hidden>:
>> On Wed, May 23, 2012 at 1:49 PM, David Kastrup <address@hidden> wrote:
>>> Werner LEMBERG <address@hidden> writes:
>>>> Very nice!  Great work, David.  A minor thing: In the given link I can
>>>> see
>>>>
>>>>   \tweak layout-object #'grob-property value
>>>>
>>>> as the syntax line, mentioning that `layout-object' is optional.
>>>> Wouldn't it be betterto write this as
>>>>
>>>>   \tweak [layout-object] #'grob-property value
>>>
>>> I am not sure this syntax is familiar to non-programmers: it might make
>>> people try using actual brackets.  This is, after all, not the Extending
>>> LilyPond reference.
>>
>> +1
>
> \tweak layout-object #'grob-property value
> is similar to NR 5.3.3 `The \override command':
> \override context.GrobName #'property = #value
>
> So I*d vote for no brackets.
> But is there any reason not to change #'grob-property to #'property?

Not really: I think I was just extending an existing example.

> (Or to change #'property in \override to be more consistent)

Honestly?  Our documentation was created in lots of little bits from
different contributors at different times.  If we hope to bring it into
a reasonably more consistent state, discussing single lines and examples
is going to be ridiculously inefficient.

Instead, it would make more sense if people opted to take care of
something like a chapter at a time, or the relation between two
chapters, and brought them into line.  We can then tack
@c last full revision by xxx for version xx.xx.xx
into that chapter, to make it easier for finding non-revised chapters.
Or keep score elsewhere.

The state of our documentation build system is currently in quite better
shape than the quality of our documentation itself.

-- 
David Kastrup