documentation on emacs

[azimut]

I think it would be nice to have documentation of each ugen or method at the reach of (describe) or (documentation) of emacs/slime. What can be the preferred way to do this?

We can parse or put as is the .schelp files: https://github.com/supercollider/supercollider/blob/develop/HelpSource/Classes/GrainFM.schelp

[defaultxr]

I think automatically parsing help files would be nice. I'm not sure how much effort this would require. I wonder how much of the documentation sources are in .schelp format vs .rtf vs just HTML.

I'm also not sure what is technically the "preferred"/"recommended" format for writing SC help files currently. i.e. even if .schelp files are used more now, is there a possibility that another format would be used more in the future?

Actually, it looks like the SC team has already talked about changing the preferred help format to Markdown: supercollider/supercollider#2897 . Though SC development doesn't go that quickly and it doesn't sound like the change will happen too soon.

Obviously, automatically parsing the help would be much preferred to manually copying it over. Less error-prone, and could be re-run in the future to easily pick up any documentation changes.

Semi-related: I think it'd also be ideal to be able to automatically parse UGen information so they wouldn't have to be specified manually as they are currently. There will always be some UGens that would have to be specified manually (such as Klang or FM7, both of which use somewhat non-standard argument formats).

There is an issue about a possible UGen metadata system on SuperCollider's github here: supercollider/supercollider#2300 where they discuss something like this.

Anyway, back to the documentation issue: in the meantime, I wrote some Emacs code to make it easy to open the sccode.org page for any of the built-in classes in sclang. All you have to do is call slime-documentation-supercollider and it will open the relevant page for you.

It might be slow the first time you use it in your Emacs session since it has to open sclang to cache the class list, but after that it should be quick.

For consistency with the rest of Slime's documentation, I have slime-documentation-supercollider bound to C-c C-d s.

(defun slime-documentation-supercollider (ugen)
  (interactive (list
                (completing-read "Class: " (slime-supercollider-get-ugens-list) nil nil "^")))
  (browse-url (concat "http://doc.sccode.org/Classes/" ugen ".html")))

(defvar slime-supercollider-ugens-list nil)

(defun slime-supercollider-get-ugens-list ()
  (if (null slime-supercollider-ugens-list)
      (progn
        (with-temp-file "/tmp/supercollider-get-ugens-list.scd"
          (insert "\"-----\".postln;Object.allSubclasses.do(_.postcs);\"-----\".postln;0.exit;"))
        (with-temp-buffer
          (call-process-shell-command "sclang /tmp/supercollider-get-ugens-list.scd" nil t nil)
          (goto-char (point-min))
          (search-forward "\n-----\n")
          (setf slime-supercollider-ugens-list
                (sort (split-string (buffer-substring-no-properties (point) (- (save-excursion (search-forward "\n-----\n") (point)) 6)) "\n" t) #'string<))))
    slime-supercollider-ugens-list))

(define-key slime-mode-map (kbd "C-c C-d s") 'slime-documentation-supercollider)

[azimut]

Thanks for the quick and extensive response.

Looks like there is some parsing of local static files at https://github.com/supercollider/scel/ that and a some (slime-read-symbol-name) to get the current symbol help page is what I was thinking originally.

But your script seems to work better and with less dependencies, only thing I had to change was:

"echo | sclang /tmp/supercollider-get-ugens-list.scd"

To workaround this error supercollider/supercollider#2655

Even things on sc3-plugins are on sscode.org. For personal convenience, I am trying to use w3m-brose-url instead (looking how to open it on a splitted buffer)

And yes, autogeneration of ugens sounds cool, once they stabilize the format used I guess.

[azimut]

Alright, I settled for this one that uses w3m and opens a view only buffer within emacs.

(defun slime-documentation-supercollider (ugen)
  "Will open a w3m view buffer with just the ugen info"
  (interactive
   (list
    (completing-read "Class: "
                     (slime-supercollider-get-ugens-list))))
  (with-current-buffer (get-buffer-create "*schelp*")
    ;; clear previous buff
    (erase-buffer)
    ;; needed to make further operations like (search-forward) work
    (w3m-process-with-wait-handler
      (w3m-retrieve-and-render
       (concat "http://doc.sccode.org/Classes/" ugen ".html")
       nil nil nil nil handler))
    ;; remove headers
    (goto-char (point-min))
    (search-forward "\n\n" nil nil 2)
    (delete-region (point-min) (point))
    ;; show
    (view-buffer-other-window "*schelp*")))

As a side note, I see the default path where cl-collider searches for SC (on linux) changed from /usr/bin/scsynth to /usr/local/bin/scsynth that is normal for manually compiled installations but not for Gentoo or Arch (https://www.archlinux.org/packages/community/x86_64/supercollider/files/) I think it would be friendlier to default to /usr/bin/scsynth or have the other as a fallback, same for plugins path.