"Used by:" Macro References for routines and variables

[spontificae]

These are currently generated automatically for routines by the sna2skool.py script. There is some manual tracking of significant variables references in the control file currently, but it's incomplete and may require editing/removal in future if variable references are also auto-generated.

This is stemming from the following conversation involving using macros similar to the deprecated #REFS and $EREFS ones from earlier Skoolkit versions: https://spectrumcomputing.co.uk/forums/viewtopic.php?p=134218#p134218

Since Skoolkit does not reparse/modify existing "Used by:" strings when generating the skool file - If we create our own macros for routine+variable references, that would have the benefit that they could be found/fixed more easily if needed.

[ZXGuesser]

I'm not sure I understand the problem, you'll have to point to an example of what you mean.

I also don't understand what you mean by "reparse/modify" strings when generating the skool file. The variable references etc use #R (unless there's things that didn't get linked)

[spontificae]

Sure! An example would be this existing page for the "Cast Spell Flag" variable - it contains one reference to it being read within "select_spell" in the description and that context helps improve understand how it is used: https://zxnet.co.uk/spectrum/chaos/asm/9384.html

My takeaway from the Skoolkit thread was that any pre-existing "Used By:" strings in the control file will be left alone, but if a routine is missing a "Used By:" string then one will currently be generated by sna2skool for every routine where it is appropriate.

I'm not using "Used By:" strings anywhere, but I have been eyeball-tracking which routines modify which variables for about half a dozen routines so far - filling out the input/output parameters manually where it seems helpful to me. While it would be nice to find a reliable method to automatically generate this data, and cross-reference it within the individual pages for each variable - that level of granularity is helpful in places but not necessarily desirable or going to increase code readability/understanding everywhere it is implemented.

This issue is not blocking any current development, but i raised it because if we did use macros to keep the cross-references for variables up-to-date then it'll be handy for me and anyone else in the future who wants to fork this disassembly to create (and document) their own Chaos Mods.

[ZXGuesser]

Ah, I think I understand what you mean now. The "used by" description is inserted when a block has no Description in the control file but not added to the ones we've commented. I thought that was supposed to happen already by setting ListRefs=2 but perhaps I've misunderstood that 🤔

[spontificae]

Nah, you understand this far better than I do :) I need to assign myself a large block of time specifically to read the other 98% of the skoolkit documentation i yet haven't and experiment with settings and output before i'll feel confident doing advanced macro stuff to add more polish.

There are a couple other non-blocking issues like this in the back of my mind, and some raised within pull-requests, which future maintainers may wish to be mindful of - i haven't used github much in over 10 years - so there may be a better way to keep track of notes rather than use Issues as an interactive TODO file :)