Journal

2017-12-04 Embedding files in Org-mode

A few days ago, there was a question on the help-gnu-emacs mailing list about a way to embed an image in a text file. Of course, the OP was instantly pointed to Org-mode. However, this does not quite do what he wanted: while you can have attachments/links to images in Org, you then need two files instead of one.

This being Emacs and Org-mode, there exists an (at least partial) solution. You can use a code block and put some Elisp code recreating the image (or any file, for that matter) in there. Here’s one way how to do it.

(defun org-insert-file (filename)
  "Insert Elisp code block recreating file named FILENAME."
  (interactive "f")
  (let ((base64-string
	 (with-temp-buffer
	   (insert-file-contents-literally filename)
	   (base64-encode-region (point-min) (point-max))
	   (buffer-string))))
	(insert (format "#+BEGIN_SRC emacs-lisp :results output silent\n  (with-temp-file %S\n    (insert (base64-decode-string\n      %S)))\n#+END_SRC" filename base64-string))))

You can now call org-insert-file somewhere in your Org-mode buffer (preferably with point at the beginning of a line), choose the file and in a second you have your source block. Too see how it works, change the filename in the beginning of that code and press C-c C-c with point on your newly created source block. You may be asked whether you are sure you want to run it – answer yes, and in another second the file is recreated under the given name.

One drawback is that this does not look very pretty in your Org-mode file. See this Emacs.SE answer for some help. Another is that you need to explicitly evaluate this source code block with C-c C-c. This is actually for your own good (security-wise), but see here for a way to automate this, too.

As usual, it turns out that Emacs and Org-mode are extremely flexible and can do a lot of stuff. Not that I’m surprised;-).

CategoryEnglish, CategoryBlog, CategoryEmacs, CategoryOrgMode

Comments on this page

2017-11-27 Org-mode radio targets

One of the interesting features of Org-mode is hyperlinks. For some documents, having many internal links makes a lot of sense. One of these types is mathematical papers: you often want to refer to “Theorem 2.1” or “Definition 3” or “equation (5)”. LaTeX has that pretty much solved (even core LaTeX, and then there are packages to help, like cleveref). Org-mode does not improve a lot on that, but it’s usually enough anyway.

But it’s not the topic of my post today. There are other kinds of documents where rich structure of internal links may be beneficial: game rulebooks. As a boardgamer, I tend to read quite a few of those, and sometimes they are a real PITA. Especially with American-style games, whose rulebooks are often one or two dozen pages long, and introduce a lot of concepts, even understanding (not to speak about memorizing!) the rules tends to be a daunting task. And one of the reasons is the fact that it is sometimes difficult to find the exact place where some concept is defined (even if the rulebook has an index, which is not always the case).

Some time ago it occured to me that if I rewrite a rulebook in Org-mode (probably shortening or reformulating it), that might both help me understand and memorize the rules and remind myself about them later, when I get back to the game after a long break. A lot of links to places where various concepts are introduced might help with that, too.

And then I recalled something I only vaguely remembered from my reading of the Org-mode manual a few years ago: radio targets. The idea is quite cool: you mark some word (or a combination of words) in your Org-mode file, and then every occurrence of this particular word or combination of words becomes a link to the marked one. Go to the relevant node in the Org manual for the details; let me just note here that radio targets are case-insensitive (this is implied but not mentioned explicitly by the manual). And it is especially cool that exporting (to HTML or LaTeX) preserves these links.

I am pretty sure that radio targets may be useful in many contexts other than boardgame rulebooks. The only downside I can see is that there is a possibility of having too many links, which is usually not desirable, so you have to consider each case separately. But this is obvious with many things anyway.

CategoryEnglish, CategoryBlog, CategoryEmacs, CategoryOrgMode

Comments on this page

2017-11-19 How to trip up yourself using Git

Everyone and their mother seem to be using Git these days. And I have to admit that it is really a clever piece of code. However, sometimes it may not work like you want it to do. Let me share a personal story.

Assume we have this piece of code.

if (1 > 0) {
	if (2 > 1) {
		console.log('2 is greater than 1.');
	} else {
		console.log('Something is wrong!');
	}
} else {
	console.log('Something is really wrong!');
}

Not that it makes a lot of sense, but let us commit it to our repo anyway:

git init
git add git-trip-up.js
git commit -m "Initial commit"

Now assume that we want to add something to both then- and else-branches of the outer if:

if (1 > 0) {
	console.log('1>0');
	if (2 > 1) {
		console.log('2 is greater than 1.');
	} else {
		console.log('1<=0');
		console.log('Something is wrong!');
	}
} else {
	console.log('Something is really wrong!');
}

Being a nice programmer, we do it on a separate branch. Having a moment of stupidity, we do it wrong (the second console.log is in the wrong else-branch).

git checkout -b new_branch
git commit -am "Bad commit"

We make a PR, and it accidentally gets merged. Then the team leader notices that something went wrong, reverts the merged commit and tells the author that he screwed up.

git checkout master
git merge new_branch
git revert --no-edit HEAD

The author fixes that on his branch.

git checkout new_branch
if (1 > 0) {
	console.log('1>0');
	if (2 > 1) {
		console.log('2 is greater than 1.');
	} else {
		console.log('Something is wrong!');
	}
} else {
	console.log('1<=0');
	console.log('Something is really wrong!');
}

Then he wants to make sure that there are no conflicts, and merges master into feature-branch. Boom! The console.log('1>0'); magically disappeared!

git commit -am "Fix a stupid mistake"
git merge --no-edit master

Well, of course this is not unexpected in technical terms. But the workflow seems reasonable, merging does not actually signal any conflicts, so one might think everything is fine.

I don’t know how to prevent such mistakes, other than being alert. So be alert when merging things that involve reverting. Probably.

CategoryEnglish, CategoryBlog, CategoryGit

Comments on this page

More...