SuperCollider `action` Description not rendering properly

[tedmoore]

I noticed in BufStats.rst that this is written:

Yet, what appears in the rendered SC help file inside of SuperCollider is:

This language for the action function is getting pulled from the template. It would be preferable to be able to specify different action functions for each object.

[jamesb93]

I'm not sure I get it. Can you explain the problem to me in another way?

[tedmoore]

There is text in the RST that is not ending up in the .schelp file. This is because the text for the action function seems to not be pulled from the RST but is instead hard-coded into the template file. Rather than hard-coding in the description for this action function it would be good to have the template get the text from the RST.

[jamesb93]

Oh yeah, sorry the difference is subtle when you are not a careful reader like me 🤦. Thanks for spelling it out :)

[weefuzzy]

• The text for action is currently rendered unconditionally in flucoma/doc/templates/schelp_buffer-proc.schelp for buffer processors' process[Blocking]
• OTOH, it is specified separately in the reStructured for each message of the data objects

IMO, neither of these is very good. We'd evidently like to be able to override the default text for the buffer processors (as here). Meanwhile, I'm not wild about having the actions for messages appear just like any other argument in the reStructuredText because that means every other host presumably has to make a special-case for them and ignore. What would be preferable would be for both cases to have a default that gets rendered but can be overridden, but also that doesn't pollute the general documentation with a host-specific implementation detail. I don't know what that mechanism is yet, but will think on it.

[tedmoore]

can be overridden

Yes. This would be wonderful.

The .. only_in:: sc seems to work quite well. Is this useful?

[weefuzzy]

Not sure that it would do the job here, as we're needing to make individual fields in a field_list conditional rather than normal body elements: what would show up in ..only would be its own field_list tree that would have, somehow, to be merged with one above, if present.