Folks,
please calm down. Nobody here is insinuating anything! As far as I can see, we have a clash of concepts that is probably not resolvable in *any* satisfying way. Consequently, the only way forward is to minimize the fallout, namely by providing explanations what a musical term 'foo' means in LilyPond, and why there are differences to its standard, colloquial usage. > Most helpful of all was the suggestion that the grob descriptions > given as IR 3.1 ... > > https://lilypond.org/doc/v2.24/Documentation/internals/all-layout-objects > > ... be expanded to list *all* properties for a given grob, rather > than only the properties that a grob *changes* from interface > defaults. Jean has shown a possible solution to that, at least for the HTML page; I'm attaching his image here (taken from https://gitlab.com/lilypond/lilypond/-/issues/6210). We now have to find a way to implement that in Texinfo while still getting decent results in the other output formats. Now answering to other comments. Matthew wrote: > The point isn't to list properties with no effect, but to list *all* > of the properties that *do* have an effect As demonstrated by Harm, this is not possible, for various, mostly technical, reasons. In addition to that, the IR is a static document that *cannot* reflect the state of LilyPond at an arbitrary point of time while processing an input document. Instead, it presents LilyPond in a pristine state, before any `*.ly` files has been loaded, more or less (including LilyPond's own startup files). > But one might well also ask, if there are useless properties with no > effect, then why are there useless properties with no effect, Again, Harm demonstrated that this can be dynamically changed in many cases, suddenly 'activating' properties and vice versa. If there are grobs that LilyPond really ignores by using hard-coded values instead, it should be documented, and it is a bug if there is no documentation for that. > and isn't the fact that such properties exist a much bigger problem > than whether they should be listed in the document? This question is far too general. Please give an example. Trevor wrote: > The naming problems would go away if this three-part way of modeling > duration were qualified in its name: dottedDuration, > dottedIntegerDuration, probably something like that since the > augmentation dots appear to be the most distinctive feature of this > particular model for duration. Though anything could work. No, please. That way madness lies. We have to live with the fact that the musical term 'duration' is not concise enough (in a computational sense) to describe all facets needed for LilyPond, and that sometimes a more fine-grained distinction is necessary, introducing 'strange' terms not used in standard musical context. I invite you to improve the documentation by submitting a section for the Learning Manual (and/or for the Notation Reference) that clarifies potential misunderstandings. Providing an update to the Glossary might also be helpful. > I ask again: has anyone on this list usability-tested LilyPond's > documentation? No. > I'm preparing to do the work of usability-testing the docs myself. Great! Werner
