Re: Contemporary music documentation

[Carl Sorensen]

On 9/5/09 1:13 AM, "Trevor Daniels" <address@hidden> wrote:

> 
> 
> Carl Sorensen wrote Friday, September 04, 2009 11:57 PM
>> 
>> On 9/4/09 10:27 AM, "Trevor Daniels" <address@hidden>
>> wrote:
>>> 
>>> Carl Sorensen wrote" <address@hidden> 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