Re: GDP predefined commands

[Mats Bengtsson]

Isn't the main points of this discussion that:
- Predefined commands like \fatText should be described in the NR.
 Even if the implementation of it might change over the years, the 
semantics
 will remain the same.
- Somewhere in the NR, it should be described how an advanced user
 can find the exact implementation of these predefined commands, in case
 he/she wants to do something similar but on another object, for example.
- On the other hand, the exact definition should not be copied verbatim into
 the NR (perhaps with the exception of one single example in the 
description
 mentioned in the previous item), since as Graham points out, the 
information
 may easily get outdated.

  /Mats

Graham Percival wrote:
> Trevor Daniels wrote:
> > > Actually, \fatText _is_ simply an arcane override > -- but one which 
> > > the > developers thought was so common that they > included a 
> > > predefined > variable.  
> >
> > The difference exactly.  That's why I think this
> > predefined variable should be in the main text.
>
> No, absolutely not.  That would be the *worst* possible thing to do.
> (below)
>
> > > Look in ly/propert-init.ly :
> > >
> > > fatText = { \override TextScript  #'extra-spacing-width = #'(0 . 0)
> > >              \override TextScript  #'infinite-spacing-height = ##t }
> > >
> > > There was a proposal to explain this in every single @commonprop 
> > > section, but I think it's better to include one GOOD explanation of 
> > > this kind of thing in the LM.
> >
> > I agree entirely. A ref to the explanation is all that is required.
>
> Summary: "documentation is a process" and "we don't have the resources".
>
> The exact definition of commands like \fatText changes.  I would be 
> willing to bet money that \fatText will change at least once over the 
> next five years.
>
> If we discuss \fatText in the main docs (or in the @commonprop), then 
> what happens when the definition changes?  either
> 1) the docs don't match the program.  (very bad!)  or
> 2) the docs need to be updated.
>
> We don't have the resources to update the .tely files every time 
> something changes.  We don't have the programmer resources to get them 
> to do it, we don't have the documenter resources to find all these 
> changes and update the appropriate places.  Would it be nice if we 
> were overflowing with offers of help and could do this stuff?  Yes, 
> totally.  But the lilypond community -- with a few notable exceptions, 
> yourself included -- has not been willing to get involved in the 
> development.
>
> (I _will_ say that it's been getting better in the past year or so... 
> but still nowhere enough help to make this feasible)
>
>
> So how should users figure out what \fatText does exactly?  They read 
> LM 4.2.1 and find ly/property-init.ly  on their own computer.  This 
> file is *guaranteed* to be correct for their exact version of lilypond.
>
> Documentation is a process, not a product.
>
> > > (let's put this specific question to rest for a few days; I promise 
> > > we will return to it)If you want to continue talking about this 
> > > without any examplesN
> >
> > Sorry, couldn't resist replying :)
>
> At this point I'd like to state that LSR tags have been implemented 
> and that we're 2 or 3 days away from having some useful examples to 
> discuss, and it will be much easier to understand once you see an 
> example.
>
> Cheers,
> - Graham
>
>
> _______________________________________________
> lilypond-user mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-user

--
=============================================
        Mats Bengtsson
        Signal Processing
        Signals, Sensors and Systems
        Royal Institute of Technology
        SE-100 44  STOCKHOLM
        Sweden
        Phone: (+46) 8 790 8463                         
       Fax:   (+46) 8 790 7260
        Email: address@hidden
        WWW: http://www.s3.kth.se/~mabe
=============================================