The Future of the Internals Reference

I hope you're prepared for another...ahem...*nerdy* post from me. As you have probably noticed, I care about LilyPond a lot. And guess what? The ``Internals Reference'' is a piece of the LilyPond documentation. So again, another post relating to LilyPond. Though LilyPond's Learning Manual and Notation Reference do a good job of explaining how to navigate the Internals Reference, this manual needs some major improvements. And since the Internals Reference is automatically generated from source code, these changes will likely be non-trivial to implement (except for the developers that are proficient in Scheme):

1. The ``Music expression'' pages should indicate which ``Music properties'' they support. Implementing a new collection of pages similar to the ``Grob interface'' pages would be nice.
2. What are ``Music classes''? I have a vague idea from browsing through the manual, but this concept should be cleared up.
3. The list of grob interfaces on the grob pages should be placed above the list of standard settings, i.e. near the top. The current structure is less efficient from a navigation point of view.
4. Every grob page should list *precisely* which grob properties the grob supports and *from which* grob interface each grob property belongs. If a grob *supports* an interface, this doesn't mean it supports *every* grob property in the interface; this is why documenting *only* the grob interfaces is less than ideal. However, implementing a system that improves the current setup might require more ``data dumping'' from the C++ side.
5. The following items should be differentiated from the source code itself and not hardcoded in Scheme code: (a) Tunable versus internal context properties, (b) Tunable versus internal grob properties, (c) Whether or not a grob support a particular grob interfaces, (d) Precisely which properties a grob supports.
6. Brand new sections need to be added to ``4. Scheme functions''. As I noted in an earlier post, there are *many* more Scheme functions available than the ones listed here. However, I admire this section in that it is *truly* auto-generated from source code. Every other section is too hard-coded to be completely useful.

As it stands, the Internals Reference is a wonderful resource, but it needs to be more of a "living" document than it is right now.