internals reference (was: tablature tie/slur)

[Graham Percival]

On Thu, Oct 28, 2010 at 04:55:12PM -0600, Carl Sorensen wrote:
> 
> On 10/28/10 4:50 PM, "Valentin Villenave" <address@hidden> wrote:
> 
> > How about basic regrouping all engravers-related Scheme definitions in
> > a `define-scheme-engravers.scm' file, and then document it just like
> > music-functions.scm and define-markup-commands.scm, using (_
> > "localized doc strings"). Or is that too pedestrian?
> 
> Well, as far as I can see, Scheme engravers are really engravers, so they
> ought to be documented in the IR along with the C++ engravers, not in an
> appendix of the NR along with Scheme functions.

Aye, but that's just a question of changing the IR-generating
scripts to look at .scm files in addition to .cpp files.  Looks
like the entry point is
  scm/documentation-generate.scm

AFAIK, right now we have absolutely zero knowledge of how the
Internals Reference is generated.  That's not ideal, of course,
but it's a non-trivial task.  I personally would budget 10 hours
of reading that scheme file, files included by that scheme file,
making small changes and rebuilding lilypond to see what happens,
etc, before claiming that I "understood" it.

OTOH, you might look at that and think "10 hours?  that's
nothing"... or even "10 hours?! it's a 179-line scheme file, of
which 33 lines are comments.  Understanding that is a 10-minute
task, not 10 hours!".

:)

In any case, I propose that we shelve this until 2.14 (maybe after
adding an Issue).  The main candidates that I had in mind for this
kind of task are currently working on release-critical stuff.
That said, if somebody is particuarly interested in this idea...
especially since I suspect that it's actually a 1-hour task rather
than 10 hours... then by all means jump in.  :)

Cheers,
- Graham