Re: Contemporary music documentation

[Trevor Daniels]

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.

Trevor