A whitespace after `tag::` or not?

Agreeing on any single rule, like whitespace after tag::, will be less likely to take root outside of a more comprehensive set of guidelines for SC docs.

An official style guideline is totally reasonable, and has been beneficial for the SuperCollider and C++ codebase IMO. They would provide a foundation for large-scale cleanup of the docs. They may even motivate someone to make a formatting/linting pipeline for it, and introduce syntax highlighting into the IDE for .schelp files.

A bulk of the effort for making guidelines is in drafting proposed rules and patiently shepherding the contributors over the finish line.

As an aside, I was able to sneak in a fairly wide cleanup of code formatting in help (Class) files, only because we have official guidelines on code. I didn’t touch other parts of the docs files because we don’t have agreed-upon guidelines and so would have derailed that effort.

EDIT: I see there’s a proposal to work on guidelines in another thread.

1 Like