Irreal

If you’re a Python programmer and like to have built-in tests for your functions, you probably know about doctest, a way of embedding one or more tests in the docstring of a Python function. Normally, they don’t do anything but if doctest is loaded as the main program or one of doctest’s methods are called, the tests are run and the results are printed to stdout.

John Kitchin likes the idea but found that the nit-picky formatting of the tests was annoying so he didn’t use them very often. Of course, being Kitchin he soon fixed that and in a clever way that leverages Org mode. Rather than fuss with the formatting of the tests, he just put a noweb marker where he wanted the test to be and then included the test as a normal Org mode code block later in the file. He added in a bit of Elisp to reformat the test code so that when the file is tangled it becomes a Python script that can be invoked in the normal way to run the tests.

Kitchin thinks of this as an example of literate programming, which it is, of course, but I prefer to think of it as another example of the power of embedding code in an Org file. The function tests can be run from the Org file to get the expected results for the tests, explanatory text can be added, and when you’re finished you just tangle it to an output file. That file can be invoked as a script to run the tests or imported into another Python file to access the functions in the normal way. Very impressive. Kitchin’s post includes a short video so you can see the system in action and get a better feel for how things work.

The other day in my post about Alain Lafon’s talk on playing Emacs like an instrument—you have watched that video, haven’t you?—I mentioned that one of the things I picked up was an Org capture template for capturing code snippets. That’s very nice and just the thing when you want to put some code in a journal or log entry.

Right after seeing the video, I saw a post from Nick Barnwell that had an even better template for capturing code snippets. His template automatically captures the language for the code block, and the file and line number from which the code is being extracted. That minimizes the amount of text that you have to enter manually.

You may have to autoload which-function if you aren’t already using something like which-function-mode. Also note that the template is assuming you’re going to be grabbing the code snippet from a file you have open in Emacs. That’s probably almost always true for a capture template of this type.

When I first started using capture templates, they were described as a way of quickly recording a note or thought while you were busy with something else and then getting back to the job at hand. That’s still true, of course, but I find that they’re just as useful for entering data related to your current task. For example, when I’m reading an article that I’m considering writing about on Irreal, I capture a link to the article and any thoughts I have about it with a template that adds the information to my blog queue. Once you start using capture templates, you keep finding new uses. Barnwell’s post is another example of that.

Wilfred Hughes serves up some useful advice for those just starting out with Org mode:

It's too easy to get excited about time tracking, tags, and literate programming when starting out with org-mode. It has a huge featureset.

I'd encourage new users just to treat it as a better markdown-mode, and learn about folding and links, before diving in to the rest.

— Wilfred Hughes (@_wilfredh) April 28, 2018

I’ve given this same advice before but it’s worth repeating. Org mode is a huge and complex package with many capabilities. If you try to learn everything at once, you’ll get discouraged and possibly even abandon Org.

That was certainly my experience. When I first started, I used Bernt Hansen’s excellent Org Mode – Organize Your Life In Plain Text! as a guide and tried to configure everything at once. The result was that I didn’t understand anything and mostly didn’t use Org at all. When I started over, I configured only a small subset of the capabilities and got familiar with them through repeated use. Later, I added more functionality as I found new ways to use Org in my workflow. That process is still going on even though Org mode is at the center of most things I do on my computer.

Do yourself a favor and start with just a couple of Org’s capabilities. You’ll have much better results that way.

As you all know, I’m fond of posts that show the versatility of Emacs by documenting its use by writers. At first glance, writing—a novel, say—seems to be the direct antithesis of what most of us use Emacs for. But when you think of it, it’s all just wrangling text and we all want to do that in the most efficient way possible. That’s were Emacs comes in.

Scott Nesbitt has a nice post entitled 5 Emacs modes for writers. Those five modes are:

1. Muse,
2. Org mode,
3. Flyspell,
4. WC mode, and
5. WriteGood mode.

I depend on three of the five. I use Org mode for virtually all of my writing these days so I don’t need Muse. Applications like WriteGood mode remind me of my eighth grade English teacher so I avoid them for admittedly emotional reasons. I use a different app for word counting—also called WC mode—but either one will serve. Any or all of these tools will make whatever writing you do easier.

Nesbitt also mentions Fountain mode (if you’re doing screen manuscripts), Markdown mode (if you prefer Markdown or have to use it in some instances), and Writeroom mode (if you want to write on a blank screen). Years ago, Jerry Pournelle used to sing the praises of an editor called (I think) WRITE. It was for CP/M and would doubtless be considered primitive today but it had the virtue of being distraction-free by offering a blank screen with no tool bars or other widgets to seduce your attention. If that sounds attractive, give Writeroom a try.