Org Template for Specification Documents

Karsten Schmidt published a really nice template for producing great looking specification documents. The result looks like this. Here is the Org document that produced that output. The whole project, including the CSS style sheet is on GitHub.

You may or may not be interested in producing specification documents but the template is valuable regardless because of the many techniques that it demonstrates. For example, the Changes since last version section is generated automatically from the git commits since the last version.

All the diagrams are generated on-the-fly using Org-babel. One nice feature is that the styles for the diagrams are specified separately from the content of the diagrams using literate programming techniques (see the Diagram definitions section in the Org file). That means that if you have multiple, say, dot diagrams, they will all have the same style features and that if you want to modify the style you can do it in one place for all the graphs.

If you read the exported HTML document along side the Org document carefully, you will almost certainly learn some valuable tricks. If your CSS skills are as poor as mine, reading over the style sheet will also show you some nice techniques.

The template puts me in mind of the AT&T memorandum cover sheet that Troff produced (here’s an example). All that boiler plate on the first page is generated automatically much like a great deal of Schmidt’s document is generated automatically from the input text. You can easily adapt this template for use in whatever recurring documents you produce so it will more than repay the study you devote to it.

Posted in General | Tagged , | Leave a comment

Searching all Opened Buffers

Abo-abo has a post on swiper-all that everyone using swiper should read. It turns out that there’s a command called swiper-all that will perform the swiper search on all opened buffers. That is, on all buffers associated with a file. That’s a tremendously useful facility and if you have swiper installed you already have it. You can call it with 【Meta+xswiper-all or, if you think you’ll use it a lot, you can bind it to a key sequence.

If you aren’t a swiper user, take a look at Mike Zamansky’s video on searching with swiper to see how it works. You can also check out the swiper GitHub site and the documentation. I’ve been using it for about a month and really like it. Discovering swiper-all just makes it better.

Posted in General | Tagged | Leave a comment

Suggest

Wilfred Hughes has contributed a cute and potentially useful package that he calls suggest. The idea is that you’re looking for an Elisp function to perform a particular calculation or transformation but don’t know the function’s name. Suggest asks you for an input and the desired output and then suggests functions to accomplish that.

One example that Hughes offers is: given

2
2

with the desired output of

4

suggest offers

(+ 2 2)
(* 2 2)
(expt 2 2)

That’s pretty neat and almost seems like magic but really amounts to taking a list of functions and applying each one to the input(s) to see if it yields the desired result. Despite the brute force, Hughes says it almost always yields an immediate result.

There’s a bit more than just trying every function available though. For example, you have to be careful about side effects. As Hughes says, you don’t won’t to delete a file as a side effect when you’re testing prospective functions. Hughes has a curated list of functions that seems to work well. He says he’s already learned a couple of new functions from the app.

If you’re trying to learn Elisp, this may be a useful tool to get you started. Take a look at Hughes’ post to see if it might help you out. Regardless, it’s a neat hack and worth playing with just for the entertainment value.

Posted in General | Tagged | Leave a comment

How to Get Started in Security

Parisa Tabriz has a nice post on how to get started as a security engineer. She does mention some resources but the post is not really a check list of things you should do and sites you should visit. Rather, it is a series of observations based on her own career and how she landed a job at Google.

She starts by making the quotidian observation that it’s not like the movies. A lot of the work is like other engineering: detail oriented and often tedious. Still, she clearly loves her work and has a real enthusiasm for it.

She notes that there’s no standard curriculum and that the practitioners come from many different academic backgrounds. Her two best suggestions, I think, are

  1. Stop reading and get your hands dirty actually doing the work
  2. Write code; it will help you understand the problems that developers face trying to write secure code.

There are several other useful suggestions. If you’re interested in the field, it’s definitely worth taking a look at Tabriz’s post. After all, she’s a Security Princess.

Posted in General | Tagged | Leave a comment

New Zamansky Emacs Video Up

Mike Zamansky has posted the latest Emacs video in his series. This time it’s about flycheck. As usual, the video is from the point of view of how Zamansky himself uses Emacs.

The demonstration is mostly about using flycheck with Python because that’s the language that Zamansky uses most of the time but he also shows an example of using it with C. He points to the flycheck home page and the list of supported languages, which includes Elisp, of course.

I often see queries on how to set up a Python environment in Emacs. Zamansky discusses that a bit too but doesn’t cover Elpy because it’s more powerful than he needs. He does talk about Pylint, Flake8, and Jedi, though. If you’re looking for a Python environment, check out this video. Those of you who haven’t tried flycheck yet should check it out too.

Posted in General | Tagged | 1 Comment

The Emacs/Vi Holy War

I saw this tweet and it got me thinking.

The tweet is, of course, snark but it raises an interesting question. Does anyone still care about the holiest of holy wars? This tweet

suggests that some of us do but my sense is that Emacsers and Vimers are pretty much united against all the newcomers as exemplified by this tweet

I always get in trouble when I bring this up but I think it’s true that serious developers overwhelmingly prefer either Emacs or Vim. Of course there are exceptions. There are, I’m sure, thousands of excellent developers that use something else but mostly the great developers use Emacs or Vim.

The choice between the two depends on the developer’s outlook. If you want the fastest, most composable editor and are focused on simply editing text, you will probably prefer Vim. If, on the other hand, you want an environment that subsumes editing among other things, you will probably prefer Emacs.

My point, though, is that Emacsers and Vimers have pretty much moved from fighting each other to shaking their heads in disbelief about those engineers who are using one of those other editors. So perhaps the holy war isn’t over, it’s just move to another domain.

Posted in General | Tagged , | 2 Comments

Why Literate Programming: One Man’s Answer

Shane Cellos has a nice post on why literate programming makes sense. He tells the story of how he and an equally matched colleague worked on a relatively simple project. It was, he says, an ideal situation. One colleague with a similar technical background. What could go wrong?

You can read Celis’ post to see what went wrong but the TL;DR is that the code quickly diverged from the spec and only one of the researchers understood it. Celis suggests that using literate programming to document what the code is trying to do would have made the collaboration easier.

I’ve been coding so long that presenting code in its natural order seems like the right way to me so I don’t feel the need to document the code in an order different from what the compiler sees. That said, I think it makes a lot of sense to write a document explaining the code in which the actual code is embedded in the document.

Of course, this is ideally suited for Org mode, which is what I would use, but others may find another method better. Regardless, we should all consider how literate programming can enhance our workflow. See Howard Abrams posts on Literate Devops for a fine example of this.

Posted in General | Tagged , , | Leave a comment

Emacs Gifs

I just came across a twitter feed that some of my fellow Emacsers may find useful. Each tweet on the Emacs Gifs feed is a small animated gif that illustrates a feature of Emacs. Some examples are sorting lines, searching with swiper, Dired write mode, iedit, and others.

My problem with this sort of thing is that I find it really difficult to follow animations without an audio track. That’s just me, of course, and I know many of you like and learn from things like this. If you’re one of those people, you should definitely check out the feed. The above link will take you to the feed whether or not you are on twitter. If you are on twitter and like what you see, you can follow the feed and get regular updates. If you aren’t on twitter, you can check the website at your leisure and get the same goodness.

UPDATE [2016-07-26 Tue]: Gigs → Gifs

Posted in General | Tagged | Leave a comment

Trackers

This is why you should be using Ghostery or something similar:

Posted in General | Tagged | Leave a comment

Guile

I haven’t written much about Scheme lately because I wasn’t able to get Guile to compile on my Macs. Today I saw this nice video of Andy Wingo talking about building programs with Scheme and Guile. He discussed the current Guile system and some of his plans for the future. It’s a bit less than 40 minutes and worth a watch so if you have any interest in Scheme, I recommend it.

Watching the video inspired me to try compiling Guile again so I downloaded the latest stable source and gave it a go. Of course there were a bunch of GNU libraries that weren’t on my OS X system so I had to hunt them up and get them installed but that wasn’t much trouble. After that, the configure completed and I was able to compile and install Guile. I brought it up to make sure it was working but I haven’t done anything with it yet. I’ll write about it a bit more when I’ve had time to play with it.

If you’re on a Mac and gave up on Guile because you couldn’t get it to compile, now’s a good time to try it again.

Posted in General | Tagged | Leave a comment