Thomas Morley <thomasmorle...@gmail.com> writes: > Am Di., 21. Jan. 2020 um 23:13 Uhr schrieb David Kastrup <d...@gnu.org>: >> >> Thomas Morley <thomasmorle...@gmail.com> writes: > >> > David, you remember my suggestion to generate that "General Code >> > Reference" with an Index ... ? >> >> Yes, that may have helped. But it may also have delivered a haystack. >> >> I think we probably need a "good programming" corpus, but the snippets >> are supposed to be that. Navigating them still is too hard. > > If you think of the "Snippets Manual" or the LSR, then I doubt they > are best suited to what I think we need. > Their snippets are too much targeted at delivering ready to use tools > for actual typesetting work. > > As an example: > music-map has the problem that you can't really stop it recursing > deeper. One reason why you wrote map-some-music and for-some-music. > Alas, I always need to get to their doc-strings again, to understand > the differences and which one to use for which case. > And ofcourse their docstrings are not in any manual, afaict. > > Sometimes I look in our regression-tests, which contains nice coding > examples, but you can't expect average user to look there. > And sometimes even the regression-test don't say anything, as an > example for no info at all: > $ git grep "ly:broadcast" > lily/dispatcher-scheme.cc:LY_DEFINE (ly_broadcast, "ly:broadcast", > scm/define-music-callbacks.scm: (ly:broadcast > (ly:context-event-source context) > > Leading to IR entry: > > Function: ly:broadcast disp ev > Send the stream event ev to the dispatcher disp. > > Which is ununderstandable without any context.
Yes. The CG might have a bit of info there, but if it is there, it is likely very sketchy and does not really help a lot. > Cheers, > Harm Well, to some degree my "why don't you use $x" kind of advice results from having had to fight through the code base in order to be able to refactor parts I had to fix into something I could understand. So I have bit of a semantic network in my head that may give me a hunch what to grep for in order to tackle some class of problem. That's pretty lousy as a way of getting information suited to the task. I don't like the bus factor impact that makes me have. Gives me a bad conscience. -- David Kastrup
