On 9/5/09 1:13 AM, "Trevor Daniels" <t.dani...@treda.co.uk> wrote:
>
>
> Carl Sorensen wrote Friday, September 04, 2009 11:57 PM
>>
>> On 9/4/09 10:27 AM, "Trevor Daniels" <t.dani...@treda.co.uk>
>> wrote:
>>>
>>> Carl Sorensen wrote" <c_soren...@byu.edu> Friday, September 04,
>>> 2009
>>> 3:06 PM
>>>>
>>>> Also, as you plan sections, remember that anything using \set or
>>>> \override
>>>> belongs in a snippet, not in the main text body.
>>>
>>> This certainly is a rule for NR 1, but is not
>>> absolutely essential for NR 2. But in general
>>> you're right - self-contained snippets are usually
>>> the best way of demonstrating \set and \override
>>> commands. When appropriately tagged and referenced
>>> they appear in the manual exactly as they would if
>>> placed there, and can be easily modified by anyone.
>>
>> CG 3.1 says "A few other policies (such as not permitting the use
>> of tweaks
>> in the main portion of NR 1 + 2) may also seem
>> counterintuitive...". Later
>> on, in CG 3.5 (under Tips, not 3.4 Policy, which is potentially
>> confusing;
>> perhaps the Tweaks subsubsection should be moved to Documentation
>> policy),
>> it says "In general, any \set or \override commands should go in
>> the
>> 'selected snippets' section."
>
> "In general", yes. "Without exception", no.
>
>> If tweaks are
>> necessary to produce the base functionality of any LilyPond
>> feature (e.g.
>> Turkish music), we should add appropriate commands to do the
>> tweaks. Then
>> tweaks are reserved for a method of modifying the base
>> functionality, and
>> can be appropriately placed in Selected Snippets.
>
> No. It's much easier to write documentation
> than it is to add commands. I would not want to
> delay useful additions to the documentation or to
> put off a keen documentation writer simply because
> new commands have to be written first. Especially
> for something like Turkish, which is particularly
> tricky and totally undocumented. Documenting it
> carefully will almost certainly throw up bugs and
> inconsistencies. These will need developer effort
> to fix before we can think of adding extensions and
> new commands.
>
> That said, anything that can be done with a simple
> encapsulation of overrides in a variable, much like
> the changes introduced during GDP, should be done,
> of course.
That's all I meant.
And it's not *too* hard convert the new documentation from
main body to selected snippets. It would even suffice (IMO) to have
documentation that uses tweaks be prefaced with a comment
@c TODO -- make command or move to Selected Snippets
to make it easy to update in the future.
Thanks,
Carl
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
