Schelp Style Guidelines discussion coordination thread

Development
1

Hi all,

The purpose of this thread

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.
  • Confirm old style guide:

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.

c. misc formatting

  • 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.

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, …)?
3 Likes
2

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.

1 Like
3

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, phase amp, 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.

2 Likes
4

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>.

5
(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:

  1. Things that concern arguments specifically;
  2. My nitpicky humanities prose hangups such as punctuation and citation (which we can really just discard if it’s not worth people’s time);
  3. 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.)

1 Like
6

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.

1 Like