Consider literate programming

[Luis-Henriquez-Perez]

I noticed that you already have all your code in one large file. I also noticed that one of Radian's goals is extensive documentation. Making Radian an org configuration may make it easier to find things in Radian (with headings). Additionally, it would provide new ways to document your code (like tags or descriptions under headings).

If speed is a concern, I think the speed of Radian could be maintained with creating your own custom tangling function (the default is slow) and tangling in kill-emacs-hook' only whenradian.el' has been modified.

What do you think?

[raxod502]

Radian already has headings:


Could you elaborate on what "tags or descriptions under headings" would look like, and what they would add?

Currently, I'm pretty strongly against Org for my code. I don't see it as an improvement to read my configuration outside of Emacs, and I view it as infinitely easier to edit my configuration when I don't have to deal with all the Org syntax, which I find pretty disgusting. Plus, it introduces a huge amount of additional complexity with respect to tangling and such (I can't always rely on kill-emacs-hook being run, for example).

Why not just document code the way it's always been documented, by means of comments and good organization?

[Luis-Henriquez-Perez]

It's up to personal preference. If you're very strongly opposed to it then stick with what you have. I only suggested it because I wanted to offer you an idea you might find interesting and because I though you veering towards that direction anyway.

I will speak a bit about my experience:

Having my code in headings helps me instantly know where code concerning a certain topic begins and end. This has a few consequences. First, knowing this I can trivially narrow code to a particularly region of interest with `org-narrow-to-block'. Additionally, I can exploit this to debug or disable or in general perform some action on a certain part of my configuration.

I use tags to disable sections of my code. For example I have a :DISABLED: tag all code beneath any subheadings is disabled. This has helped me a lot with debugging. When I have a bug I would disable almost all my modules (or enough so the bug wouldn't show up) and re-enable them one by one until I saw the bug show up again. Simple but very effective.

There is also potential with org block switches. I elaborate:

Something I disliked a lot in my code is seeing forms wrapped around other forms that didn't change an inner forms functionality. For example:

(eval-after-load 'evil --some-code--)

eval-after-load will change when --some-code-- happens but what --some-code-- does is the same. I want what my code actually does to be the first thing I understand when reading my code, and when it is executed or if it's debugged to be secondary. I want to be aware about the presence of eval-after-load but I don't want the visual distraction of it wrapping my code around a form.

To do this I added a functionality for org block switches.

Switches can wrap their corresponding block with expressions upon tangling. For example:

+begin_src emacs-lisp :after org

(message "hi")

+end_src

would tangle to (eval-after-load 'org (message "hi").

Something that I'm planning to implement actually is automatically tangling blocks with `condition-case' blocks that tell me the exact heading where I got an error. This is possible because my code is already neatly divided in source blocks.

As for the syntax, I agree with you that I don't find it very visually appealing. Well at least the +#begin_src stuff. but that can be improved with prettify-symbols-mode.

I won't lie and say it will not require more initial work than just having a plain elisp configuration. Though, I do think after the initial work it get easier.

[raxod502]

That's interesting; thanks for your perspective. I don't think I'll take things in this direction, but I appreciate the ideas.