Moldable Emacs: moldable tutorials
Too long; didn't read
Tutorials are great to start with a new tool. In this post I describe a new mold I crafted to make tutorials available from moldable-emacs.
I got a few issues opened last couple of weeks that made pretty excited! One that bit at me was about the absence of introductory material for moldable-emacs. Just in my last post I wrote how great are tools that are self explanatory. I strive to make my little mode like that too. I know that it is a struggle to start with a tool without a guide. We know how beginning with Emacs can test your patience and skills. I remember clearly how frustrating was to learn to copy paste again. My productivity plummeted for a while. It still does now: I have started using the amazing Lispy recently for (structurally) coding Clojure and I need to undo things a lot!
So the question: how to make the first steps with moldable-emacs easier?
It is a problem indeed
Well, I thought to write a tutorial. And I did! But it felt wrong.
Just the other day I was writing how adding a
doctor function to
code-compass felt an extra effort. How cool would it be to make the
tutorials interactive? Tutorials that you can run with moldable-emacs
itself, I mean.
Emacs does already an amazing job at that: for instance, have you ever
tried the calc tutorial
This idea is also definitely inspired by GlamorousToolkit again. When you run it, you can find a bunch of guides in the main window. You can interact with these by using the tool itself. A fascinating approach.
(As an aside: if you are on Linux or Mac, running GT from Emacs is easy. The following Elisp function is what I use for running the latest build.
(defun fun/make-latest-version-of-GT () "Make latest version of GT." (interactive) (let* ((mac-p (eq 'darwin system-type)) (just-run (if mac-p "cd /tmp/; open myGT/GlamorousToolkit.app" "cd /tmp/myGT/bin; ./GlamorousToolkit")) (download-and-run (if mac-p "mkdir /tmp/myGT; cd /tmp/myGT; wget https://dl.feenk.com/gt/GlamorousToolkitOSX64-release.zip; unzip GlamorousToolkitOSX64-release.zip; cd ../ open myGT/GlamorousToolkit.app" "mkdir /tmp/myGT; cd /tmp/myGT; wget https://dl.feenk.com/gt/GlamorousToolkitLinux64-release.zip; unzip GlamorousToolkitLinux64-release.zip; cd bin; ./GlamorousToolkit"))) (async-shell-command (if (file-exists-p "/tmp/myGT") just-run download-and-run))))
So I was wondering: can I at least open tutorials from moldable-emacs itself?
And there is a solution
That was easier than I expected! The idea is to have a mold that collects tutorials and makes them accessible to the user. If you want to use moldable-emacs then you need the repository. So I added a folder with tutorials in there. Then we know where the tutorials are. We just have to pull them and display them nicely to the user! Org Mode has some nice presentation/interactive features. So I wrote the tutorials in Org.
This is how the new mold looks like at the moment.
(me-register-mold :key "Show Tutorials" :given (:fn (not me-i-know-what-i-am-doing)) :then (:fn (let ((tutorials (--> (symbol-file 'me-mold) (file-name-directory it) (concat it "/tutorials") (directory-files it t) (--filter (equal (file-name-extension it) "org") it)))) (with-current-buffer buffername (org-mode) (erase-buffer) (insert "#+TITLE: Moldable Emacs Tutorials\n\n") (--each tutorials (insert-file-contents-literally it)) (goto-char (point-min)) (call-interactively #'outline-hide-sublevels) (setq-local self tutorials)))) :docs "You can consult `moldable-emacs' tutorials." :examples nil)
A bit of commentary:
me-i-know-what-i-am-doingis a variable you can set to
tin order to hide this mold
(symbol-file 'me-mold)tells us where you stored moldable-emacs repository
then we can gather the file names starting from that
(insert-file-contents-literally it)is really the trick: we just insert the files verbatim in an Org Mode based mold!
- this buffer sets
selfto be the list of tutorials filenames.
The exciting thing is that now you can follow along with the tutorial
by firing your
me-mold! I will try to write my next tutorial so that
you can run moldable-emacs on the tutorial itself. (Actually you can do
that already: there is a mold
OrgAsTree that could be interesting to
And the fun bit is that also my blog posts are written in Org Mode...
A world of interactivity awaits us!