is to coordinate discussions on schelp style guide decisions (this does not pertain to the code examples). The idea is to group the large number of questions and decisions this involves into a slightly more manageable number of issues, for which I will then open issues on the github project page. Each issue will comprise multiple questions/decisions. The present thread isn’t about making those decisions, but rather about agreeing which decision goes into which issue. Maybe we can tentatively aim to settle this first part of the process by the End of March? (Even better if we’re done before then, but people have lives.)
I will be proposing an outline below to get us started, and will try to keep it updated as people make suggestions, additions, or ask me to remove things (I erred toward the overly explicit for now).
Blah blah blah
At the moment, I’m formulating all of this as questions, and including answers in round brackets where I think there may already be consensus, or if the old style guidelines provide an answer. If you think I am misrepresenting that consensus, let me know and I will remove that answer; no need to provide reasons (the fact that you disagree is reason enough). At any rate, the focus is on the questions for now.
[Square brackets around questions are things that occurred to me as I was writing this, but that I didn’t see mentioned anywhere. If two more people confirm that they these square-bracketed questions should be explicitly addressed in the style guide, I’ll remove the brackets; if two people think they’re irrelevant, I’ll remove the question. Things that are still in brackets at the end of this discussion won’t make it into the issues.]
Maybe this is organizational overkill at this point, but to make my life easier, you could begin your posts with a short heading describing what you suggest I change, and then the reasoning behind it. E.g., “Remove capitalization question”, “Move method description formatting question to general formatting issue”, etc.; also helpful: If you agree with someone else, post a quick +1 of their heading, e.g. “+1 Remove capitalization question”, or “+1 add commitment to luxury space communism to schelp style guidelines formatting issue”.
Issue 1: Formulate role of style guide for contributors and reviewers.
Should style guide compliance ever be a criterion for PR rejection? (No.)
Should regular help contributors be expected to adhere to style guide? (Yes.)
Should first-time help contributors be expected to adhere to style guide? (They should be nudged toward it but this should not discourage contribution.)
To what extent should occasional help contributors be expected to adhere to style guide?
[Should we qualify style guide rules by importance? E.g., unified spelling may be more important than unified punctuation because of search, but in case someone asks, it would be nice to have a quick answer to the somewhat unimportant punctuation question of whether the comma comes before or after the quote sign.]
[Should the style guide rules reflect the current state of the help files or some neater, ideal version?]
Issue 2: Text formatting, spelling. (The things user sees in the help browser)
NOTE: This issue should probably be split up into multiple smaller ones; current organization into a,b,c is a suggestion.
a) prose things:
Which spelling do we expect? (American: synthesize, color, center, etc.)
[Which punctuation rules do we expect? See above, not sure if this is worth discussing]
What capitalization rules apply? (Usual English, maybe link to CMOS or some such; but capitalize classes such as AbstractFunction)
[What citation style do we encourage? Again, low importance, but good to state somewhere so those who care can look it up.]
Should we specify the implicit grammatical context of method descriptions?
are paragraph breaks ok after just one line (or sentence) of text?
b. argument related:
[Should argument names mentioned in the text be highlighted? Some files do this, some don’t.]
boiler plate phrases for common args (freq, phase, amp, …)
guidance on how to document arguments accept multiple values. E.g. GrainBuf’s interp argument accepts 1,2,4 — Inline description? bullet list? table?
guidance on how to format wording for default argument values and valid ranges, if provided.
Either all of the parameters and/or return value should be documented, or none should be.
When documenting a parameter or return value, make sure to include the expected type.
guidance on when to use code:: (inline and block styles) vs. teletype:: (monospace, non-colorized)
formatting when referring to file names of file paths (e.g. italic, emphasis::)
Should all mentions of classes be tagged with links, e.g. link::Classes/AbstractFunction.schelp::? If not all, what are the conditions under which they should?
[Should math:: typesetting be explicitly encouraged? Can’t expect everyone to know how to do that, but otoh whoever designs/documents a filter probably does know basic tex; I may be wrong.]
Issue 3: Text structure.
EDIT: Turns out almost all of what I had here is already addressed in the Writing Help guide and SCDoc Syntax document. (That’s the magic of schelp: The info is already there, except not where you happened to look.)
Maybe this means that the style guide should least link to those two docs … the old one doesn’t, maybe because it’s too obvious.
Issue 4: Text format (as seen by contributors, not HelpBrowser users).
REMINDER: This has (almost) no effect on the result in the HelpBrowser, which ignores single newlines (wrapping the text instead) turns double newlines into paragraph breaks, and ignores case in tags.
mention footnote:: tag issue (which actually is a parser problem, but in the meantime…): Unless the tag is placed right after the word it precedes, without a space or newline (as in blah blah blah.footnote::More blah::), the parser will print a space between the word and the footnote marker, which is bad typography.
use tabs for indentation in schelp-formatted text and code
private methods should be hidden using private::
prefer using the lowercase forms of tags (code:: ::, method::), unless this would break with convention in the context being edited
prefer using argument:: and returns:: instead of the method description body to document parameters
In this category, there are already the items in @prko’s PR (to be discussed there, pasting here for completeness):
should line length be limited to a certain number of characters, words, sentences?
Reordering the header: changing class:: to title::, reordering the tags in the header.
Arranging (adding or removing) whitespace after ::.
Blank line alignment: only one blank line between line codes.
Capitalisation of the first word after description::, sections::, subsection::, method::methodName\n and argument::argumentName\n.
Change 3rd singular present form without grammatical subject after section tags like description::, sections::, subsection::, method::methodName\n and argument::argumentName\n to instructive (declarative) tone.
Issue 5: Things that concern the entirety of the help:
What different kinds of help files should there be, and how do we specify expectations for each? E.g., Class docs, reference, guides, tutorials, overviews…? Writing Help broaches this under “Directory Layout” but this could use some fleshing out.
Should categories:: be treated as non-hierarchical? (Yes I think: they are a comma-separated list, more like tags than folders, although many files have just one assigned category.)
Should we strive to eventually standardize the terminological inconsistencies that @prko brought up: (answer vs. return, item vs. element, …)?
Thank you for your opinion and for creating this thread!
I believe that many users are currently dedicating their time to preparing presentations and working on the SC Symposium, which may delay responses and opinions.
I’d like to share my thoughts on the use of single-sentence paragraphs and standalone paragraphs. In some cases, it is unclear whether the author’s intent is fully reflected, and the paragraph structure can appear a bit odd. You can see an example of those paragraph here: Add margin-top to "li:first-child" in scdoc.css by prko · Pull Request #6643 · supercollider/supercollider · GitHub. Although readability doesn’t seem to be an issue in this particular example, it provides insight into how changes in scdoc renderer settings might affect formatting.
Thanks for putting together these Issues, I think it’s a good approach to make separate issues both for easier organization and so people can gravitate toward Issues they care more about.
Here are a few suggestions to add to Issue 2 (Text formatting, spelling.)
Suggest boiler plate phrases for common arguments, like freq, phaseamp, etc…
e.g. in Input signal. freq Frequency of the oscillator (Hz). mul The output is multiplied by this value.
guidance on when to use code:: (inline and block styles) vs. teletype:: (monospace, non-colorized)
formatting when referring to file names of file paths (e.g. itallic, emphasis::)
guidance on how to document arguments accept multiple values. E.g. GrainBuf’s interp argument accepts 1,2,4 — Inline description? bullet list? table?
guidance on how to format wording for default argument values and valid ranges, if provided.
There are likely more… I suppose once Issues are created more suggestions could be gathered there. I can see how some Issues like #2 could balloon and may need to be slightly more granular.
That’s a good point. I’ll just edit to change the deadline. That deadline is fictitious/aspirational anyway; we can take however long we’d like with this really (but things are more likely to happen if we pretend otherwise…).
Yes, renderer settings are definitely relevant. I will add the single-sentence-paragraph to issue 2 for now. Right now I’m not sure I know what you mean by “standalone paragraphs,” is that the same thing? I looked at the link but what I see there all seems to correspond to single-sentence-paragraphs, unless you mean the <p><\p>.
(Thoughts for discussion which should really not go here ;) )
Yes. This seems to be the de-facto practice already for parts of the doc, good to make it explicit.
I was wondering about mul and add args, though: There is an older discussion about their utility and potential outdatedness, and while that discussion didn’t end in any way conclusively, keeping mul and add in the boilerplate seems like it would endorse the conservative option (i.e., mul add “good” because people use it), as opposed to the reformist one (mul add “bad” because inconsistent). If the boilerplate is meant primarily for new doc files (rather than revision of old ones), then I would argue not including those args in it is the more neutral decision.
Agreed, I can see at least three strands in there:
Things that concern arguments specifically;
My nitpicky humanities prose hangups such as punctuation and citation (which we can really just discard if it’s not worth people’s time);
Other things that concern formatting irrespective of where in the structure the text is (i.e., irrespective of whether it’s an arg description or an intro paragraph, …).
There may be other possible ways to carve it up, feel free to suggest things.
(I’ll edit the list later today to reflect your and @prko’s suggestions.)
Yes, indeed, we do not know how the work will actually be done.
I originally wrote ‘one-line paragraph,’ and this was converted while checking my writing using software (I do not remember which one I used for this; it should be DeepL or Microsoft Copilot). I thought ‘standalone paragraph’ was a better term for ‘one-line paragraph’ without checking its meaning. Sorry for that. Next time, I will carefully review my sentences myself after checking them with software.
Sure! When I posted this originally I didn’t know that such a thing would be happening. In general, there’s no real hurry with any of this but it would also be nice to get it done.
Maybe this is more of a content and less of a style issue, so feel free to ignore, but, particularly in the class documentation, being brief is really important as it is very easy to get overwhelmed with information. There is also an issue where if you mention class X’s behaviour in the help file for class Y, a future contributor altering X’s behaviour will have to search all help files to update it. It might be good to limit the scope of examples to as few classes as possible for this reason. Obviously it’s a balance between providing good musical examples and limiting the connectedness of the help files, but maybe something to consider.
This is a good point, and I agree; I’m also starting to think that the info in the docs is a generally too distributed in the sense that you often need to know what class X does in order to understand the doc for class Y.
However I don’t think this needs to be part of the style guidelines discussion, but belongs with the many “actually interesting things” that are much trickier to find solutions for. Probably best treated under the umbrella of “text structure” (i.e., aim for concision etc.), which I’ve mainly left out of this thing after all… or the present issue 5, as this would also amount to a clearer specification of what, e.g., a class documentation should do as opposed to a guide, tutorial, overview, …
I think of the style guidelines stuff as mostly low-hanging fruit, and this is I think slightly less low-hanging.
more musings re content
I’ve been entertaining the idea of (for explanatory/pedagogical purposes) sort of “pruning” sc down to a more rigid, ockhamized version (where there is exactly one class for exactly one job, and not fifteen different ways of writing the same thing, either in syntax or simply in alternative names for the same method (e.g. next, value, resume; …). I guess it would be nice for the docs to have a “standard” specificaton of the language with a limited selection of objects and syntax shortcuts that can show up in the class documentation etc., so that for instance I don’t have to first figure out a fancy synthdef when I’m really just hoping to understand some pattern class.
But actually making that happen is a whole other issue and I doubt there’s a consensus on it.
Doesn’t concern Class Helpfiles. Typically, the Glossary or Introduction to GUI, which I think might be difficult to reach.
Maybe I’m wrong about this, and this is due to the way I’m browsing help. I realized I was using it like a wiki, only navigating through the searchbar, or via links, but never using the arborescence to navigate back-and-forth through topics.
If you don’t know the Glossary page exists, the only way you reach it is using Browse > Help > Glossary. I find the Document Browser quite unfriendly.
But I think the response to the problem (if it is a common problem, not only mine) isn’t a specific guideline about multiplying references to a file, but a better arborescence representation within SCDoc UI.
First, it would help navigate. Second, it would give a direct representation of what topics should be (ideally) covered within a ‘standard’ helpfile. Contributors to the SCDoc will likely have navigated the documentation for hours before contributing. They would have seen this summary dozens of times. They would know what’s expected.
Collapsable blocs of text
Maybe off-topic, but...
…there’s this issue between being brief and concise, and overexplaining things. I’ve spent a lot of times debugging special cases that weren’t documented. Showing equations on the helpfile is a must, but might scare newcomers. I’d like to provide copy-paste templates, but I don’t want them to pollute the helpfile by default.
So I don’t know if we have this collapsable bloc of text functionality available in the SCDoc renderer, but I think this is a good answer to the problems mentionned above.
These pages will be accessible from the help home, if the following PR is approved and merged (Please refer to the screenshots of the help home for details.):
You can navigate the documentation using the Table of Contents. At present, the Table of Contents appears a bit narrow and could be widened for improved clarity:
This is exactly the point I have been making. The SC help documentation, although valuable, isn’t very user-friendly for newcomers—especially those who are just beginning their journey in computer music with SuperCollider. Enhancing its accessibility and clarity would greatly benefit new users.
As a quick note, when using ScIDE to edit help files, class names are colored ‘correctly’ when not linked (e.g. typing only Font), but not when typing link::Classes/Font::. This could be a good improvement.
Yes, the GH issue description will be updated. We decided that if we’d make a wiki page it might cause confusion as to which of the style guidelines is the active one.
You’re right about the links, will include that too. (I guess I didn’t put them in there right away because you gotta first make the issue before you can link to it, and the forgot.)
