SuperCollider 4: First Thoughts

Very much agreed.

Regarding the help system, I’d personally love to be able to work in some variety of markdown, since I already use it for my internal project notes, but I haven’t really thought through the larger scale implications of that at this point.

What I actually wanted to add here is the idea that one of the simplest and highest-leverage changes that could be made to the help system would be adding full-text search. Right now we have options for “Title/Filename”, “Summary”, “Categories”, and “Methods”, and I’d imagine this just being another checkable item in that list.

I think this would lower the barrier to learners building their own mental maps of the documentation (which is complex and fragmented and realistically will probably always be at least a little complex and fragmented). Speaking personally, before I realized that I could just grep -ir foo /usr/share/SuperCollider/HelpSource, I’d regularly have the experience of stumbling across something interesting buried in some corner of the help system and then “losing” it for months before something else happened to lead me back to it.

Completely agree, IMO the old (SCApp) documentation system was a much better solution. Sure, there’s more consistency in the appearance of the documentation now, but it came at the price of flexibility and interactivity.

Unfortunately .rtf is a Microsoft proprietary format, and there doesn’t appear to be any libraries for handling that particular format cross platform.

It would be great to have an environment more in line with the old SCApp experience in general, which in itself was closer to the SmallTalk ethos.

NOTE: no disrespect to any authors who’ve graciously contributed to the development of SC :heart:

Its searchability was poor.

hjh

Indeed, I’m probably overlooking weak aspects of the old implementation, it’s been a while since I used it.

Unfortunately .rtf is a Microsoft proprietary format, and there doesn’t appear to be any libraries for handling that particular format cross platform.

Yes, .rtf wouldn’t work. It looks like the QT system would store documents either as HTML or “a custom XML format”.

https://doc.qt.io/qt-5/examples-richtext.html

But I’m not sure it matters what the storage format is?

Another complaint about .rtf was that diffs were hard to read. Maybe using auto-tidied HTML would help there too?

Its searchability was poor.

Also, it did all the kinds of documentation the same way too. ArrayedCollection.help.rtf was the same as COsc.rtf.

But perhaps all the method documentation in the former is more helpful if it’s written in the methods (as “Documentation”), and the latter (which only documents one method) is better as a “Help” file.

In case anyone is interested, you can grab an archive of the old .rtf files by typing the below, if you have a copy of the SC git archive:

$ git checkout 2495f4f61c0955001169d28142543aabbe1bedcb build/old_rtf_help.tar.gz

(I’m sure you can do it at github too, but I don’t know how.)

SCDoc has a lot of structure and a lot of tools for navigating and transforming it (that’s how it works!) so if people did decide to make any changes they could be done using the existing help codes.

One thing I don’t miss from SCApp: language crashes, you forgot to save, bang your code is lost forever. Or, you’re using the internal server for scoping (no shared memory interface at that time), and a UGen crashes, bang lost your code.

I’m curious what other features you liked about the old app. Rich text for code, unstructured editing of help files are two that you’ve mentioned… anything else?

hjh

Since I mostly use my own client, I have no strong opinion on the direction of the sclang help system, but I would recommend against going back to RTF. It’s also not true that markdown requires an “edit/compile/render/view cycle”. Don’t know which system you are referring to, but I can see many platforms that instantly render, and you can view “source” and rendered side by side. The RTF was a mess with people leaving their fonts and font sizes all across the place. A semantic doc structure is much better to maintain a consistent documentation. This doesn’t impede that you can format personally your documents like you wish.

I think the way to go for “literate programming” is a mixed markdown / code model like Jupyter notebooks.

BTW I agree that String and SinOsc should not use the same template for documentation and belong to entirely different perspectives.

1 Like

I guess a rich text editor could store to markdown, but I’m not sure the Qt one will do that.

Having edit and render windows side by side is still a kind of mode switch.

You wouldn’t have two views if you were just reading.

The idea of a rich text editor is that you edit inside the rendered view.

The rendered text around the edit cursor maintains it’s rendering as you type.

It’s true, I don’t know of a markdown editor that does this!

If SC decided it wanted a rich text editor but didn’t want to have different fonts, perhaps it could hide the font selector?

Since the Qt rich text editor is writing to Html I imagine it might allow structural editing, H1, H2, Em, Ul, Ol, Li &etc.

Why not have documentation written in markdown but parsed to HTML and rendered in the web view? That is, in my opinion, a trivial thing to solve technically.

Cue the old debate between WYSIWYG and WYSIWYM… (I’m firmly in the second camp tbh – Writing? org-mode + LaTeX > MS Word. Scoring? LilyPond > Sibelius… etc.).

hjh

Yes, and this is connected to a basic tension in SC, i.e. “who is SC directed at”?

The 1996 ICMC paper says SC began as “a Max object called Pyrite”.

https://quod.lib.umich.edu/i/icmc/bbp2372.1996.078/

So in a concrete sense SC was first directed at people who used Max.

That is, music and sound design (and perhaps signal processing) people.

Perhaps, over the years, SC has shifted focus a bit.

Perhaps the edit views of the old and new SinOsc help files reflect this.

Perhaps which you prefer depends on background and so on.

Still, if people are thinking of working on the help system again, then I think it’s worth thinking about these basic questions again as well.

Ps. In case anyone’s interested below is a picture of the “edit view” of the old SinOsc help file. (I don’t have an old SC so this is just the file opened in gmail, but you can get the idea.) For people who haven’t edited any of the new help files, you can get an “edit view” by following the link at the bottom of the SinOsc page in the scide help browser. Each has virtues, but they’re very different ones!

SinOsc.help.rtf|690x386

Pps. To be super clear, I’m not at all saying people should rewrite the Help system! Just that if people do, there may be some other ways of going about things now that Qt is a little more advanced and SC has very nice Qt support.

I think it may simply be that James McCartney was responsible for an awful lot and that attention to optimal usability of the help system may not have been high on the list. That is, having designed a language and a synth and an editor/GUI environment, then the choice would be between implementing structured documentation with indexing and search features, or “eh, I’ve done enough, rich text is OK for now”… we don’t know.

It’s kind of like the way that the Pure Data community almost fetishizes the minimal-core design of pd-vanilla, when the real reason for the minimal core is that Miller Puckette ran out of time before a concert and had to get something working quickly. There wasn’t, in fact, prescience in that decision but in hindsight it’s taken as such.

Unstructured text is easier to approach for editing but it’s much harder to build indices and search it. Searching is kinda important for documentation. It would be possible to use markdown and maintain some sense of structure but I think it would be bad to lose semantic structuring altogether.

hjh

1 Like

Hmmmm, I don’t know.

The old files did have category structure though, it was written in the directory tree, ie.

Help/UGens/Oscillators/SinOsc.help.rtf

And the Help files were indexed at the top level so everything linked, like a wiki, implicitly.

At least that’s how I remember.

I don’t have a working copy to check all the details.

But regardless of the Help files, rich text can make organising working files nicer too.

It’s unusual for section headings to be in the same size and weight font as the rest of a text?

Emacs, naturally, has something very close to a modeless markdown editor.

It let’s you edit in the render view, set fonts and sizes for elements, hide sections, &etc.

It’s very nice, but it’s Emacs…

I think it would be bad to lose semantic structuring altogether

Me too! Hence remarks above about distinction between “Documentation” and “Help”.

Where did you hear that? This doesn’t make much sense to me. Even if that was true, there is no reason why he couldn’t add more objects/features after that concert…

Miller explains in one of his older papers that he envisioned the original Max as a minimal runtime environment and expected users to write their own abstractions/externals. He carried this philosophy over to Pd, while Max/MSP went for the “batteries-included” road (Pd’s minimalism wouldn’t work very well as a commercial product).

I think the real reason why Pd is so minimal is that Miller is the sole maintainer (besides a handful of contributors) and he wants to make sure that he is able to understand and maintain all of it. (I don’t think there is a single person on this world who understands all of SuperCollider :slight_smile: )

BTW, Miller just recently managed to get Pd (without GUI) running on the ESP32 WiFi board with only 512 kB of RAM!

1 Like

He says in a podcast that he had been working on data structures, but with a deadline approaching, he ended up putting in Max style objects because he knew it would work. I guess I’m incorrectly extrapolating from this.

I wasn’t aware of the older paper and I appreciate the correction. (If I’m wrong and subsequently corrected, then my knowledge improves, which is a good thing.)

FWIW I suppose the ideal balance is somewhere in between Pd and SC. That Pd lacks a built-in bandlimited sawtooth generator strikes me as excessively dogmatic about minimal core. OTOH, when I find for instance that SC’s Integrator accepts only control rate for the coefficient (???) then I think SC might be better off by removing convenience UGens like this and using FOS (First Order Section) instead, reducing the surface area required to test (Integrator = FOS.ar(in, DC.ar(1), DC.ar(0), coefficient_ar)).

hjh

I guess a rich text editor could store to markdown, but I’m not sure the Qt one will do that.

It does!

I think QTextEdit is what QCollider and ScIde currently use for text editing, and:

QTextEdit is an advanced WYSIWYG viewer/editor supporting rich text formatting using HTML-style tags, or Markdown format.

I guess the interesting question would be delimiting the scope of the syntax highlighter.

Perhaps the outer parentheses did this in the old SC?

I opened the below as a placeholder in case anyone else is interested in this.

Also, if the editor has structural elements (ie. as in Html or Markdown) then syntax highlighting would be very easy! It’d just be applied in “code” blocks, however they’re delimited. Plus maybe a command for highlighting “in paragraph” codes.

https://github.com/supercollider/supercollider/issues/5556

Cleaning up the docs won’t require another major version, but we want to get it done before we get there.

The expansiveness of the core library is a great virtue… with the side effect of making itself a particular challenge to navigate, in certain cases.

Before stepping aside for a moment, a more in-depth report of SC’s user survey:


Greatest difficulties:

Top result: tutorials & documentation

Requested development efforts:

Top result: tutorials & documentation

The preceding question appears to be a summary of category groupings for responses to a free form version of the all the questions that comprised the greater majority of the entire survey… user interest regarding areas of potential future development.

The result ratings for these questions can be shown in their entirety by using only a single image or inforgraphic, serving as the grand takeaway concentrated gem of information, from over 11,000 questions & answers.

Here are the results for score ranked features answered by every user in the survey:

…while being dead last on the list, the support for Ableton Link (see LinkClock) is still a victory none the less.

While nearly all of the features could be reliably implemented without a major version update, the outstanding exceptions seems to be support for VST plugins as well as standalone applications.

If both of these implementations were included as cleanly polished & functional interfaces… this in itself would be mark a huge distinction from SC as it is at present.

Not to draw relevance from the evolution of how the community currently feels about this; I find these two features to be the highest demand overall, and while apart from being distinctive in nature, VST & Standalone have captivated my interest rather naturally, since I first began using SC.

Standalones were once possible on OS X, and as @jamshark70 mentioned, the critical issue with these involves licensing… and a similar issue exists for VST that also involves licensing related complications.

The necessity of popular demand may work as a catalyst for the next prefixed version release of SC… this in itself would require the licensing updates to reflect only the identifying and applicable versions of future releases.

1 Like